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
Parameterlimit (query) Typenumber Default50 DescriptionNumber of records, from 1 to 5000. A value above 5000 is capped at 5000 without an error
Parameteroffset (query) Typenumber Default0 DescriptionSkip N records: offset=7 starts the selection at the 8th record
Parameterselect (query) Typestring Default— DescriptionComma-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
Parametersort (query) Typestring Default— DescriptionSort using shorthand syntax: ?sort=-id. A minus sign indicates descending order
Parameterorder (query) Typeobject Default— DescriptionSorting: ?order[id]=desc
Parameterfilter (query) Typeobject Default— DescriptionFiltering by the fields of GET /v1/shipment-items/fields.
Filtering syntax. Example: ?filter[orderDeliveryId]=1207
ParameterwithTotal (query) Typestring Default— DescriptionWhether 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of shipment items
Fielddata[].id Typenumber DescriptionShipment item ID
Fielddata[].orderDeliveryId Typenumber DescriptionShipment ID. List: GET /v1/shipments
Fielddata[].basketId Typenumber DescriptionBasket item ID. List: GET /v1/basket-items
Fielddata[].quantity Typenumber DescriptionProduct quantity in the shipment, can be fractional
Fielddata[].reservedQuantity Typenumber DescriptionReserved quantity
Fielddata[].xmlId Typestring DescriptionExternal item code
Fielddata[].dateInsert Typedatetime DescriptionCreation date, ISO 8601
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter. May be absent — see the withTotal parameter
Fieldmeta.hasMore Typeboolean DescriptionWhether more records exist beyond limit
Fieldmeta.warnings Typearray DescriptionWarnings about request parameters: code, message, field. Present only when there are warnings
Fieldmeta.pageErrorSample Typeobject DescriptionCode 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
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionFilter by a field that is not in the schema. Field list: GET /v1/shipment-items/fields
HTTP400 CodeINVALID_FILTER_FIELD DescriptionThe field name in the filter starts with the unsupported prefix @ or !@
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionUnknown filter operator, an empty object as a condition value, or the logical condition $or
HTTP400 CodeINVALID_FILTER DescriptionThe filter parameter is neither an object nor a JSON string, or both filter notations are mixed in one request
HTTP400 CodeINVALID_DUPLICATE_FILTER_FIELD DescriptionTwo filter conditions reduce to the same Bitrix24 condition, for example $ne and != on one field. Pass only one of them
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting by a field that is not in the schema
HTTP400 CodeINVALID_SORT_DIRECTION DescriptionThe direction in order or in the object form of sort is not one of asc, desc, ASC, DESC, 1, -1
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP403 CodeMANAGEMENT_KEY_NO_ENTITY_ACCESS DescriptionThe request was made with a management key. Entities require an application key or a personal key with the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe API key was not found
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see 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 item in the list can be retrieved 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