Adopt Facilitator Tax Clearing Treatment
POST/api/ledger/facilitator-tax/adopt
Adopts the clearing treatment for marketplace-facilitator tax: from now on, tax on orders from channels where the marketplace collects and remits it posts to a dedicated clearing liability instead of Sales Tax, where the settlement's collected and withheld lines net to zero. It applies to orders created after adoption only; posted entries are not changed (use Repair Facilitator Tax for past months).
accounting:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body:
- clearing_nominal_code_id (optional, nullable integer): an existing liability account to use as the clearing account. It must not be the Sales Tax account. Omit or pass null to use the 2210 Marketplace Facilitator Tax account, which is created if missing. With Xero or QuickBooks connected, a picked account must already be linked to a provider account (the currently mapped or suggested account is the exception); the mapped or suggested account is created in the provider and linked if it has no provider account yet.
- apply_settlement_defaults (optional boolean, default true): also map the channels' unmapped facilitator-tax settlement and payout codes to the clearing account.
Refused with 422 when the treatment is already in force, accounting generation is off, the chosen account is not a liability or is the Sales Tax account, a picked account is not linked to the connected provider (clearing_nominal_code_id), the provider refuses to create the clearing account (treatment; nothing is created or mapped: create 2210 Marketplace Facilitator Tax in the provider first, or pick a linked liability), or another adoption or repair is running.
Returns the updated status.
Authentication: Requires Bearer token (signed-in user session; not available to Personal Access Tokens). Requires the accounting.manage_settings permission.
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.