Import Storefront Payout Type Mappings
POST/api/storefront/payout-mappings/type-mappings/import
Sets the account and mapping group of many line types at once from a CSV file, in the format Export Storefront Payout Type Mappings downloads.
accounting:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Two steps:
- Upload the CSV as multipart form data to
POST /api/store-filewith fieldsfileanddestination=models. The response containsstored_name. - Call this endpoint with that
stored_name.
CSV columns (header row required): Financial Code, Nominal Code, Mapping Group.
How each row is applied:
- The row updates the mapping the store uses for that financial code: its own where it has one, otherwise the global one.
Nominal Codeacceptscode - name(for example4000 - Online Store Sales), a bare code (4000) or an account name. A blank value clears the account.Mapping Groupis a group name. A blank value leaves the group as it is. A global row can only use a global group.- Rows with no financial code, a financial code this store does not have, an account that does not exist (or is a Xero system account), or a group that is not found or not allowed are not applied and are listed in
skippedwith their line number and the reason. Nothing is guessed.
Changes are dated like Update Storefront Payout Type Mappings: payouts arriving on or after effective_from use the new mappings and are rebuilt; earlier payouts keep the accounts they posted with.
Body:
provider(required): stripe.integration_instance_id(required integer).stored_name(required string, max 255): the name returned byPOST /api/store-file.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.
Response: data.updated is the number of rows applied, data.skipped lists the rows that were not, data.skipped_posted_count the posted payouts the change makes out of date.
Errors:
- 400: the uploaded file was not found (upload it again), or the file has no rows.
- 422:
stored_nameis missing, oreffective_fromis not a valid date or falls on or before the accounting lock date.
Authentication: Requires Bearer token and the integrations.update permission. Open to API tokens with the accounting:write scope.
Request
Responses
- 200
- 400
- 401
- 403
- 422
- 429
OK
Response Headers
Bad Request
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.