Usage billing API
Every usage billing route on the Comecero API, grouped by resource, with who may call it and a link to its full page in the API reference.
The usage billing routes are on https://api.comecero.com/api/v1. Call them from your server with a secret token in the Authorization: Bearer header. Limited tokens can not call them, except Get a customer's usage this period, which a shopper's token may call for its own customer.
A test token reads and writes test objects only, and a live token live objects only. Until Comecero turns usage billing on for your account, the routes answer 403 with the code usage_billing_off. Listing and revoking usage keys still work then.
Sending usage events is not on this API. Your server sends them to the usage meter with a usage key: see the Usage meter API.
Usage metrics
What you count and bill for, such as API calls or AI tokens, and how the events add up.
| Route | Method and path |
|---|---|
| Create a metric | POST /usage/metrics |
| List metrics | GET /usage/metrics |
| Get a metric | GET /usage/metrics/{metric_id} |
| Create or replace a metric | PUT /usage/metrics/{metric_id} |
Usage rate plans
The price of a metric: an included allowance, a price per unit, packages or tiers. Each version is fixed once saved.
| Route | Method and path |
|---|---|
| Create a rate plan version | POST /usage/rate_plans |
| List rate plans | GET /usage/rate_plans |
| Get a rate plan version | GET /usage/rate_plans/{rate_plan_id}/versions/{version} |
Usage agreements
Link your own id for a customer to their Comecero subscription, and read their usage so far.
| Route | Method and path |
|---|---|
| Create or update a billing agreement | POST /usage/agreements |
| List billing agreements | GET /usage/agreements |
| Get a billing agreement | GET /usage/agreements/{agreement_id} |
| Get usage this period so far | GET /usage/agreements/{agreement_id}/current |
| List an agreement's entitlements | GET /usage/agreements/{agreement_id}/entitlements |
| Find a customer's subscription | GET /usage/subscription_context |
Usage entitlements
Put a metric and price on an agreement, or hold prepaid credit, and read the balance.
| Route | Method and path |
|---|---|
| Create or update an entitlement | POST /usage/entitlements |
| Get an entitlement | GET /usage/entitlements/{entitlement_id} |
| Get an entitlement's balance | GET /usage/entitlements/{entitlement_id}/balance |
| Add prepaid credit | POST /usage/entitlements/{entitlement_id}/credits |
Usage keys
The keys your server uses to send usage events to the usage meter.
| Route | Method and path |
|---|---|
| Create a usage key | POST /usage/keys |
| List usage keys | GET /usage/keys |
| Revoke a usage key | POST /usage/keys/{usage_key_id}/revoke |
Usage billing runs
One billed period of one agreement, with the invoice its usage is on.
| Route | Method and path |
|---|---|
| List an agreement's billing runs | GET /usage/agreements/{agreement_id}/runs |
| List bills that need attention | GET /usage/attention |
| Get a billing run | GET /usage/runs/{billing_run_id} |
Usage
Read usage totals and the events behind them.
| Route | Method and path |
|---|---|
| Read counted usage | GET /usage/summary |
| List a customer's events | GET /usage/events |
| Get a customer's usage this period | GET /customers/{customer_id}/usage |
Webhook
Usage threshold reached (usage:threshold_reached) fires when a customer passes 50%, 80% or 100% of an included allowance. See usage alerts.
Usage meter API
The one usage meter route your server calls. Send usage events to POST /v1/events with a usage key, and read every field, answer and status code.
Reports and analytics
MRR, churn, sales, card approval, storefront visits and usage for your shop, in the dashboard, the API and Claude, with what each number means.