Returns the landed costs that match the given criteria.

POST /inventory/landed-costs/search

Group: Inventory › Landed Costs · Operation ID: searchLandedCosts

Searches landed costs by exact criteria in a request body, and returns the same item schema as get, the whole landed cost with its receipts, charges and allocation.

Three criteria here cannot be asked of the collection endpoint, because they are questions about the landed cost's children. receiptId finds the landed costs covering a given receipt, vendorBillId those drawing on a given vendor bill, and itemId those whose allocation touches a given item. Each resolves to the set of landed costs that satisfy it, and they intersect.

Every criterion is exact and they combine with AND. An empty filters object returns everything, page by page. There is no substring or free-text matching on any endpoint of this resource.

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.

Request body

Required, application/json: searchLandedCostsInput.

Field Type Required Description
filters object yes The search criteria, combined with AND. An empty object returns every landed cost, page by page.
filters.documentNumber string no Limits results to the landed cost with this number, for example 'LC-1007'. The match is exact.
filters.documentStatus string no Limits results to landed costs with this status. The two statuses are DRAFT and COMMITTED. The match is exact.
filters.entityId string no Limits results to landed costs of this legal entity.
filters.receiptId string no Limits results to the landed costs that name this receipt. See id on GET inventory/receipts/:id.
filters.vendorBillId string no Limits results to the landed costs that draw a charge from this vendor bill. See id on GET accounting/vendor-bills/:id.
filters.itemId string no Limits results to the landed costs whose allocation touches this item.
filters.fromDate string (date) no Limits results to landed costs dated on or after this date. Format YYYY-MM-DD.
filters.toDate string (date) no Limits results to landed costs dated on or before this date. Format YYYY-MM-DD.
filters.modifiedSince string (date-time) no Limits results to landed costs changed on or after this time, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
page object no The pagination controls. Omit for the first page.
page.cursor string no The cursor from the previous response's pagination.nextCursor. Omit on the first request.
page.size number no The number of landed costs per page, between 1 and 200. Defaults to 50. A value above 200 is treated as 200, not rejected.

Example:

{
  "filters": {
    "documentStatus": "DRAFT"
  },
  "page": {
    "size": 50
  }
}

Response

200 Success

Under data (searchLandedCostsOutput):

