Preview Landed Cost Allocation
POST/api/landed-costs/allocation-preview
Shows how a landed-cost bill would be split before it is saved. Read-only: nothing is written.
purchase-orders:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token with read/write access to purchase orders.
Request fields:
- link_type (required):
inbound_shipment,purchase_orderorwarehouse_transfer— the document the bill is (or will be) on - link_id (required, integer): its ID
- bill_id (optional, integer): the bill being edited, if any — a "By customs entry" group then splits by the customs entries linked to that bill (else to the document), as saving would
- proration_strategy (required): the bill's method, e.g.
category_default,cost_based,weight_based,volume_based,quantity_based,specific_line,duty_estimate_based,customs_entry_based,manual - lines (required, may be empty, max 500): the bill's lines —
key(required string you choose, echoed back inline_keys),amount(required, the line's extended amount),cost_category_id(optional),proration_strategy_override(optional:cost_based,volume_based,weight_based,quantity_based,specific_line,duty_estimate_based,customs_entry_based). Oncategory_default, a duty-category line with no override splits bycustoms_entry_basedwhen a fully matched customs entry is linked, else byduty_estimate_based
Response:
- groups: one per method group (a single group unless proration_strategy is
category_default) — method asked for, method used after any fallback, amount, the line keys and categories in it, and an optionalsuggestion - targets: every purchase order or transfer line the bill spreads across, with each group's share per unit and in total, the landed cost per unit, the per-unit cost an all-cost split would give, and the product's weight and dimensions with their source (
measured,vendor,estimatedormissing) - data_quality: units with real (vendor or measured), estimated and missing weights and dimensions
- suggestion (on a group split by cost): weight or volume instead, given only when at least 90% of the units carry real data for that basis, some product moves at least $1.00 per unit and at least 10% of the group's amount moves;
rowslists the per-unit change for each product, biggest first - hint: set when no group has a suggestion because the data is estimated — names the largest cost group of at least $25
- warnings: groups that fell back (
proration_basis_fallback,duty_estimates_zero_fallback,customs_entry_not_linked), a customs-entry group only partly matched (customs_entry_partial_match— the unmatched share splits by cost), ornothing_to_allocate/no_targets
Manual bills return no groups. Returns 404 when the linked document does not exist and 422 for invalid input.
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 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.