Creates several landed costs in one call, each as a draft.

POST /inventory/landed-costs/bulk

Group: Inventory › Landed Costs · Operation ID: bulkCreateLandedCosts

Creates several landed costs as drafts in one all-or-nothing call, the shape a period-end run takes, where a month of freight invoices is capitalized onto the receipts they belong to in one pass.

If any landed cost is rejected, none is created, and the error names the offending document's index. Every precondition of the single create applies to every entry.

Nothing is committed. Each landed cost comes back as a draft and has to be committed on its own. A commit revalues stock, and one that failed partway through a batch would leave some of the batch's stock restated and the rest 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: bulkCreateLandedCostsInput.

Field Type Required Description
landedCosts array of object yes The landed costs to create, each as a draft. All or nothing: if any is invalid, nothing is created.
landedCosts[].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.
landedCosts[].documentDate string (date) no The date of the landed cost. Use format YYYY-MM-DD. Defaults to today.
landedCosts[].notes string no Free text on the landed cost.
landedCosts[].receipts array of object yes The receipts whose stock the charges are capitalized onto. At least one, and every one must be committed.
landedCosts[].receipts[].receiptId string yes A committed receipt. See id on GET inventory/receipts/:id.
landedCosts[].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.
landedCosts[].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.
landedCosts[].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.
landedCosts[].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.
landedCosts[].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.
landedCosts[].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:

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

Response

200 Success

Under data (bulkCreateLandedCostsOutput):

Field Type Required Description
created array of object yes The created landed costs, in input order, each a draft. Match them to inputs by index.
created[].id string yes The unique identifier for the created landed cost.
created[].documentNumber string no The landed cost number, for example 'LC-1007'. Assigned when the landed cost is created.

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