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.
accounting:readGrant 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
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.