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

List shipments

GET /v1/shipments

Returns a list of online store order shipments with support for 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 reduced to 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 field selection: ?select=id,orderId,deducted,trackingNumber. 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 via the short syntax: ?sort=-id, where a leading minus means descending order
order (query) object — Sorting: ?order[id]=desc
filter (query) object — Filtering by the fields from GET /v1/shipments/fields.
Filtering syntax. Example: ?filter[orderId]=1027
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 follow.

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/shipments?select=id,orderId,deducted,trackingNumber&filter[orderId]=1027" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/shipments?select=id,orderId,deducted,trackingNumber&filter[orderId]=1027" \
  -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/shipments?select=id,orderId,deducted,trackingNumber&filter[orderId]=1027', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Shipments in the order: ${data.length}`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipments?select=id,orderId,deducted,trackingNumber&filter[orderId]=1027', {
  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 shipments. All fields — Shipment fields
meta.total number Total number of records matching the filter. May be absent — see the withTotal parameter
meta.hasMore boolean Whether there are more records 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

A request with select returns only the listed fields:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1205,
      "orderId": 1027,
      "deducted": false,
      "trackingNumber": "VIBE-DOC-1"
    }
  ],
  "meta": {
    "total": 1,
    "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 'shipments'. Available: accountNumber, allowDelivery, basePriceDelivery, canceled, comments, companyId, currency, customPriceDelivery, dateAllowDelivery, dateCanceled, dateDeducted, dateInsert, dateMarked, dateResponsibleId, deducted, deliveryDocDate, deliveryDocNum, deliveryId, deliveryName, deliveryXmlId, discountPrice, empAllowDeliveryId, empCanceledId, empDeductedId, empMarkedId, empResponsibleId, externalDelivery, id, id1c, marked, orderId, priceDelivery, reasonMarked, reasonUndoDeducted, responsibleId, statusId, statusXmlId, system, trackingDescription, trackingLastCheck, trackingNumber, trackingStatus, updated1c, version1c, xmlId, shipmentItems"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD Filter by a field that is not in the schema. Field list: GET /v1/shipments/fields
400 INVALID_FILTER_FIELD The field name in the filter starts with the unsupported prefix @ or !@
400 INVALID_FILTER_OPERATOR Unknown filter operator, or the logical condition $or, which cannot be expressed in a query string
400 INVALID_FILTER The filter parameter is neither an object nor a JSON string, or one request mixes both filter notations
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 or cannot be sorted on
400 INVALID_SORT_DIRECTION The direction in order is not one of asc, desc, ASC, DESC, 1, -1
403 SCOPE_DENIED The API key does not have the sale scope
401 MISSING_API_KEY The X-Api-Key header is missing
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 list has no shipment items. The data items do not contain the shipmentItems field. The shipment contents are returned by GET /v1/shipments/:id.

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

See also