Skip to main content

Update Storefront Accounting Settings

PUT 

/api/storefront/:integrationInstance/finance-settings

Changes how one store books its revenue. Send only the fields to change.

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 (all optional):

  • accounting_sync_mode (string): per_order or per_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 from payout_processors never 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, paypal only): 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 in shared_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 with fallback_revenue_nominal_code_id, fallback_expense_nominal_code_id and invoiced_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 to fallback_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​

OK

Response Headers
    Content-Type