comecerodocs
Usage billing

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

FeatureWhat it does
Usage meteringSend 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 aggregationsDefine what you count and how it adds up: sum (total used) or gauge (highest hourly level). See Metrics and aggregations.
Rate plansPrice 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.
EntitlementsPut 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 burndownSell prepaid credit. Usage is paid from the included allowance first, then from credit, and only then charged. See Credits and burndown.
Subscription billingUsage 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 invoicesUsage 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 alertsShow 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 PaymentsWhen 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

  1. Your app counts. Each time a customer uses something, your server sends an event to the usage meter, for example "customer cust_8412 used 1,250 AI tokens".
  2. The meter adds it up. Events are counted by customer, metric and UTC hour. A resend of the same event is never counted twice.
  3. 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.
  4. 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

ObjectWhat it is
MetricWhat 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 planThe price of a metric, in one currency. Each version is fixed once it is saved.
Billing agreementLinks your own id for a customer to one of their Comecero subscriptions. Usage is invoiced to that subscription's customer, in its currency.
EntitlementPuts a metric and a pinned rate plan version on an agreement (metered), or holds prepaid credit for the agreement (credit).
CreditMoney added to a credit entitlement. Metered entitlements of the same agreement can draw on it when a period is billed.
Usage keyLets your server send events to the usage meter. Starts with apk_live_ or apk_test_.
Usage eventOne thing that happened, for example "customer cust_8412 used 1,250 tokens".
Billing runOne 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/usage routes 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_runs and usage_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.

On this page