Create Landed Cost

POST /inventory/landed-costs

Group: Inventory › Landed Costs · Operation ID: createLandedCost

Creates a landed cost as a draft. Nothing is capitalized until you commit it.

Creates a landed cost as a draft over committed receipts and approved vendor bill charges. Nothing is capitalized until you commit it.

Read GET inventory/landed-costs/vendor-bill-lines?entityId=<id> first. Its id is a charge's chargeId, its functionalLineTotal is what to send as amount, and its allocationMode is what to pass back. Without it you cannot build the payload.

Send only the charge line, never the vendor bill with it. The vendor bill is derived from the line.

The allocation is computed as part of the create. Read the landed cost back and allocationLines says what each receipt line's unit cost becomes. That is the preview, and it is always current because it is recomputed on every write.

Every amount is in the entity's functional currency. Nothing converts them, so the selector's functionalLineTotal is the right figure and the bill's own lineTotal is not.

Open in the interactive reference

Parameters

Name In Type Required Description
Api-Version header "v1" yes The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version v1.
Idempotency-Key header string no An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with 400 IDEMPOTENCY_NOT_SUPPORTED rather than silently ignored.

Request body

Required, application/json: createLandedCostInput.

Field Type Required Description
entityId string yes The legal entity. It decides the functional currency that every amount on the landed cost is in, and it cannot be changed after create.
documentDate string (date) no The date of the landed cost. Use format YYYY-MM-DD. Defaults to today.
notes string no Free text on the landed cost.
receipts array of object yes The receipts whose stock the charges are capitalized onto. At least one, and every one must be committed.
receipts[].receiptId string yes A committed receipt. See id on GET inventory/receipts/:id.
receipts[].selectedLineIds array of string no The receipt lines to allocate onto, by their id under lines on GET inventory/receipts/:id. Omit to use all of them, which is the usual case. Every id must belong to this receipt, and an id from another one fails with REFERENCE_NOT_FOUND.
charges array of object yes The charges to capitalize, read from GET inventory/landed-costs/vendor-bill-lines. At least one, and every one from an approved vendor bill.
charges[].chargeId string yes The vendor bill line the charge comes from, by its id on GET inventory/landed-costs/vendor-bill-lines. The vendor bill is derived from it, so there is no second id to send.
charges[].allocationMode string no How to spread this charge over the receipt lines. Accepted values: 'Equal', 'Quantity', 'LineTotal', 'Weight', 'Volume'. Pass back what GET inventory/landed-costs/vendor-bill-lines returned. Omitting it does not fall through to the landed cost item configuration. It falls through to the item's own default, which may be a different mode.
charges[].amount string (decimal) yes How much of the charge to capitalize, in the entity's functional currency. Send functionalLineTotal from GET inventory/landed-costs/vendor-bill-lines, less anything already allocated, not the bill's own lineTotal. Nothing converts this amount.
charges[].isSelected boolean no Whether to include the charge. Defaults to true. A charge set to false is kept on the landed cost and allocated nothing.

Example:

{
  "entityId": "7039b992-696a-40c7-a181-51759304ef83",
  "documentDate": "2026-01-15",
  "notes": "<notes>",
  "receipts": [
    {
      "receiptId": "b1a7c930-5e46-4f82-8d05-71c3e9a24f68"
    }
  ],
  "charges": [
    {
      "chargeId": "9c47e1b8-2a63-4d05-b7f9-04e28d5a1c37",
      "allocationMode": "Quantity",
      "amount": "240"
    }
  ]
}

Response

200 Success

Under data (createLandedCostOutput):

Field Type Required Description
id string yes The unique identifier for the created landed cost.
documentNumber string no The landed cost number, for example 'LC-1007'. Assigned when the landed cost is created.
documentStatus string yes Always DRAFT. Nothing is capitalized until you commit the landed cost.
allocationLineCount number no The number of allocation lines, one per selected receipt line. Zero means the charges landed on nothing, which is worth checking before you commit.

Response headers

Errors

Code Status
REFERENCE_NOT_FOUND 400
NO_RECEIPTS 400
NO_CHARGES 400
RECEIPT_NOT_COMMITTED 400
VENDOR_BILL_NOT_APPROVED 400
INVALID_AMOUNT 400
UNKNOWN_ALLOCATION_MODE 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses