Set Channel Settlement Revenue
PUT/api/ledger/settings/channel-sync/:integrationInstance/settlement-revenue
Sets when a sales channel's payouts or settlements take over booking its revenue, so its per-order invoices and credits stop posting their own ledger entries and the revenue is counted once.
accounting:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token with the Manage accounting settings permission.
Body (every field optional; a field left out keeps its current value):
per_order_revenue_entries_off_from(date Y-m-d, nullable): the cut-over. Order invoices and credits dated on/after it post no ledger entry. It cannot be inside a locked period (422 naming the first allowed day). Null removes it, so documents post per order again.payout_accounting_start_date(date Y-m-d, nullable, Amazon only): when the channel's settlements start booking revenue. Orders sold before it keep their own invoices. Other channels set it on their Finance settings; 422 here.accounting_sync_mode(string, Amazon only):per_order(order invoices book revenue; settlements book fees and other lines) orper_payout(settlements book revenue). Switching toper_payoutis refused while the settlements' order-sale lines (Order / ItemPrice / PrincipalandRefund / ItemPrice / Principal) do not both book revenue — unless the channel's settlements never booked revenue, in which case the switch is allowed and its settlements with order-sale lines are held until those lines are mapped (order_sale_mapping_pending); switching toper_orderis refused while either of them still does. Switching mode changes which document books revenue for orders created afterwards; orders already created keep theirs. Sendorder_revenue_mappingwith the switch to re-map those lines in the same step.order_revenue_mapping(object, optional, Amazon only, only together withaccounting_sync_mode): re-points the two order-sale settlement lines in the same transaction as the mode switch, so the switch and the mapping change are saved together or not at all. They are re-mapped from the day the order invoices stop posting (per_payout) or start posting again (per_order).order_revenue_mapping.nominal_code_id(integer, required with the object): the account the order-sale lines post to. Forper_payoutit must be a revenue (Sales or Revenue type) account, since the settlements then book order sales; forper_orderit must be a non-revenue account (such as a settlement clearing account), since the order invoices book the sales and a revenue account would count each sale twice. 422 on this field otherwise.order_revenue_mapping.mapping_group_id(integer, nullable): the settlement mapping group they post in. It must belong to this channel and be an Invoice group forper_payoutor a Bill group forper_order; omit it to use the channel's first group of that type.
Changing the dates re-evaluates the channel's documents in open periods in the background. Returns the channel's refreshed explanation (same shape as Get Channel Sync Explanation); its settlement_revenue object holds:
accounting_sync_mode,payout_accounting_start_date/revenue_start(the same date under both names),per_order_revenue_entries_off_from(the cut-over) andfirst_open_day(the earliest allowed cut-over; null when nothing is locked).order_revenue_mapped(boolean, Amazon only, else null): whether the settlements book order sales AND refunds. A switch toper_payoutneeds it true, or anorder_revenue_mapping.order_revenue_booked_by_settlements(boolean, Amazon only, else null): whether either order-sale line books revenue. A switch toper_orderneeds it false, or anorder_revenue_mapping.per_order_revenue_entries_on_from(date or null): after the channel left payout mode, the day its per-order invoices and credits post again; null when it never left.closed_windows(array): each period the channel spent in payout mode and then left, as{from, to, start}(frominclusive,toexclusive,startthe revenue start date in force then, or null). History only: whether an order's documents post follows the order's own revenue owner, decided when it was created, so an order sold while the channel ran per payout stays booked by its settlements after the switch.order_sale_mapping_pending(boolean, Amazon only, else null): the channel runs per payout but its Order and Refund / ItemPrice / Principal settlement lines don't book revenue yet; settlements with such lines are held until they are mapped.clearing_account_needed(boolean or null): the channel has orders booked by their own invoices whose payout or settlement lines would post to revenue too, because the account those lines go to instead is not set (Amazon: settlement clearing account; Shopify: account for invoiced orders paid through payouts). Null when the channel has no such account.accounting_sync_mode_editable_here/start_date_editable_here: whether those fields are set on this endpoint (Amazon) or on the channel's Finance settings.
404 when the channel does not exist; 422 when the channel has no settlements, for a date inside a locked period, for a mode switch the order-sale mappings do not fit, for order_revenue_mapping sent without accounting_sync_mode, for an order_revenue_mapping.nominal_code_id of the wrong account type for the mode, or for a mapping group of another channel or of the wrong document type.
Request
Responses
- 200
- 401
- 403
- 404
- 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.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
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.