GET /royalties/breakdown

Get a per-dimension royalty breakdown

Return royalties for the authenticated user's owned labels, grouped by a caller-chosen ordered set of dimensions (group_by), decomposing the same provider-fee-adjusted gross_usd figure the statements/transactions filter path and the customer CSV use. This is the JSON equivalent of the async CSV line-item export's per-track × per-DSP × per-territory granularity, without downloading and parsing a file.

group_by is required and is an ordered, comma-separated, distinct subset of track,dsp,release,territory,period (e.g. group_by=track,dsp). It is a closed allow-list — any other token, a duplicate, or an empty token returns 422 and never reaches the query. Each row carries only the keys for the requested dimensions (isrc/dsp/release_id/territory/period, each possibly null when the value is unattributable), plus currency and a single monetary gross_usd. A line with a blank retailer under a known track surfaces as { "isrc": "…", "dsp": null } — known attribution is never discarded. The terminal page carries one synthetic rounding- adjustment row so the sum of every row exactly equals meta.total_gross_usd; that row has every dimension key null AND an additional adjustment: true key. Only the adjustment row carries adjustment — that key, not "all dimensions null", distinguishes it from a genuine all-null-dimension group (a real blank-retailer group under group_by=dsp is also { "dsp": null, … } but has no adjustment key).

Snapshot-backed pagination. The grouped result is aggregated once, at a single instant, and frozen — every page (and every cursor read) is served from that snapshot, so per-group totals are self-consistent across the whole walk. Page forward with the opaque cursor from links.next until it is null. A cursor is bound to its snapshot, user, and exact query params; an invalid, expired, foreign, or mismatched cursor returns 422 — restart without a cursor for a fresh snapshot. meta.as_of is the snapshot instant and meta.snapshot_expires_at when it (and its cursors) expire.

gross_usd is gross revenue after the statement-provider fee (e.g. Merlin/Orchard) and before LabelGrid platform/UGC fees — matching the customer-facing UI + CSV column of the same name. Net revenue (after LabelGrid fees) and the final payout remain on the statements endpoint. Only labels you directly own are visible; an unowned filter[label_id]/filter[release_id] returns 404 and a foreign upc/isrc returns empty data. dsp and territory are the raw DSP-reported values (parity with the CSV), not server-normalized.

Parameters

Responses