Monthly revenue & unbilled usage
Every subscription read returns monthlyRevenue: what the subscription bills
per month today. Metered consumption is not part of that figure, so a separate
endpoint returns the usage recorded so far in the current billing period. Use
the two together to report MRR and to estimate the next invoice.
monthlyRevenue
GET /v1/subscriptions and GET /v1/subscriptions/{id} return
monthlyRevenue (a decimal string), currency and hasMeteredProducts. Each
add-on in a subscription's addons array carries its own monthlyRevenue.
Code
| Question | Answer |
|---|---|
| Is VAT included? | No. The figure is computed from the same net line amounts an invoice adds VAT to. |
| Is it per month when billed quarterly or yearly? | Yes. Each billing interval is converted to one month: a quarter is divided by 3, half a year by 6, a year by 12, and weekly prices are multiplied by 52/12. |
| Are discounts applied? | Yes. Plan discounts, interval discounts and recurring surcharges are applied. |
| Are one-off charges included? | No. A setup fee or other one-off charge is billed once. |
| Are add-ons included? | No. Each add-on is its own subscription with its own monthlyRevenue and appears as its own row in the list. The invoice a parent sends carries its own figure plus its add-ons', so adding up every subscription counts nothing twice. |
| Is usage-based consumption included? | No, because it is not known until the period closes. A metered line counts only through a prepaid commitment (the committed quantity at its committed price) or a fee its price charges at zero usage. Read unbilled usage for the rest. hasMeteredProducts says whether the subscription has a metered product. |
| Which date does it describe? | Today. A change scheduled for a later date shows from the day it takes effect. |
| Does a catalog price change move it? | Not by itself. A running subscription keeps billing the price it has. When a change to the subscription takes effect, its lines bill at the catalog price of that day, except a line with a negotiated price, which bills that price. |
| What during a trial? | The price billing starts at when the trial ends. |
| What before the start date or after the end? | 0.00. A migrated subscription that was already billing in another system counts from its original start date. |
monthlyRevenue is in the subscription's currency, the currency it is
invoiced in. Convert to one currency before summing subscriptions in different
currencies.
Unbilled usage
GET /v1/subscriptions/{id}/usage returns the usage the subscription has
recorded but not yet been invoiced for, one entry per metered price and billing
period.
Code
Code
Usage is billed in arrears. A period's usage is invoiced when the period
closes, on periodEnd; until then amount grows as usage is reported.
amount is priced the way that invoice will price it:
- at the price the subscription is locked to, tiers included;
- excluding VAT;
- before plan and interval discounts, which appear on the invoice as their own lines;
- without usage that has already been invoiced;
- without usage recorded before a date you chose not to bill from.
For a line with a prepaid commitment,
amount is only the settlement: the usage above what was prepaid, or, when the
commitment refunds unused units, a negative amount for what was not used. The
prepaid commitment itself is part of monthlyRevenue, so the two never count
the same money.
Usage is recorded per customer and meter, not per subscription. When another
line bills the same meter (another price on this subscription, or another of
the customer's subscriptions), it reports the same units and
quantityIsShared is true. Amounts on such lines add up; quantities do not.
Pass asOf=YYYY-MM-DD to choose which billing period is current. A
subscription that is behind on billing can return more than one period for one
price. A subscription without metered products returns an empty lines array.
Reading usage needs the subscriptions-read scope and the Subscription
license. Reporting it is described in
Reporting usage. The full response
schema is in the API Reference.
Price changes by webhook
subscription.started carries the monthlyRevenue and currency the
subscription starts at. subscription.transitioned carries the figure the
subscription bills after the change, and effectiveDate:
Code
transitionedAt is when the change was made. For a change scheduled for a
later date it comes before effectiveDate; keep the current figure until that
date. On effectiveDate a phase_changed transition follows when the change
alters the monthly revenue or the entitlements. A change that takes effect the
day it is made sends one event.
A catalog price change sends no event by itself. For a change scheduled for a
later date, monthlyRevenue prices a line with no negotiated price at the
catalog price of the day the change was made. That line's price is set on
effectiveDate, and phase_changed carries the resulting figure when it differs
from what the subscription billed until then.
monthlyRevenue on a webhook is null only when the subscription could not be
priced; read the subscription to recover the figure. The full payloads are in
Webhooks, and reconciliation is in
Webhooks & reconciliation.
Errors & failure states
| What you observe | Cause | What to do |
|---|---|---|
404 SUBSCRIPTION_CUSTOMER_SUBSCRIPTION_NOT_FOUND | The id is not a subscription of the company the key belongs to | Use the stable id from the subscription list |
400 validation error on asOf | asOf is not a real YYYY-MM-DD date | Send a calendar date, e.g. 2026-10-01 |
403 with LICENSE.REQUIRED | Your company does not hold the Subscription license | See Licenses |
monthlyRevenue is 0.00 on an active subscription | Every product is metered and none has a commitment or standing fee | Read the usage endpoint |
quantity is higher than this subscription's usage | quantityIsShared is true: another line bills the same meter | Add up amount, not quantity |