Skip to main content

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.

Required scope: accounting:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Two steps:

  1. Upload the CSV as multipart form data to POST /api/store-file with fields file and destination=models. The response contains stored_name.
  2. 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 Code accepts code - name (for example 4000 - Online Store Sales), a bare code (4000) or an account name. A blank value clears the account.
  • Mapping Group is 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 skipped with 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 by POST /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_name is missing, or effective_from is 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​

OK

Response Headers
    Content-Type