For AI agents: markdown of this page — /docs-content-en/entities/shipment-items/list.md documentation index — /llms.txt

List shipment items

GET /v1/shipment-items

Returns a list of online store order shipment items with filtering, sorting and automatic pagination.

Parameters

Parameter Type Default Description
limit (query) number 50 Number of records, from 1 to 5000. A value above 5000 is capped at 5000 without an error
offset (query) number 0 Skip N records: offset=7 starts the selection at the 8th record
select (query) string — Comma-separated fields to return: ?select=id,orderDeliveryId,quantity. An unknown field does not cause an error: it is absent from the data items, and meta.warnings carries an UNKNOWN_SELECT_FIELD warning with the field name in field
sort (query) string — Sorting in short syntax: ?sort=-id, a minus means descending
order (query) object — Sorting: ?order[id]=desc
filter (query) object — Filtering by the fields of GET /v1/shipment-items/fields.
Filtering syntax. Example: ?filter[orderDeliveryId]=1207
withTotal (query) string — Whether to return the record count in meta.total: true or false. Details — Paging and record counts

Pagination. With limit > 50, Vibecode assembles the response from several sequential reads of 50 records each and returns all records in one response. meta.hasMore shows whether more records remain.

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/shipment-items?filter[basketId]=1387" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/shipment-items?filter[basketId]=1387" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items?filter[basketId]=1387', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
const total = data.reduce((sum, item) => sum + item.quantity, 0)
console.log(`Basket item is split across ${data.length} shipments, ${total} in total`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items?filter[basketId]=1387', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of shipment items
data[].id number Shipment item ID
data[].orderDeliveryId number Shipment ID. List: GET /v1/shipments
data[].basketId number Basket item ID. List: GET /v1/basket-items
data[].quantity number Product quantity in the shipment, can be fractional
data[].reservedQuantity number Reserved quantity
data[].xmlId string External item code
data[].dateInsert datetime Creation date, ISO 8601
meta.total number Total number of records matching the filter. May be absent — see the withTotal parameter
meta.hasMore boolean Whether more records exist beyond limit
meta.warnings array Warnings about request parameters: code, message, field. Present only when there are warnings
meta.pageErrorSample object Code and text of the error that stopped automatic pagination early. data then contains the records up to the stopping point

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "basketId": 1387,
      "dateInsert": "2026-10-04T22:01:08.000Z",
      "id": 1347,
      "orderDeliveryId": 1195,
      "quantity": 0.25,
      "reservedQuantity": 0,
      "xmlId": "bx_6ac2be9427875"
    },
    {
      "basketId": 1387,
      "dateInsert": "2026-10-07T09:55:27.000Z",
      "id": 1353,
      "orderDeliveryId": 1207,
      "quantity": 0.75,
      "reservedQuantity": 0,
      "xmlId": "vibe-doc-si-1"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

Error response example

400 — filter by a nonexistent field:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'foo' for entity 'shipment-items'. Available: basketId, dateInsert, id, orderDeliveryId, quantity, reservedQuantity, xmlId"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD Filter by a field that is not in the schema. Field list: GET /v1/shipment-items/fields
400 INVALID_FILTER_FIELD The field name in the filter starts with the unsupported prefix @ or !@
400 INVALID_FILTER_OPERATOR Unknown filter operator, an empty object as a condition value, or the logical condition $or
400 INVALID_FILTER The filter parameter is neither an object nor a JSON string, or both filter notations are mixed in one request
400 INVALID_DUPLICATE_FILTER_FIELD Two filter conditions reduce to the same Bitrix24 condition, for example $ne and != on one field. Pass only one of them
400 UNKNOWN_SORT_FIELD Sorting by a field that is not in the schema
400 INVALID_SORT_DIRECTION The direction in order or in the object form of sort is not one of asc, desc, ASC, DESC, 1, -1
403 SCOPE_DENIED The API key does not have the sale scope
403 MANAGEMENT_KEY_NO_ENTITY_ACCESS The request was made with a management key. Entities require an application key or a personal key with the sale scope
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY The API key was not found
401 TOKEN_MISSING The API key has no configured tokens
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — Errors.

Known specifics

The selection includes rows of the system shipment. A filter by basketId returns all shipments the basket item is distributed across, including the system shipment holding the undistributed remainder. In the example above, basket item 1387 with quantity 1 is split into 0.75 in shipment 1207 and 0.25 in system shipment 1195. Details — What to know before you start.

Not every list row opens by id. Items of the system shipment and items of shipments that no longer exist appear in the list, but GET /v1/shipment-items/:id returns 404 for them. In the example above, item 1347 gets this response. To get the contents of a specific shipment, use this list with filter[orderDeliveryId].

When to use search instead of list: POST /v1/shipment-items/search passes parameters in the request body rather than the query string, and splits the selection into time windows when filtering by a dateInsert range wider than 14 days.

See also