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
filter object no — Filtering by the fields from GET /v1/shipment-items/fields.
Filtering syntax. Example: { "basketId": 1387 }
select string[] no — Field 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
sort string no — Sorting via the short syntax: "-id", where a leading minus means descending
order object no — Sorting as an object: { "id": "asc" }. If sort is also passed, sort takes effect
limit number no 50 Number of records, from 1 to 5000. A value above 5000 is reduced to 5000 without an error
offset number no 0 Skip 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
autoWindow boolean no true Split the selection into weekly windows when filtering by a dateInsert range wider than 14 days. false disables splitting
withTotal boolean no — Whether 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
success boolean Always true on success
data array Array of shipment items
data[].id number Shipment item identifier
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, may be fractional
data[].reservedQuantity number Reserved quantity
data[].xmlId string External code of the item
data[].dateInsert datetime Creation date, ISO 8601
meta.total number How many records matched the filter. May be absent — see the withTotal field
meta.hasMore boolean Whether there are more records beyond limit
meta.durationMs number Request duration in milliseconds
meta.autoWindowed boolean true if the selection was split into time windows
meta.windowCount number Number of windows. Arrives with autoWindowed: true
meta.windowErrors number How many windows ended with an error. Arrives if some of the windows failed
meta.windowErrorSample object Error code and message of the first failed window. Arrives together with windowErrors
meta.batchWaves number Number of waves of parallel requests. Arrives with autoWindowed: true
meta.warnings array Warnings about request parameters: code, message, field. Arrives only when there are warnings
meta.hint string Advice to narrow the date range or disable splitting. Arrives if the search went through more than 10 windows and took longer than 10 seconds
meta.pageErrorSample object Code and message of the error that stopped automatic pagination early. Arrives only if data holds 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
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_SHAPE filter is not an object of conditions, for example a string, number, or array
400 INVALID_DUPLICATE_FILTER_FIELD Two filter conditions reduce to one Bitrix24 condition, for example $ne and != on the same field. Pass only one of them
400 UNKNOWN_SORT_FIELD Sorting by a field that is not in the schema
400 INVALID_SORT_TYPE sort or order has an unsupported type, for example a number
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
400 INVALID_LIMIT limit is not a number
400 INVALID_SELECT_TYPE select is not a string or an array of strings
400 INVALID_REQUEST The request body is not a JSON object
400 UNSTABLE_OFFSET_PAGINATION offset 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
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 passed 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

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 arrives with success: true and records only from the successful windows. Before treating the selection as complete, check that meta.windowErrors is absent.

See also