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

List orders

GET /v1/orders

Returns a list of online store orders with support for filtering and auto-pagination.

Parameters

Parameter Type Default Description
limit number 50 Number of records (up to 5000). When limit > 50, the response is assembled from several sequential reads of 50 records
offset number 0 Skip N records — row-exact: offset=7 starts at the 8th record. When offset ≥ 2500, limit ≤ 500 is recommended. For deep paging a cursor is more reliable — order[id]=asc plus filter[>id] set to the id of the last record of the previous response. Orders carry no meta.nextAfterId field, so take the identifier from the last element of data
select string — Field selection: ?select=id,price,currency,statusId
sort string — Sorting via the short syntax: ?sort=-id, the minus means descending
order object — Sorting: ?order[id]=desc
filter object — Filtering by GET /v1/orders/fields fields.
Filtering syntax. Example: ?filter[statusId]=N

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/orders?limit=10&filter[statusId]=N&order[id]=desc" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/orders?limit=10&filter[statusId]=N&order[id]=desc" \
  -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/orders?limit=10&filter[statusId]=N&order[id]=desc', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} orders`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/orders?limit=10&filter[statusId]=N&order[id]=desc', {
  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 orders (each contains all fields — see Order fields)
meta.total number Total number of records matching the filter
meta.hasMore boolean Whether there are more records beyond limit

The URL of any order in the data array is built from its id:

https://<portal>.bitrix24.com/shop/orders/details/<id>/

<portal> — the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 845,
      "accountNumber": "443",
      "price": 100,
      "currency": "USD",
      "statusId": "N",
      "userId": 1,
      "personTypeId": 5,
      "lid": "s1",
      "payed": false,
      "canceled": false,
      "responsibleId": 1,
      "dateInsert": "2026-04-21T06:48:16.000Z",
      "dateUpdate": "2026-04-21T06:48:16.000Z"
    },
    {
      "id": 841,
      "accountNumber": "441",
      "price": 100.5,
      "currency": "USD",
      "statusId": "N",
      "userId": 9,
      "personTypeId": 5,
      "lid": "s1",
      "payed": false,
      "canceled": false,
      "responsibleId": 1,
      "dateInsert": "2026-04-04T20:02:28.000Z",
      "dateUpdate": "2026-04-04T20:02:28.000Z"
    }
  ],
  "meta": {
    "total": 194,
    "hasMore": true
  }
}

The main fields are shown. Full list — Order fields.

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'sale' scope"
  }
}

Errors

HTTP Code Description
400 UNKNOWN_FILTER_FIELD Filter by a field not present in the schema. Field list: GET /v1/orders/fields
403 SCOPE_DENIED The API key does not have the sale scope
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

Auto-pagination: when limit > 50, Vibecode automatically requests several pages from Bitrix24 and returns all records in a single response. meta.total reflects the total number of records matching the filter.

When to use search instead of list: POST /v1/orders/search passes parameters in the request body rather than in the query string — suited for complex filters with many conditions.

See also