# Returns the sales order shipments that match the given filters.

`POST /accounting/sales-order-shipments/search`

Group: Accounting › Sales Order Shipments · Operation ID: `searchSalesOrderShipments`

This endpoint takes the criteria a query string cannot: free-text matching on carrier, tracking id, shipment number and incoterm, the shipping contact email, several statuses at once, the customer's requested delivery date, and the shipped sales order product item. The text filters match a case-insensitive substring.

Every filter is optional and they are combined with AND. Omit them all to match every shipment. The id, warehouse and date-range filters that GET accounting/sales-order-shipments also serves are available here too.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchSalesOrderShipments)

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | no | The filters to apply. A shipment must match every filter you send. Omit to return all shipments. |
| `filters.salesOrderId` | string | no | Limits results to shipments that fulfill this sales order. See id on GET accounting/sales-orders/:id. |
| `filters.inventoryShipmentId` | number | no | Limits results to the shipment mirroring this inventory shipment, given as its numeric inventory shipment id. At most one shipment matches. |
| `filters.warehouseId` | string | no | Limits results to shipments dispatched from this warehouse location. See id on GET inventory/warehouses/:id. |
| `filters.status` | array of string, one of `"pendingShipment"`, `"shipped"`, `"cancelled"` | no | Limits results to shipments in any of these states. Omit or pass an empty array to match every state. |
| `filters.salesOrderProductItemId` | string | no | Limits results to shipments that have a line for this sales order product item. This is how you find the shipments covering one ordered item. There is no endpoint for it. |
| `filters.shipmentNumber` | string | no | Limits results to shipments whose shipment number contains this text. The match is case-insensitive. |
| `filters.trackingId` | string | no | Limits results to shipments whose tracking number or URL contains this text. The match is case-insensitive. |
| `filters.carrier` | string | no | Limits results to shipments whose carrier name contains this text. The match is case-insensitive. |
| `filters.incoterm` | string | no | Limits results to shipments whose incoterm contains this text. The match is case-insensitive. |
| `filters.shipToContactEmail` | string | no | Limits results to shipments whose shipping contact email contains this text. The match is case-insensitive. |
| `filters.shipDate` | object | no | Limits results by dispatch date. Both bounds are inclusive. Omit one to leave that side open. |
| `filters.shipDate.start` | string (date) | no | The earliest dispatch date to include, inclusive. Format YYYY-MM-DD. |
| `filters.shipDate.end` | string (date) | no | The latest dispatch date to include, inclusive. Format YYYY-MM-DD. |
| `filters.deliveryDate` | object | no | Limits results by delivery date. Both bounds are inclusive. Omit one to leave that side open. |
| `filters.deliveryDate.start` | string (date) | no | The earliest delivery date to include, inclusive. Format YYYY-MM-DD. |
| `filters.deliveryDate.end` | string (date) | no | The latest delivery date to include, inclusive. Format YYYY-MM-DD. |
| `filters.customerRequestDate` | object | no | Limits results by the date the customer requested delivery. Both bounds are inclusive. Omit one to leave that side open. |
| `filters.customerRequestDate.start` | string (date) | no | The earliest requested delivery date to include, inclusive. Format YYYY-MM-DD. |
| `filters.customerRequestDate.end` | string (date) | no | The latest requested delivery date to include, inclusive. Format YYYY-MM-DD. |
| `filters.lastModifiedDate` | object | no | Limits results by last change. Both bounds are inclusive. Format YYYY-MM-DDTHH:mm:ss.sssZ in UTC. Omit one to leave that side open. |
| `filters.lastModifiedDate.start` | string (date-time) | no | The earliest change time to include, inclusive. Format YYYY-MM-DDTHH:mm:ss.sssZ in UTC. |
| `filters.lastModifiedDate.end` | string (date-time) | no | The latest change time to include, inclusive. Format YYYY-MM-DDTHH:mm:ss.sssZ in UTC. |
| `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 for the first page. |
| `page.size` | number | no | The number of shipments per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "filters": {
    "carrier": "dhl",
    "status": [
      "pendingShipment",
      "shipped"
    ]
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchSalesOrderShipmentsOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The shipments on this page, ordered by ship date with the most recent first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the sales order shipment. |
| `items[].salesOrderId` | string | yes | The sales order this shipment fulfills. See id on GET accounting/sales-orders/:id. |
| `items[].inventoryShipmentId` | number | no | The numeric identifier of the shipment document in inventory, which owns the shipment. Absent only on legacy rows written before the mirroring existed. |
| `items[].shipmentNumber` | string | no | The shipment document number, assigned by inventory. Absent until inventory has issued one. |
| `items[].status` | string | no | The lifecycle status of the shipment. Possible values: 'pendingShipment', 'shipped', 'cancelled'. 'pendingShipment' is drafted in inventory but not yet dispatched, 'shipped' is dispatched, and 'cancelled' means the inventory shipment was deleted and this mirror was soft-cancelled. |
| `items[].trackingId` | string | no | The carrier tracking number or tracking URL, when one has been recorded. |
| `items[].carrier` | string | no | The name of the carrier handling the shipment. |
| `items[].incoterm` | string | no | The incoterm governing shipping responsibility for this shipment. For example 'DAP' or 'EXW'. |
| `items[].warehouseId` | string | no | The warehouse location the shipment is dispatched from. See id on GET inventory/warehouses/:id. |
| `items[].shipToContactEmail` | string | no | The email of the contact who receives this shipment. |
| `items[].customerRequestDate` | string (date) | no | The date the customer asked for delivery. Format YYYY-MM-DD. |
| `items[].shipDate` | string (date) | no | The date the shipment was dispatched. Format YYYY-MM-DD. Absent while the shipment is still pending. |
| `items[].deliveryDate` | string (date) | no | The date the shipment was, or is expected to be, delivered. Format YYYY-MM-DD. |
| `items[].lastModifiedDate` | string (date-time) | yes | The date and time the shipment last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].items` | array of object | yes | The shipped lines, oldest first. An empty array when the shipment has no lines. |
| `items[].items[].id` | string | yes | The unique identifier for the shipment line. PATCH matches updateItems and deleteItems on it. |
| `items[].items[].salesOrderProductItemId` | string | yes | The sales order product item this line ships. There is no endpoint for it. |
| `items[].items[].shippedQty` | string (decimal) | yes | The quantity shipped on this line, as a count of units. |
| `items[].items[].orderedQty` | string (decimal) | yes | The total quantity ordered for the underlying sales order product item, as a count of units. |
| `items[].items[].unshippedQty` | string (decimal) | yes | The quantity still outstanding on this line, as a count of units: orderedQty minus shippedQty. |
| `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 | yes | True when more shipments 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