Skip to main content

List Payout Mapping Periods

GET 

/api/ledger/payout-mapping-periods

Lists the dated history of payout mapping rows: for each row, the values it had over each span of payout dates. A payout mapping row is a channel type mapping (a financial code's account, mapping group and, for eBay and Shopify, its sale component split) or a store's fallback accounts. Mapping changes are dated: saved with an effective_from date, they apply to payouts dated on or after it, while earlier payouts keep the accounts they posted with. A change can also be scheduled for a future date.

Required scope: accounting:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token and the accounting scope.

Query parameters:

  • kind (required): which kind of mapping row the ids refer to.
  • mapping_ids[] (required, 1 to 200 integers): mapping row ids.

Response (under data.payout_mapping_periods):

  • today: today's date in the account's timezone.
  • lock_date: the accounting lock date, or null when nothing is locked. Payouts on or before it can't change.
  • earliest_effective_date: the earliest effective_from a change may use (the day after lock_date), or null when nothing is locked.
  • mappings: one entry per row that has a dated history, each with mapping_id and its periods in date order. A row that was never changed from a date (its current values have always applied) is left out.

Each period:

  • effective_from / effective_to: the span of payout dates (Y-m-d). effective_from is inclusive and null means from the beginning; effective_to is exclusive and null means open-ended.
  • status: past (ended on or before today), current (in force today) or scheduled (starts after today).
  • inherits: true when the store's own row did not exist yet in that span, so the all-stores default applied; values is then empty.
  • values: the row's mapping fields in that span (account ids, mapping group id, and for eBay and Shopify type mappings the split settings).
  • labels: a display name for each id in values: the account code and name, or the mapping group name.
  • changed_by_user_id: the user who last changed the period, or null.

Payout dates: eBay payout date; Shopify accounting date (else payout date); Walmart settlement date; Amazon settlement end date (in the account's timezone).

Request​

Responses​

OK

Response Headers
    Content-Type