Skip to main content
GET
Get profitability summary

Authorizations

Authorization
string
header
required

API key authentication

Query Parameters

merchantId
string
required

Merchant whose customers to summarize Unique identifier for an organization

Pattern: ^org_[a-zA-Z0-9]+$
from
string<date-time>
required

Start of the time range (ISO 8601 format)

to
string<date-time>
required

End of the time range (ISO 8601 format)

topN
integer
default:10

Number of top customers (by profit) to return individually. The rest are rolled into a single 'Other' row.

Required range: 1 <= x <= 100
currency
string

ISO 4217 currency code to scope the summary. Defaults to the merchant's primary currency.

Required string length: 3
excludeEmpty
boolean
default:false

When true, leave customers with neither revenue nor cost in the period out of rows. They are dropped before ranking, so they take no top-N slot and are not folded into the 'Other' row. emptyCustomerCount says how many there are either way.

includeEmpty
boolean
default:false

When true, also return in emptyCustomers the customers counted in emptyCustomerCount that rows does not carry, so a caller can show the complete customer list.

Response

Profitability summary

object
string
required

Object type identifier

Allowed value: "profitability_summary"
currency
string
required

ISO 4217 currency code applied to revenue and cost values

rows
object[]
required

Top-N customer rows by profit descending, optionally followed by a single 'Other' row when more than topN customers contributed. Soft-deleted customers appear only through the 'deleted' row, which comes last, never by name. With excludeEmpty=true, customers with neither revenue nor cost in the period are left out.

Maximum array length: 101
customerCount
integer

The merchant's customers this summary scored, whether or not they made a row.

Required range: x >= 0
emptyCustomerCount
integer | null

Customers with neither revenue nor cost in the period, counted whether or not excludeEmpty left them out of rows. Null when a cost read failed: their cost was never established, so none is counted and excludeEmpty leaves nobody out.

Required range: x >= 0
unloadedCustomerCount
integer | null

Customers rows does not carry because a cost read failed (see warnings) and they had no revenue in the period. Null when every cost read settled.

Required range: x >= 0
emptyCustomers
object[]

The customers emptyCustomerCount counts that rows does not carry, either as a row or folded into the 'Other' row, sorted by name, each reading zero with a null margin. Present only when includeEmpty=true and the count is answered. They are never ranked, never part of the top-N and never folded into the 'Other' row.

warnings
string[]

Non-fatal warnings collected during cost discovery (e.g. an individual cost query failed). Empty array on a clean run.

Maximum array length: 100
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 may span more than this endpoint's maximum queryable range, so clamp before re-querying.

costRange
object | null

Where the caller's cost data actually lies in time. Present only when the selected range returned no cost. An object carries the bounds of the real cost events; null means the caller has no cost event at any time; an absent field means the extent was not resolved, because the result was not empty, because the lookup failed, or because the metering service does not serve the bounds method. An absent field must never be read as an absence.