Skip to main content
GET
Get revenue summary

Authorizations

Authorization
string
header
required

API key authentication

Query Parameters

startTime
string<date-time>
required

Start of the read window, included (ISO 8601 format)

endTime
string<date-time>
required

End of the read window, excluded: the read counts startTime <= t < endTime, so a month ends at the first instant of the next month (ISO 8601 format)

bucketWidth
enum<string>
default:day

Time bucket granularity for trend data

Available options:
hour,
day,
week
merchantId
string

The merchant whose revenue to read. Defaults to the merchant your API key belongs to, and is required when you belong to several merchants. Every read is scoped to one merchant; customerId and subscriptionIds narrow it further. Unique identifier for an organization

Pattern: ^org_[a-zA-Z0-9]+$
customerId
string

Narrow the read to one of the merchant's customers.

subscriptionIds
string[]

Narrow the invoice figures to some of the merchant's subscriptions. A payment is not tied to a subscription, so the payment figures are not narrowed by it.

currency
string

ISO 4217 currency code (e.g. 'USD') to scope every figure to. Defaults to the merchant's primary currency, except with groupBy=currency, where omitting it returns every currency.

Required string length: 3
groupBy
enum<string>

Group invoice data by dimension. Allowed values: 'plan' (max 5 groups, top 4 + 'other' when exceeding), 'customer' (max 25 groups, top 24 + 'other' when exceeding, sorted by revenue descending), both in one currency like an ungrouped read, 'currency' (one entry per currency, primary currency first then alphabetical). Note: groupBy values are mutually exclusive — combining them returns a 400 error. When groupBy=currency is active, top-level netRevenue, invoices, and payments fields are omitted; currencyBreakdown is the sole data source.

Available options:
plan,
customer,
currency
periodBasis
enum<string>
default:issued

Which date places revenue inside the window. 'issued' (default) counts whole invoices by their issue date, the basis revenue is recognised on. 'billingPeriod' counts invoice lines by the start of the period each line bills, so a window covering one billing period returns that period's charges, whichever invoices carry them: this month's advance fee and this month's arrears usage. Paid, outstanding and written-off follow each line's invoice; a refund splits across its invoice's lines by subtotal; payments not tied to an invoice are excluded because they bill no period.

Available options:
issued,
billingPeriod

Response

Revenue summary data

object
string
required

Object type identifier

Allowed value: "revenue_summary"
currency
string

ISO 4217 currency code every figure in the response is in: the requested currency, or the merchant's primary currency when none was requested. Omitted when groupBy=currency is active.

netRevenue
string

Revenue: what was billed in the period, excluding tax, in units of the currency. On the default issue-date basis it is recognised when each invoice is issued; with periodBasis=billingPeriod, each invoice line counts in the period it bills, and a refund splits across its invoice's lines. An invoice counts whether it was since paid, is still outstanding, failed payment or was written off, less non-voided refunds. It is billings, not cash collected: what customers still owe is invoices.outstanding, including tax, and payment-link collections are under payments. Omitted when groupBy=currency is active.

totalRefunds
string

Total of non-voided refunds (credit notes) issued in the period, in dollars, including tax. netRevenue subtracts these refunds excluding tax. Omitted when groupBy=currency is active.

refundCount
number

Number of non-voided refunds (credit notes) issued in the period. Omitted when groupBy=currency is active.

totalRebates
string

Gross total of usage-scaled rebates (negative metered line items) on invoices issued in the period, in dollars. Already netted into issued invoice grandTotals, so surfaced here for visibility. Omitted when groupBy=currency is active.

rebateCount
number

Number of rebate line items on invoices issued in the period. Omitted when groupBy=currency is active.

invoices
object

Invoice breakdown. Omitted when groupBy=currency is active.

payments
object

Payment breakdown. Omitted when groupBy=currency is active.

trend
object[]

Time-bucketed revenue trend data. Omitted when groupBy=currency is active.

groupBreakdown
object[]

Invoice breakdown by group dimension (only present when groupBy=plan or groupBy=customer is specified)

currencyBreakdown
object[]

Per-currency revenue aggregates (only present when groupBy=currency is specified). Primary currency appears first, then alphabetical by ISO code. When present, top-level netRevenue, invoices, payments, and trend fields are omitted.

revenueRange
object | null

Where the caller's revenue actually lies in time. Scoped by the same filters as the request (merchant, and where given customer, subscription and currency), so it is not an account-wide statement. Present only when the selected range returned nothing. An object carries the bounds of the real revenue; null means no revenue under these filters at any time; an absent field means the extent was not resolved, because the result was not empty or because the lookup failed. An absent field must never be read as an absence. The bounds are instants that exist and both are included, so a window that holds to ends after it. The bounds may span more than this endpoint's maximum queryable range, so clamp before re-querying.