Skip to main content

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.

Required scope: accounting:write

Grant 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​

OK

Response Headers
    Content-Type