Field Type Required Description
items array of object yes The landed costs that match, oldest first, each whole. An empty array when nothing matches.
items[].id string yes The unique identifier for the landed cost.
items[].documentNumber string no The landed cost number, for example 'LC-1007'. Assigned when the landed cost is created.
items[].documentStatus string yes The status of the landed cost. It is DRAFT while it is being built and COMMITTED once you commit it with POST inventory/landed-costs/:id/commit.
items[].documentDate string (date) no The date of the landed cost. Format YYYY-MM-DD.
items[].entityId string no The legal entity the landed cost belongs to. It decides the functional currency that every amount is in.
items[].entityName string no The name of that legal entity.
items[].currency string no The currency of the landed cost's amounts. Format ISO 4217, for example 'GBP'. This is the entity's functional currency, and nothing converts the amounts.
items[].notes string no Free text on the landed cost.
items[].totalChargeAmount string (decimal) no The total of the selected charges, in the landed cost's currency.
items[].receiptCount number no The number of receipts in scope.
items[].chargeCount number no The number of charges on the landed cost.
items[].allocationLineCount number no The number of allocation lines, one per selected receipt line.
items[].createdDate string (date-time) no The date and time the landed cost was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lastModifiedDate string (date-time) no The date and time the landed cost last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].receipts array of object no The receipts whose stock the charges are capitalized onto, each with the lines in scope.
items[].receipts[].id string yes The receipt this scope entry is for. See id on GET inventory/receipts/:id.
items[].receipts[].receiptNumber string no The receipt's number.
items[].receipts[].documentDate string (date) no The date of the receipt. Format YYYY-MM-DD.
items[].receipts[].documentStatus string no The receipt's status. Always COMMITTED, because a landed cost cannot name a receipt that has not been committed.
items[].receipts[].lines array of object no Every line of that receipt, each showing whether this landed cost allocates onto it. A line that is not selected takes none of the charge.
items[].receipts[].lines[].id string yes The receipt line. This is what selectedLineIds names on create and update. See id under lines on GET inventory/receipts/:id.
items[].receipts[].lines[].isSelected boolean no Whether this landed cost allocates onto the line.
items[].receipts[].lines[].itemId string no The item received on the line.
items[].receipts[].lines[].itemCode string no The short code of that item.
items[].receipts[].lines[].itemName string no The name of that item.
items[].receipts[].lines[].locationId string no The warehouse it was received into.
items[].receipts[].lines[].quantity string (decimal) no The quantity received, in the line's unit.
items[].receipts[].lines[].inventoryQuantity string (decimal) no The same quantity in the item's stocking unit.
items[].receipts[].lines[].unitPrice string (decimal) no The price the line was received at, per unit, in the landed cost's currency.
items[].receipts[].lines[].lineTotal string (decimal) no The total for the line, in the landed cost's currency.
items[].charges array of object no The charges being capitalized, one per vendor bill line.
items[].charges[].id string yes The vendor bill line the charge comes from. See id on GET inventory/landed-costs/vendor-bill-lines.
items[].charges[].vendorBillId string no The vendor bill the charge belongs to. Derived from the line, never supplied. See id on GET accounting/vendor-bills/:id.
items[].charges[].vendorBillNumber string no The vendor bill's number.
items[].charges[].itemId string no The item the charge is billed as, where it is billed as one.
items[].charges[].itemCode string no The short code of that item.
items[].charges[].itemName string no The name of that item.
items[].charges[].allocationMode string no How this charge is spread over the receipt lines. Possible values: 'Equal', 'Quantity', 'LineTotal', 'Weight', 'Volume'.
items[].charges[].amount string (decimal) no The amount of the charge this landed cost takes, in the landed cost's currency.
items[].charges[].allocatedAmount string (decimal) no The amount of the charge that has actually been allocated. Filled in when you commit the landed cost.
items[].charges[].isSelected boolean no Whether this charge is included. An excluded charge is kept on the landed cost and allocated nothing.
items[].allocationLines array of object no The computed allocation: one line per selected receipt line, saying what its unit cost becomes. Recomputed on every write, so it is always current.
items[].allocationLines[].id string yes The unique identifier for the allocation line within the landed cost.
items[].allocationLines[].receiptId string no The receipt this allocation line belongs to. See id on GET inventory/receipts/:id.
items[].allocationLines[].receiptLineId string no The receipt line this allocation lands on. See id under lines on GET inventory/receipts/:id.
items[].allocationLines[].itemId string no The item.
items[].allocationLines[].itemCode string no The short code of that item.
items[].allocationLines[].itemName string no The name of that item.
items[].allocationLines[].locationId string no The warehouse.
items[].allocationLines[].locationCode string no The short code of that warehouse.
items[].allocationLines[].quantity string (decimal) no The quantity the allocation is spread over.
items[].allocationLines[].currentUnitCost string (decimal) no The unit cost of the stock before the landed cost commits.
items[].allocationLines[].additionalCostAmount string (decimal) no The share of the charges this line takes, in total, not per unit.
items[].allocationLines[].newUnitCost string (decimal) no The unit cost of the stock after the landed cost commits.
items[].allocationLines[].revaluationDocuments array of object no The inventory revaluations this allocation line produced. An empty array on a draft, and more than one where the charges post to different expense accounts.
items[].allocationLines[].revaluationDocuments[].id string yes The inventory revaluation. See id on GET inventory/inventory-revaluations/:id.
items[].allocationLines[].revaluationDocuments[].documentNumber string no The revaluation's number.
items[].allocationLines[].revaluationDocuments[].documentStatus string no The revaluation's status.
pagination object yes The pagination cursor for this page.
pagination.nextCursor string no The cursor for the next page. Pass it as page.cursor. Absent on the last page.
pagination.hasMore boolean no Whether more results remain beyond this page.

Statuses