# Returns a list of shipments.

`GET /inventory/shipments`

Group: Inventory › Shipments · Operation ID: `shipments`

The collection returns shipment headers only, not their lines, and lineCount stands in for them. To get the lines, or to filter by customer, item, warehouse, reference number or tracking number, use POST inventory/shipments/search.

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

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

## Query surface

- `id` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `documentNumber` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `documentStatus` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `documentDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `deliveryDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `entityId` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `shipmentCarrierId` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `returnStatus` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- `lastModifiedDate` — filter by eq, ne, gt, gte, lt, lte, in, notIn, between, like
- Orderable: id, documentNumber, documentDate, deliveryDate, documentStatus, totalAmount, createdDate, lastModifiedDate
- Selectable: id, documentNumber, documentStatus, documentDate, deliveryDate, entityId, entityName, businessPartnerId, businessPartnerName, shipmentCarrierId, shipmentCarrierName, returnStatus, referenceNumber, trackingNumber, currency, totalAmount, lineCount, notes, createdDate, lastModifiedDate

## Response

`200` Success

Under `data`, an array of shipmentsRow:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | The unique identifier for the shipment. |
| `documentNumber` | string or null | no | The shipment's document number, for example 'SD-8841'. Absent while none has been assigned. |
| `documentStatus` | string | no | The status of the shipment. Possible values: 'DRAFT', 'PACKED', 'PARTIALLY_SHIPPED', 'SHIPPED', 'COMMITTED', 'DELIVERED', 'COMPLETED', 'CANCELLED', 'INVOICED', 'PARTIALLY_INVOICED', 'RETURNED', 'PARTIALLY_RETURNED'. |
| `documentDate` | string (date) | no | The date the shipment is dated. Format YYYY-MM-DD. |
| `deliveryDate` | string (date) or null | no | The planned or actual delivery date. Format YYYY-MM-DD. |
| `entityId` | string | no | The unique identifier for the legal entity the shipment belongs to. See id on GET base/entities. |
| `entityName` | string or null | no | The display name of that legal entity. |
| `businessPartnerId` | string | no | The unique identifier for the customer the goods go to. Despite the name, this is a customer id. See id on GET accounting/customers/:id. |
| `businessPartnerName` | string or null | no | The display name of that customer. |
| `shipmentCarrierId` | string or null | no | The unique identifier for the carrier taking the goods. See id on GET inventory/shipment-carriers/:id. |
| `shipmentCarrierName` | string or null | no | The name of that carrier. |
| `returnStatus` | string or null | no | How much of the shipment has come back on sales returns. Possible values: 'OPEN', 'PARTIALLY_RETURNED', 'FULLY_RETURNED'. The return process maintains it. |
| `referenceNumber` | string or null | no | The customer's own reference for the shipment. |
| `trackingNumber` | string or null | no | The carrier's tracking number for the goods. |
| `currency` | string or null | no | The currency of every amount on the shipment. Format ISO 4217, for example 'EUR'. |
| `totalAmount` | string (decimal) or null | no | The total value of the shipment, in the shipment's currency. |
| `lineCount` | number or null | no | The number of lines the shipment has. The collection does not return the lines themselves. |
| `notes` | string or null | no | Free text on the shipment. |
| `createdDate` | string (date-time) or null | no | The date and time the shipment was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `lastModifiedDate` | string (date-time) or null | no | The date and time the shipment record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |

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