comecerodocs
Usage billing

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.

RouteMethod and path
Create a metricPOST /usage/metrics
List metricsGET /usage/metrics
Get a metricGET /usage/metrics/{metric_id}
Create or replace a metricPUT /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.

RouteMethod and path
Create a rate plan versionPOST /usage/rate_plans
List rate plansGET /usage/rate_plans
Get a rate plan versionGET /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.

RouteMethod and path
Create or update a billing agreementPOST /usage/agreements
List billing agreementsGET /usage/agreements
Get a billing agreementGET /usage/agreements/{agreement_id}
Get usage this period so farGET /usage/agreements/{agreement_id}/current
List an agreement's entitlementsGET /usage/agreements/{agreement_id}/entitlements
Find a customer's subscriptionGET /usage/subscription_context

Usage entitlements

Put a metric and price on an agreement, or hold prepaid credit, and read the balance.

RouteMethod and path
Create or update an entitlementPOST /usage/entitlements
Get an entitlementGET /usage/entitlements/{entitlement_id}
Get an entitlement's balanceGET /usage/entitlements/{entitlement_id}/balance
Add prepaid creditPOST /usage/entitlements/{entitlement_id}/credits

Usage keys

The keys your server uses to send usage events to the usage meter.

RouteMethod and path
Create a usage keyPOST /usage/keys
List usage keysGET /usage/keys
Revoke a usage keyPOST /usage/keys/{usage_key_id}/revoke

Usage billing runs

One billed period of one agreement, with the invoice its usage is on.

RouteMethod and path
List an agreement's billing runsGET /usage/agreements/{agreement_id}/runs
List bills that need attentionGET /usage/attention
Get a billing runGET /usage/runs/{billing_run_id}

Usage

Read usage totals and the events behind them.

RouteMethod and path
Read counted usageGET /usage/summary
List a customer's eventsGET /usage/events
Get a customer's usage this periodGET /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.

On this page