Skip to main content

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.

Required scope: purchase-orders:write

Grant 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_order or warehouse_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 in line_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). On category_default, a duty-category line with no override splits by customs_entry_based when a fully matched customs entry is linked, else by duty_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 optional suggestion
  • 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, estimated or missing)
  • 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; rows lists 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), or nothing_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​

OK

Response Headers
    Content-Type