# Search landed costs

Operation ID: `searchLandedCosts`

Group: Inventory › Landed Costs

[Open in the interactive reference](https://docs.api.lensing.ai/lensing/v1/endpoints/searchLandedCosts)

`POST /inventory/landed-costs/search`

Read-only: A read that takes its filters in the body. Changes nothing, and ignores Idempotency-Key.

Searches landed costs, with their receipts, charges, and allocation.

## 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`. |

## Request body

Required, `application/json`: searchLandedCostsInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | yes | The filters to apply. A landed cost must match every filter you send. Send an empty object to return all landed costs. Example: `{"documentStatus":"DRAFT"}`. |
| `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. Accepted values: 'DRAFT', 'COMMITTED'. |
| `filters.entityId` | string | no | Limits results to landed costs of the legal entity with this unique identifier. Format: UUID. See `id` on GET base/entities (entities). |
| `filters.receiptId` | string | no | Limits results to landed costs that include the receipt with this unique identifier. Format: UUID. See `id` on GET inventory/receipts/:id (getReceipt). |
| `filters.vendorBillId` | string | no | Limits results to landed costs with a charge from the vendor bill with this unique identifier. Format: UUID. See `id` on GET accounting/vendor-bills/:id (getVendorBill). |
| `filters.itemId` | string | no | Limits results to landed costs with an allocation line for the item with this unique identifier. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `filters.fromDate` | date | no | Limits results to landed costs with a `documentDate` on or after this date. Format: YYYY-MM-DD. |
| `filters.toDate` | date | no | Limits results to landed costs with a `documentDate` on or before this date. Format: YYYY-MM-DD. |
| `filters.modifiedSince` | date-time | no | Limits results to landed costs whose `lastModifiedDate` is on or after this time. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `page` | object | no | The page to return and its size. Omit to get the first page at the default size. Example: `{"size":50}`. |
| `page.cursor` | string | no | The cursor from the previous response's `pagination.nextCursor`. Send it exactly as you received it. Omit on the first request. |
| `page.size` | number | no | The number of landed costs per page, from 1 to 200. Defaults to 50. A value above 200 is treated as 200, not rejected. |

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

## Response

`200` Success

Under `data` (searchLandedCostsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array<object> | yes | The matching landed costs in this response. When more landed costs match than fit in one response, use `pagination` to get the rest. Empty when nothing matches. Example: `[{"id":"6d18b2f0-49c7-4a35-9e81-2f0c5a7d3b64","documentNumber":"LC-1007","documentStatus":"DRAFT","documentDate":"2026-08-18","entityId":"7039b992-696a-40c7-a181-51759304ef83","entityName":"Flow UK","currency":"GBP","totalChargeAmount":"240","receiptCount":1,"chargeCount":1,"allocationLineCount":1,"lastModifiedDate":"2026-08-18T09:14:22.517Z","receipts":[{"id":"b1a7c930-5e46-4f82-8d05-71c3e9a24f68","receiptNumber":"REC-2210","documentStatus":"COMMITTED","lines":[{"id":"2d5b81f7-4c93-4a16-8e70-5f1c9d3a82b4","isSelected":true,"itemCode":"WIDGET-01","quantity":"40","unitPrice":"12","lineTotal":"480"}]}],"charges":[{"id":"9c47e1b8-2a63-4d05-b7f9-04e28d5a1c37","vendorBillNumber":"VB-8842","itemCode":"SVC-FREIGHT","allocationMode":"Quantity","amount":"240","isSelected":true}],"allocationLines":[{"id":"41","receiptLineId":"2d5b81f7-4c93-4a16-8e70-5f1c9d3a82b4","itemCode":"WIDGET-01","quantity":"40","currentUnitCost":"12","additionalCostAmount":"240","newUnitCost":"18","revaluationDocuments":[]}]}]`. |
| `items[].id` | string | yes | The unique identifier for the landed cost. Format: UUID. |
| `items[].documentNumber` | string | no | The landed cost number, for example 'LC-1007'. |
| `items[].documentStatus` | string | yes | The status of the landed cost. Possible values: 'DRAFT', 'COMMITTED'. |
| `items[].documentDate` | date | no | The date of the landed cost. Format: YYYY-MM-DD. |
| `items[].entityId` | string | no | The unique identifier of the legal entity the landed cost belongs to. Format: UUID. See `id` on GET base/entities (entities). |
| `items[].entityName` | string | no | The name of the legal entity in `entityId`. |
| `items[].currency` | string | no | The currency of every amount on the landed cost, which is the functional currency of its legal entity. Format: ISO 4217, for example 'GBP'. |
| `items[].notes` | string | no | Free text on the landed cost. |
| `items[].totalChargeAmount` | decimal | no | The total of the selected charges, in the landed cost's currency. |
| `items[].receiptCount` | number | no | The number of receipts on the landed cost. |
| `items[].chargeCount` | number | no | The number of charges on the landed cost. |
| `items[].allocationLineCount` | number | no | The number of allocation lines on the landed cost. |
| `items[].createdDate` | date-time | no | The date and time the landed cost was created, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].lastModifiedDate` | date-time | no | The date and time the landed cost last changed, in UTC. Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].receipts` | array<object> | no | The receipts whose stock the charges are spread over, with their lines. |
| `items[].receipts[].id` | string | yes | The unique identifier of the receipt. Format: UUID. See `id` on GET inventory/receipts/:id (getReceipt). |
| `items[].receipts[].receiptNumber` | string | no | The receipt's number. |
| `items[].receipts[].documentDate` | date | no | The date of the receipt. Format: YYYY-MM-DD. |
| `items[].receipts[].documentStatus` | string | no | The status of the receipt. See `documentStatus` on GET inventory/receipts/:id (getReceipt). |
| `items[].receipts[].lines` | array<object> | no | The lines of the receipt. Every line is included, whether or not the charges are spread over it. |
| `items[].receipts[].lines[].id` | string | yes | The unique identifier of the receipt line. Format: UUID. It is the `id` you send in `selectedLineIds`. See `lines[].id` on GET inventory/receipts/:id (getReceipt). |
| `items[].receipts[].lines[].isSelected` | boolean | no | Whether the charges are spread over the line. |
| `items[].receipts[].lines[].itemId` | string | no | The unique identifier of the item received on the line. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `items[].receipts[].lines[].itemCode` | string | no | The code of the item in `itemId`. |
| `items[].receipts[].lines[].itemName` | string | no | The name of the item in `itemId`. |
| `items[].receipts[].lines[].locationId` | string | no | The unique identifier of the warehouse that received the stock on the receipt line. Format: UUID. See `id` on GET inventory/warehouses/:id (getWarehouse). |
| `items[].receipts[].lines[].quantity` | decimal | no | The quantity of stock the receipt line brought in, in the unit of measure used on the receipt line. It is the quantity received, not the quantity in stock now. See `lines[].unitId` on GET inventory/receipts/:id (getReceipt). |
| `items[].receipts[].lines[].inventoryQuantity` | decimal | no | The quantity of stock the receipt line brought in, in the item's stocking unit. |
| `items[].receipts[].lines[].unitPrice` | decimal | no | The price the line was received at, per unit, in the landed cost's currency. |
| `items[].receipts[].lines[].lineTotal` | decimal | no | The total for the line, in the landed cost's currency. |
| `items[].charges` | array<object> | no | The charges of the landed cost. Each charge comes from a line of a vendor bill. |
| `items[].charges[].id` | string | yes | The unique identifier of the vendor bill line the charge comes from. Format: UUID. See `id` on GET inventory/landed-costs/vendor-bill-lines (getAvailableCharges). |
| `items[].charges[].vendorBillId` | string | no | The unique identifier of the vendor bill the line belongs to. Format: UUID. See `id` on GET accounting/vendor-bills/:id (getVendorBill). |
| `items[].charges[].vendorBillNumber` | string | no | The vendor bill's number. |
| `items[].charges[].itemId` | string | no | The unique identifier of the item on the vendor bill line. Format: UUID. Absent when the line has no item. See `id` on GET inventory/items/:id (getItem). |
| `items[].charges[].itemCode` | string | no | The code of the item in `itemId`. |
| `items[].charges[].itemName` | string | no | The name of the item in `itemId`. When the vendor bill line has no item, the line's description is used. |
| `items[].charges[].allocationMode` | string | no | How this charge is spread (allocated) over the receipt lines. Possible values: 'Equal', 'Quantity', 'LineTotal', 'Weight', 'Volume'. |
| `items[].charges[].amount` | decimal | no | The amount of the charge this landed cost takes, in the landed cost's currency. |
| `items[].charges[].allocatedAmount` | decimal | no | The amount of the charge that the commit used (allocated), in the landed cost's currency. After the commit, it equals `amount`. It is absent before the commit, and on charges whose `isSelected` is false. |
| `items[].charges[].isSelected` | boolean | no | Whether the charge is spread over the receipt lines. A charge set to false is kept in the landed cost's charges, but the commit does not spread it. |
| `items[].allocationLines` | array<object> | no | The allocation of the charges over the receipt lines, with one allocation line for each selected receipt line that has an inventory item. It is calculated when the landed cost is created or updated. |
| `items[].allocationLines[].id` | string | yes | The identifier of the allocation line. It is a number sent as a string, not a UUID. |
| `items[].allocationLines[].receiptId` | string | no | The unique identifier of the receipt. Format: UUID. See `id` on GET inventory/receipts/:id (getReceipt). |
| `items[].allocationLines[].receiptLineId` | string | no | The unique identifier of the receipt line. Format: UUID. See `lines[].id` on GET inventory/receipts/:id (getReceipt). |
| `items[].allocationLines[].itemId` | string | no | The unique identifier of the item on the receipt line. Format: UUID. See `id` on GET inventory/items/:id (getItem). |
| `items[].allocationLines[].itemCode` | string | no | The code of the item in `itemId`. |
| `items[].allocationLines[].itemName` | string | no | The name of the item in `itemId`. |
| `items[].allocationLines[].locationId` | string | no | The unique identifier of the warehouse that received the stock on the receipt line. Format: UUID. See `id` on GET inventory/warehouses/:id (getWarehouse). |
| `items[].allocationLines[].locationCode` | string | no | The code of the warehouse in `locationId`. |
| `items[].allocationLines[].quantity` | decimal | no | The quantity received on the receipt line, in the item's stocking unit. |
| `items[].allocationLines[].currentUnitCost` | decimal | no | The cost of one unit of the item in the warehouse before the charges, in the landed cost's currency, at the time the landed cost was created or last updated. It is the item's average cost, or the receipt line's unit price when there is no average cost. When you commit the landed cost, the commit uses the item's cost at that moment, which can differ from this cost. |
| `items[].allocationLines[].additionalCostAmount` | decimal | no | This receipt line's share of the charges, in the landed cost's currency. It is the share for the whole line, not for one unit. |
| `items[].allocationLines[].newUnitCost` | decimal | no | The cost of one unit of the item with the charges, in the landed cost's currency. It is `currentUnitCost` plus this line's share of the charges for one unit. The share for one unit is `additionalCostAmount` divided by `quantity`. The commit can end with a different cost, because it uses the item's cost at the time of the commit. |
| `items[].allocationLines[].revaluationDocuments` | array<object> | no | The inventory revaluations that the commit created for this allocation line. It is empty before the commit. It has more than one inventory revaluation when the line's charges have different expense accounts or costing element types. |
| `items[].allocationLines[].revaluationDocuments[].id` | string | yes | The unique identifier of the inventory revaluation. Format: UUID. See `id` on GET inventory/inventory-revaluations/:id (getInventoryRevaluation). |
| `items[].allocationLines[].revaluationDocuments[].documentNumber` | string | no | The inventory revaluation number. |
| `items[].allocationLines[].revaluationDocuments[].documentStatus` | string | no | The status of the inventory revaluation. |
| `pagination` | object | yes | Whether there are more results than are in this response, and the cursor you use to get the next ones. Example: `{"hasMore":false}`. |
| `pagination.nextCursor` | string | no | The cursor that marks where this response stopped. To get the next results, send it as `page.cursor` in your next request. Absent when there are no more results. |
| `pagination.hasMore` | boolean | no | Whether there are more results than are in this response. |

```json
{
  "data": {
    "items": [
      {
        "id": "6d18b2f0-49c7-4a35-9e81-2f0c5a7d3b64",
        "documentNumber": "LC-1007",
        "documentStatus": "DRAFT",
        "documentDate": "2026-08-18",
        "entityId": "7039b992-696a-40c7-a181-51759304ef83",
        "entityName": "Flow UK",
        "currency": "GBP",
        "totalChargeAmount": "240",
        "receiptCount": 1,
        "chargeCount": 1,
        "allocationLineCount": 1,
        "lastModifiedDate": "2026-08-18T09:14:22.517Z",
        "receipts": [
          {
            "id": "b1a7c930-5e46-4f82-8d05-71c3e9a24f68",
            "receiptNumber": "REC-2210",
            "documentStatus": "COMMITTED",
            "lines": [
              {
                "id": "2d5b81f7-4c93-4a16-8e70-5f1c9d3a82b4",
                "isSelected": true,
                "itemCode": "WIDGET-01",
                "quantity": "40",
                "unitPrice": "12",
                "lineTotal": "480"
              }
            ]
          }
        ],
        "charges": [
          {
            "id": "9c47e1b8-2a63-4d05-b7f9-04e28d5a1c37",
            "vendorBillNumber": "VB-8842",
            "itemCode": "SVC-FREIGHT",
            "allocationMode": "Quantity",
            "amount": "240",
            "isSelected": true
          }
        ],
        "allocationLines": [
          {
            "id": "41",
            "receiptLineId": "2d5b81f7-4c93-4a16-8e70-5f1c9d3a82b4",
            "itemCode": "WIDGET-01",
            "quantity": "40",
            "currentUnitCost": "12",
            "additionalCostAmount": "240",
            "newUnitCost": "18",
            "revaluationDocuments": []
          }
        ]
      }
    ],
    "pagination": {
      "hasMore": false
    }
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}
```

## Statuses

- `400` — Invalid request or business failure
- `401` — The request carries no valid access token.
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests from this client address. The response has no body and no `Retry-After` header.
- `500` — Internal server error