# 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](https://docs.api.lensing.ai/?op=searchLandedCosts)

## 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:

```json
{
  "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

- `400` — Invalid request or business failure
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error