Suggest Settlement Tax Mappings
POST/api/amazon/unified/settlement-type-mappings/suggest-tax
Suggests the account each tax-like Amazon settlement code should be mapped to, for the Amazon settlement codes on the unified mappings page: the global codes, or — with integration_instance_id — the codes one store resolves to, its per-store overrides included. Saves nothing — apply a suggestion with the update or bulk-assign endpoint, or keep the current account with Acknowledge Settlement Tax Mapping.
accounting:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
A code is returned when it is tax and is unmapped, mapped somewhere other than the account its tax class belongs on, or flagged for review.
Body (all optional; send {} for every tax-like code):
- mapping_ids (array of integers): only suggest for these mapping IDs.
- needs_review_only (boolean, default false): only suggest for codes flagged for review.
- integration_instance_id (integer): suggest for this Amazon store's resolved codes — its overrides, plus the global codes it does not override. Omit for the global codes.
Each suggestion: mapping_id, integration_instance_id (null = global mapping), financial_code, tax_class (facilitator_collected, facilitator_remitted, seller_collected or tax_on_fees) and tax_class_label, the current account (current_nominal_code_id / current_nominal_code_label), the suggested account (suggested_nominal_code_id / suggested_label — null when the account the code belongs on is not mapped yet; the reason then says what to set up), sets_up_clearing_account (true while the Marketplace Facilitator Tax clearing account is not mapped: suggested_label then names the account adopting the clearing treatment would use and suggested_nominal_code_id is null — call Set Up Facilitator Tax Clearing Account first, then map the code to the id it returns), reason, confidence (high for codes known exactly, low for codes that only mention tax) and needs_review.
Default accounts: marketplace-collected and marketplace-remitted tax → the Marketplace Facilitator Tax clearing account; tax the seller collects → Sales Tax; tax on marketplace fees → Purchase Tax when mapped, otherwise the fee account it already sits on.
Authentication: Requires Bearer token (signed-in user session; not available to Personal Access Tokens).
Request
Responses
- 200
- 401
- 403
- 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.
Unprocessable Content
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.