Update Storefront Payout Fallback Settings
PUT/api/storefront/payout-mappings/fallback-settings
Saves a store's fallback accounts for one processor. Keys left out keep the account in force (inherited from the global setting when the store has none of its own yet). A changed account rebuilds the store's unposted payouts.
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).fallback_revenue_nominal_code_id,fallback_expense_nominal_code_id,invoiced_order_payout_nominal_code_id(optional, nullable account IDs):fallback_revenue_nominal_code_id: the account an unmapped line type posts to when it adds money (a charge with no account).fallback_expense_nominal_code_id: the account an unmapped line type posts to when it takes money (fees, refunds with no account).invoiced_order_payout_nominal_code_id: for an order that already has its own invoice (for example one placed before the store switched to per-payout booking), the account its payout line is credited to instead of revenue: a clearing (current asset) account. It cannot be the Accounts Receivable or Accounts Payable account (422): the payout's documents already post against those, so its deposit could not settle the line.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.
The response is the settings now in force, plus top-level skipped_posted_count.
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.