Bulk Assign Storefront Payout Type Mappings
PUT/api/storefront/payout-mappings/type-mappings/bulk-assign
Assigns one account and/or mapping group to many line types at once, applied like Update Storefront Payout Type Mappings (global rows and this store's own).
accounting:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token and the integrations.update permission. Open to API tokens with the accounting:write scope.
Body:
provider(required): stripe.integration_instance_id(required integer).ids(required array of mapping IDs, at least one).nominal_code_id(optional, nullable account ID): sent = applied, null clears the account.storefront_payout_mapping_group_id(optional, nullable group ID): sent = applied, null ungroups. At least one of the two must be sent.effective_from(optional, nullable, string, Y-m-d): payouts arriving on or after this date (by arrival date) use the change and are rebuilt; earlier ones keep the accounts they posted with. Defaults to today. Must be after the accounting lock date.
data.updated is the number of rows assigned.
Mapping changes are dated. Each change applies to payouts arriving on or after effective_from, so payouts already in your books before that date keep the accounts they posted with. GET /api/ledger/payout-mapping-periods (List Payout Mapping Periods, kind storefront_payout_type_mapping or storefront_payout_fallback_setting) returns a row's dated history and scheduled changes, and GET /api/ledger/payout-mapping-periods/impact (Preview Payout Mapping Change) counts the payouts a change would rebuild.
skipped_posted_count in the response is the number of payouts already posted that the change makes out of date; they are flagged for review rather than rebuilt.
An account that posts to a Xero system account (for example Xero's built-in Sales Tax / GST account) is rejected with a 422 while Xero is your connected accounting provider, because Xero refuses lines coded to system accounts.
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.