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

Search shipment items

POST /v1/shipment-items/search

Searches online store order shipment items with filtering, sorting, and automatic pagination. Parameters are passed in the body of the POST request. Suited to complex filters and wide date ranges. For simple selections of up to 5000 records, the shipment item list is enough.

Request fields (body)

Field Type Required Default Description
Fieldfilter Typeobject Requiredno Default— DescriptionFiltering by the fields from GET /v1/shipment-items/fields.
Filtering syntax. Example: { "basketId": 1387 }
Fieldselect Typestring[] Requiredno Default— DescriptionField selection: ["id", "orderDeliveryId", "quantity"]. A comma-separated string is also accepted. 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
Fieldsort Typestring Requiredno Default— DescriptionSorting via the short syntax: "-id", where a leading minus means descending
Fieldorder Typeobject Requiredno Default— DescriptionSorting as an object: { "id": "asc" }. If sort is also passed, sort takes effect
Fieldlimit Typenumber Requiredno Default50 DescriptionNumber of records, from 1 to 5000. A value above 5000 is reduced to 5000 without an error
Fieldoffset Typenumber Requiredno Default0 DescriptionSkip N records. Rejected when combined with a date range filter wider than 14 days, unless autoWindow: false is passed — see UNSTABLE_OFFSET_PAGINATION in the "Errors" section
FieldautoWindow Typeboolean Requiredno Defaulttrue DescriptionSplit the selection into weekly windows when filtering by a dateInsert range wider than 14 days. false disables splitting
FieldwithTotal Typeboolean Requiredno Default— DescriptionWhether to return the record count in meta.total. Details — Paging and record counts

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipment-items/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "basketId": 1387 },
    "select": ["id", "orderDeliveryId", "quantity"],
    "order": { "id": "asc" }
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipment-items/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "basketId": 1387 },
    "select": ["id", "orderDeliveryId", "quantity"],
    "order": { "id": "asc" }
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { basketId: 1387 },
    select: ['id', 'orderDeliveryId', 'quantity'],
    order: { id: 'asc' },
  }),
})

const { success, data, meta } = await res.json()
for (const item of data) {
  console.log(`Shipment ${item.orderDeliveryId}: ${item.quantity}`)
}

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { basketId: 1387 },
    select: ['id', 'orderDeliveryId', 'quantity'],
    order: { id: 'asc' },
  }),
})

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 identifier
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; may be fractional
Fielddata[].reservedQuantity Typenumber DescriptionReserved quantity
Fielddata[].xmlId Typestring DescriptionExternal code of the item
Fielddata[].dateInsert Typedatetime DescriptionCreation date, ISO 8601
Fieldmeta.total Typenumber DescriptionHow many records matched the filter. May be absent — see the withTotal field
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit
Fieldmeta.durationMs Typenumber DescriptionRequest duration in milliseconds
Fieldmeta.autoWindowed Typeboolean Descriptiontrue if the selection was split into time windows
Fieldmeta.windowCount Typenumber DescriptionNumber of windows. Included when autoWindowed: true
Fieldmeta.windowErrors Typenumber DescriptionHow many windows ended with an error. Included if some windows failed
Fieldmeta.windowErrorSample Typeobject DescriptionError code and message of the first failed window. Included with windowErrors
Fieldmeta.batchWaves Typenumber DescriptionNumber of waves of parallel requests. Included when autoWindowed: true
Fieldmeta.warnings Typearray DescriptionWarnings about request parameters: code, message, field. Included only when there are warnings
Fieldmeta.hint Typestring DescriptionAdvice to narrow the date range or disable splitting. Included if the search processed more than 10 windows and took longer than 10 seconds
Fieldmeta.pageErrorSample Typeobject DescriptionCode and message of the error that stopped automatic pagination early. Included only if data contains fewer records than limit

Response example

A request with select returns only the listed fields:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1347,
      "orderDeliveryId": 1195,
      "quantity": 0.25
    },
    {
      "id": 1353,
      "orderDeliveryId": 1207,
      "quantity": 0.75
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false,
    "durationMs": 342
  }
}

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_SHAPE Descriptionfilter is not an object of conditions, for example a string, number, or array
HTTP400 CodeINVALID_DUPLICATE_FILTER_FIELD DescriptionTwo filter conditions reduce to one Bitrix24 condition, for example $ne and != on the same field. Pass only one of them
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting by a field that is not in the schema
HTTP400 CodeINVALID_SORT_TYPE Descriptionsort or order has an unsupported type, for example a number
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
HTTP400 CodeINVALID_LIMIT Descriptionlimit is not a number
HTTP400 CodeINVALID_SELECT_TYPE Descriptionselect is not a string or an array of strings
HTTP400 CodeINVALID_REQUEST DescriptionThe request body is not a JSON object
HTTP400 CodeUNSTABLE_OFFSET_PAGINATION Descriptionoffset greater than zero together with a filter by a date range wider than 14 days. Fetch everything in one request with limit up to 5000, or pass autoWindow: false with sorting by id, or split the date range into parts yourself
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 passed 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

Splitting into time windows. With windows, the selection gets past the cap of 5000 records per call. A range from January 1, 2025 to October 8, 2026 was split into 93 windows processed in three waves: meta.windowCount: 93, meta.batchWaves: 3. The same request with autoWindow: false returned the same 104 records in a single pass.

A partial window failure does not abort the request. If some of the windows failed, the response is returned with success: true and records only from the successful windows. Before treating the selection as complete, check that meta.windowErrors is absent.

See also