Usage billing and credits
Meter what customers use, set entitlements, sell prepaid credit and bill usage on the subscription's renewal invoice, with the API or the dashboard.
Usage billing charges a customer for what they use: API calls, AI tokens, storage, seats, messages, or anything else your app can count. Your app sends usage events to the Comecero usage meter. When the customer's subscription renews, Comecero adds up their usage for the period that just ended, takes off what their plan includes and any prepaid credit, prices the rest and usually puts it on the renewal invoice, next to the plan's price for the period ahead. The invoice is charged with the customer's saved payment method, as every renewal is.
It works with the subscriptions you already sell on Comecero. A customer pays one invoice each billing cycle: the fee for their plan and the usage above what the plan includes.
What you get
| Feature | What it does |
|---|---|
| Usage metering | Send events from your server in batches of up to 1,000. A resend of the same event is never counted twice. Late events up to 30 days old are still billed. See Send usage. |
| Metrics and aggregations | Define what you count and how it adds up: sum (total used) or gauge (highest hourly level). See Metrics and aggregations. |
| Rate plans | Price a metric with an included allowance and a price per unit, per package, or in volume or graduated tiers. Each version is fixed once saved. See Set a price. |
| Entitlements | Put a metric on a customer at a pinned price version, with an overage policy: charge the overage, or stop at a hard limit. See Entitlements. |
| Credits and burndown | Sell prepaid credit. Usage is paid from the included allowance first, then from credit, and only then charged. See Credits and burndown. |
| Subscription billing | Usage periods follow the subscription's renewals. Each period's usage usually goes on the renewal invoice and is charged with it. See Usage with subscriptions. |
| Safe invoices | Usage that can't go on a renewal gets a separate usage invoice, and small amounts wait for the next invoice. Unusually large usage is held, and nothing is charged until Comecero has checked it with you. See How usage is billed. |
| Usage so far and alerts | Show usage for the current period in your app, on the shopper's account page and in the dashboard. Get a usage:threshold_reached webhook at 50%, 80% and 100% of an allowance. See Follow usage. |
| Comecero Express Payments | When your account sells through Comecero Express Payments, usage is charged through it like every other sale. See Merchant of record. |
Comecero turns usage billing on for each account. Until it is on, the /api/v1/usage routes answer 403 with the error code usage_billing_off ("Usage billing is not turned on for this account. Ask Comecero to turn it on."). Only listing and revoking usage keys still work. GET /api/v1/customers/{customer_id}/usage answers an empty list instead of an error.
How it works
- Your app counts. Each time a customer uses something, your server sends an event to the usage meter, for example "customer
cust_8412used 1,250 AI tokens". - The meter adds it up. Events are counted by customer, metric and UTC hour. A resend of the same event is never counted twice.
- Comecero bills each period. When the customer's subscription renews, Comecero reads the period's usage, takes off the included allowance, prices the rest with the rate plan version the customer is on, then takes the price from prepaid credit.
- The customer pays. What is left goes on the renewal invoice, next to the plan's price, and is charged with the customer's saved payment method.
How the pieces fit
| Object | What it is |
|---|---|
| Metric | What you count, for example ai_tokens. Its event_key is the metric_key your app sends. It adds events up (sum) or keeps the highest hourly reading (gauge). |
| Rate plan | The price of a metric, in one currency. Each version is fixed once it is saved. |
| Billing agreement | Links your own id for a customer to one of their Comecero subscriptions. Usage is invoiced to that subscription's customer, in its currency. |
| Entitlement | Puts a metric and a pinned rate plan version on an agreement (metered), or holds prepaid credit for the agreement (credit). |
| Credit | Money added to a credit entitlement. Metered entitlements of the same agreement can draw on it when a period is billed. |
| Usage key | Lets your server send events to the usage meter. Starts with apk_live_ or apk_test_. |
| Usage event | One thing that happened, for example "customer cust_8412 used 1,250 tokens". |
| Billing run | One billed period of one agreement, with the invoice its usage is on. |
Your server never calls the usage meter with a Comecero API token. You set things up with the Comecero API (https://api.comecero.com/api/v1/usage/...) and a secret token. You send events to the usage meter (https://usage.comecero.com/v1/events) with a usage key.
The meter counts events for any external_customer_id. Usage is billed only when that id is the customer_id of a billing agreement. Events for any other id are counted but never billed.
Before you start
- Ask Comecero to turn on usage billing for your account.
- Call the
/api/v1/usageroutes from your server with a secret token. The dashboard uses a trusted token. Limited (shopper) tokens can't call them. The token needs permission on the resources the routes use:metrics,rate_plans,billing_agreements,entitlement_grants,entitlement_balance_snapshots,entitlement_ledger_entries,billing_runsandusage_keys. - Each customer you bill for usage needs a subscription in Comecero. Usage goes on its renewal invoices and uses its currency.
- Test first. A test token makes test objects and
apk_test_usage keys, and test usage is only billed to test agreements.
Set it up in the dashboard
Go to Usage Billing in the sidebar. It has five tabs: Overview, Customers, Prices, Metrics and Usage keys. The Overview tab has a checklist that walks you through the setup: add a metric, set a price, bill a customer for usage, create a usage key, and send usage from your app. Every pricing model (per unit, per package, tiered, volume and stair-step) can be set up there.
Set up usage billing in the dashboard walks through every screen, with pictures.
Steps
Ask Comecero to turn on usage billing.
Create a metric for each thing you count.
Create a rate plan for each metric.
Create a billing agreement for each customer's subscription.
Add entitlements to the agreement, and prepaid credit if you sell it.
Create a usage key for your server.
Send usage from your app.
Want it all in one script? The Quickstart does every step in Node.js. Every route is in the API reference, starting with Create a metric. Sending events is in the Usage meter API.
Billing regions
Every metric, rate plan, agreement and entitlement has a billing_region: us (the default), uk or eu. The objects of one agreement must all use the same region. Reading a billing run or a balance looks in us unless you pass ?billing_region= in the query string, and answers 404 when the region does not match.
Fraud screening
What Comecero checks before a card or wallet payment goes to the bank, what a blocked payment returns, trusted customers, and how to test a fraud block.
Quickstart
Set up usage billing for one customer in test mode and send their first usage events, then read usage so far, in short Node.js scripts.