Bulk create landed costs

Operation ID: bulkCreateLandedCosts

Group: Inventory › Landed Costs

Open in the interactive reference

POST /inventory/landed-costs/bulk

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Creates multiple landed costs as drafts in one request. Each landed cost is checked the same way as on POST inventory/landed-costs. If one landed cost cannot be created, the request fails and no landed costs are created.

Nothing is committed. Commit each landed cost with POST inventory/landed-costs/:id/commit.

Parameters

Name In Type Required Description
Api-Version header string · 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<object> yes The landed costs to create. Example: [{"entityId":"7039b992-696a-40c7-a181-51759304ef83","receipts":[{"receiptId":"b1a7c930-5e46-4f82-8d05-71c3e9a24f68"}],"charges":[{"chargeId":"9c47e1b8-2a63-4d05-b7f9-04e28d5a1c37","allocationMode":"Quantity","amount":"240"}]}].
landedCosts[].entityId string yes The unique identifier of the legal entity the landed cost belongs to. Format: UUID. It cannot be changed later. See id on GET base/entities (entities).
landedCosts[].documentDate date no The date of the landed cost. Format: YYYY-MM-DD. Defaults to today's date in UTC. The inventory revaluations that the commit creates have this date, so it sets the date of the change in the stock's value. It must fall in an open accounting period.
landedCosts[].notes string no Free text on the landed cost.
landedCosts[].receipts array<object> yes The receipts whose stock the charges are spread over. Send at least one. Every receipt must have the documentStatus 'COMMITTED'.
landedCosts[].receipts[].receiptId string yes The unique identifier of the receipt. Format: UUID. See id on GET inventory/receipts/:id (getReceipt).
landedCosts[].receipts[].selectedLineIds array<string> no The unique identifiers of the receipt lines to spread the charges over. Format: UUID. Each identifier must be the id of a line of the receipt named by receiptId. Omit to spread the charges over all of the receipt's lines. See lines[].id on GET inventory/receipts/:id (getReceipt).
landedCosts[].charges array<object> yes The charges to spread over the stock. Each charge comes from a line of an approved vendor bill. Send at least one.
landedCosts[].charges[].chargeId string yes The unique identifier of the vendor bill line the charge comes from. Format: UUID. The vendor bill is taken from the line, so you do not send it. See id on GET inventory/landed-costs/vendor-bill-lines (getAvailableCharges).
landedCosts[].charges[].allocationMode string no How the charge is spread (allocated) over the receipt lines. Defaults to the defaultAllocationMode of the item on the vendor bill line, or to 'Equal' when there is no such default. To use the mode set on the matching landed cost item, send the allocationMode from GET inventory/landed-costs/vendor-bill-lines. 'Weight' needs a gross weight, weight, or net weight on the item of every selected receipt line. 'Volume' needs a volume per unit on the item of every selected receipt line, or else a length, width, and height on every one. Weights and volumes are converted to the same unit before the charge is spread. See defaultAllocationMode, grossWeight, weight, netWeight, weightUnit, volumePerUnit, volumeUnit, length, width, and height on GET inventory/items/:id (getItem). Accepted values: 'Equal', 'Quantity', 'LineTotal', 'Weight', 'Volume'.
landedCosts[].charges[].amount decimal yes The amount of the vendor bill line to use, in the functional currency of the landed cost's legal entity. It must be more than 0. To use what is left on the line, send functionalLineTotal minus functionalAllocatedAmount from GET inventory/landed-costs/vendor-bill-lines. The commit fails if this amount is more than what is left on the line.
landedCosts[].charges[].isSelected boolean no Whether to spread the charge over the receipt lines. Defaults to true. A charge set to false is kept in the landed cost's charges, so you can set it back to true later, but the commit does not spread it. 
{
  "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<object> yes The created landed costs, in the order you sent them. Example: [{"id":"6d18b2f0-49c7-4a35-9e81-2f0c5a7d3b64","documentNumber":"LC-1007"}].
created[].id string yes The unique identifier for the created landed cost. Format: UUID.
created[].documentNumber string no The landed cost number, for example 'LC-1007'. 
{
  "data": {
    "created": [
      {
        "id": "6d18b2f0-49c7-4a35-9e81-2f0c5a7d3b64",
        "documentNumber": "LC-1007"
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

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