comecerodocs
Usage billing

Usage with subscriptions

Sell a plan with a monthly fee and usage on top. How usage follows the subscription through renewals, plan changes, cancellations and failed payments.

Usage billing is built on Comecero subscriptions. You keep selling plans the way you do today, and usage is billed on the same cycle, usually on the plan's renewal invoice. This is often called hybrid pricing: a fixed fee plus pay for what you use.

A hybrid plan, start to finish

Say you sell Pro at 49 USD a month, with 1,000,000 AI tokens included and 0.00002 USD per token after that.

You set upWith
The 49 USD monthly planA normal subscription plan and product, sold through your shop or the API. See the subscriptions guide.
What you countA sum metric ai_tokens.
The price of usageA rate plan with included_allowance 1,000,000 and overage_price 0.00002, in USD.
The link to the customerA billing agreement for their subscription, plus an entitlement for ai_tokens on the rate plan.

Each month, the customer gets one renewal invoice with:

  1. The plan: 49 USD for Pro, for the month ahead.
  2. The usage: for the month that just ended. With 1,400,000 tokens used, it is 400,000 × 0.00002 = 8.00 USD, so the invoice comes to 57.00 USD. With 900,000 tokens, nothing is owed for usage and the invoice is just the 49 USD.

How usage follows the subscription

  • Same periods. A usage period ends at the subscription's next renewal. The first one starts at the hour of the agreement's effective_from.
  • Same customer and currency. Usage is billed to the subscription's customer. The agreement's currency must be the subscription's currency.
  • On the renewal invoice. When the subscription renews, the usage of the period that just ended is added to the renewal invoice, next to the plan's price for the period ahead.
  • The renewal never waits. A renewal is never held back or failed because of usage. Usage that reaches the usage meter after the renewal is made is billed as late usage on the next invoice.
  • Late usage is not lost. Events up to 30 days old are billed on the next invoice, as a "late usage" line at the price of the period they belong to.
  • A separate usage invoice only when needed. When usage can't go on a renewal, for example the period ended without one because the subscription was cancelled, or the usage meter could not be reached when the renewal was made, it goes on a usage invoice of its own, made by the hourly usage billing job. See The separate usage invoice.

Payments

The renewal invoice, usage included, is charged automatically with the customer's saved payment method, after the invoice payment delay in your subscription settings if you set one.

  • The invoice is paid as one. If the payment is declined, it is retried as a renewal is. If it is never paid, the subscription is cancelled as usual, and the usage on it moves to a separate usage invoice, because it is still owed.
  • A separate usage invoice is charged the same way, when the customer has a saved payment method that can be charged automatically. A declined payment is retried on the same schedule as a renewal. On the first decline the customer is emailed the invoice with a Pay Invoice Now link. A failed payment on a separate usage invoice never cancels the subscription.
  • A separate usage invoice is only made from 1.00 USD (or the same in the invoice currency). Smaller amounts wait and join the next invoice. Usage on a renewal invoice has no minimum.
  • Unusually large usage is held until Comecero has checked it with you, so a bug or a leaked key can't charge your customers. That is a total above 5,000 USD, or more than 10 times the agreement's last usage bill. Once Comecero releases it, it is billed on a separate usage invoice.

See How usage is billed for every rule.

Plan changes

An upgrade or downgrade changes the price of usage from a given hour, and never changes hours already billed.

  • Same agreement, new price: end each metered entitlement at the hour of the change with effective_to, and create new ones with the new rate_plan_version that start at that hour.
  • New agreement: end agreement A with effective_to at an hour, and start agreement B at the same hour. Only one agreement for a customer_id can cover any hour.

With new entitlements on the same agreement, the period that holds the change is billed in two parts, each at its own price. For a sum metric the two parts share one included allowance and one count: the new entitlement gets what is left of the allowance, and its tiers carry on from the usage before it, so a stair-step period never pays two brackets for usage that fits in one. Each gauge entitlement keeps its own full allowance. A new agreement starts its own count.

To bill all usage not billed yet at a new price instead, send the entitlement again with the new rate_plan_version, or use Change price in the dashboard.

Cancellations and the end of a plan

  • When the subscription is cancelled or completes, its usage stops being billed at that point. The last period ends without a renewal, so it is billed on a separate usage invoice by the hourly job.
  • Usage that arrives late for the ended plan is still billed: about 31 days after the last period, one final pass bills it and the agreement's status becomes ended.
  • The last invoice of an agreement is always made, even under the 1.00 USD minimum.

What the shopper sees

On their account in your shop, under Subscriptions, a customer sees Usage this period for each plan billed by use: each metric with what they used, what the plan includes, and a bar showing the percent used. It shows no prices: the invoice says what is owed.

Your own app can show the same with Get a customer's usage this period (GET /api/v1/customers/{customer_id}/usage). Here customer_id is the Comecero customer id, not your own id from the agreement. A shopper's token reads only its own customer (me works too), and a secret token can read any customer. See Follow usage.

Merchant of record

Usage is charged through the same payment setup as your renewals, because it is usually on the renewal invoice itself. When your account sells through Comecero Express Payments, usage goes through it like every other sale. A separate usage invoice gets its settlement currency and exchange rate source the same way a renewal does. Its 1.00 USD minimum is the Comecero Express Payments minimum sale.

Nothing changes in your code: the same usage events and the same setup work whether you sell through Comecero Express Payments or through your own payment gateway.

Test mode

Test subscriptions get test agreements, test usage (from apk_test_ keys, for metrics made in test mode) and test invoices, charged with test payment methods. Run a whole billing period in test mode before you go live.

On this page