Settlements
Not available through the public API
This page describes a planned capability. It has no endpoints in the public API
today, and nothing on this page can be called. For payouts to sellers on a marketplace, use the Marketplace API, which is available today: GET /v1/marketplace/payouts, POST /v1/marketplace/payouts/{payout_id}/confirm and GET /v1/marketplace/statements (see the Marketplace API).
A settlement would roll a group of invoices and credit notes into a single payout statement for a counterparty: paying sellers their share of platform revenue, commissions on referred customers, or any case where money flows back out based on aggregated billing activity.
Planned model
The shape below is planned and may change before release. None of it is part of any API today.
| Object | Purpose |
|---|---|
Settlement | The header: counterparty, period, currency, totals, payout status. |
SettlementLine | One row per source document (invoice, credit note, fee adjustment) included in the settlement. |
A settlement would be generated per counterparty and period from the counterparty's commission and withholding rules, or assembled by hand for one-off bonuses and dispute resolutions, then finalised (totals frozen, a settlement number assigned) and marked paid with a payout reference. Withholding and clawbacks would appear as their own negative lines. A counterparty-facing PDF and a line-level CSV would be available for reconciliation.
Planned lifecycle:
Code
Next steps
- Invoices - the source documents a settlement would aggregate
- Credit notes - reductions that would flow into a settlement
- Marketplace API - sellers, sales, payouts and statements, available today