Update Storefront Accounting Settings
PUT/api/storefront/:integrationInstance/finance-settings
Changes how one store books its revenue. Send only the fields to change.
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 (all optional):
accounting_sync_mode(string):per_orderorper_payout.payout_processors(array of strings): stripe (PayPal has no payouts; its orders are always booked per order).payout_accounting_start_date(nullable, Y-m-d): must be after the accounting lock date (re-sending the stored date is always accepted).payout_deposit_nominal_code_ids(nullable object keyed by stripe): a bank or current-asset account ID per processor. Merged into the stored accounts: a processor you leave out keeps its account (so dropping a processor frompayout_processorsnever loses the account its existing payouts deposit to), a processor sent as null is cleared, and null for the whole object clears every account.processor_fee_nominal_code_ids(nullable object,paypalonly): the PayPal fee account (any account but Accounts Receivable / Payable or a Xero system account; null = the merchant-fee account). A change re-posts the store's PayPal fee entries not posted yet.shared_account_owner(nullable object):"<provider>:<account id>"→ the integration instance ID of the store that books that shared account's payouts (one of the stores inshared_accounts), or null. The choice is recorded on every store reporting the account and its unposted payouts move to the owner.fallback_settings(object keyed by stripe): each withfallback_revenue_nominal_code_id,fallback_expense_nominal_code_idandinvoiced_order_payout_nominal_code_id(nullable account IDs), as in Update Storefront Payout Fallback Settings.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. Applies tofallback_settings.
What a change does:
- The settings, the snapshot of which existing orders the payouts carry and the switch-over date are saved together, so nothing reads a half-saved store.
- Switching the mode, the start date or the processors re-decides which orders the payouts book and rebuilds the store's per-order documents and payouts to match; per-order documents an order no longer needs are withdrawn, and orders already in a payout keep it.
- A new deposit account re-posts the store's payout deposits.
The response is the full settings, as Get Storefront Accounting Settings returns them, plus skipped_posted_count (posted payouts a fallback change makes out of date).
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
- 404
- 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.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
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.