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

List payments

GET /v1/payments

Returns a list of order payments with support for filtering and auto-pagination.

Parameters

Parameter Type Default Description
Parameterlimit Typenumber Default50 DescriptionNumber of records (up to 5000). When limit > 50, Vibecode automatically requests several pages from Bitrix24
Parameteroffset Typenumber Default0 DescriptionSkip N records. When offset ≥ 2500, limit ≤ 500 is recommended
Parameterselect Typestring Default— DescriptionField selection: ?select=id,orderId,sum,paid
Parametersort Typestring Default— DescriptionSorting via the short syntax: ?sort=-id, the minus means descending
Parameterorder Typeobject Default— DescriptionSorting: ?order[id]=desc
Parameterfilter Typeobject Default— DescriptionFiltering by key payment fields.
Filtering syntax. Example: ?filter[orderId]=19

Examples

curl — personal key

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

curl — OAuth application

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

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/payments?limit=10&filter[paid]=true&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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typearray DescriptionArray of payments (each contains all payment fields)
Fieldmeta.total Typenumber DescriptionTotal number of records matching the filter
Fieldmeta.hasMore Typeboolean DescriptionWhether there are more records beyond limit

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 17,
      "accountNumber": "19/1",
      "orderId": 19,
      "paySystemId": 11,
      "paySystemName": "Cash",
      "sum": 0,
      "currency": "USD",
      "paid": false,
      "datePaid": "2020-05-14T20:00:00.000Z",
      "dateBill": "2020-05-14T20:00:00.000Z",
      "responsibleId": 1,
      "isReturn": "N",
      "comments": "",
      "xmlId": "bx_5ebe943aacfa0"
    },
    {
      "id": 19,
      "accountNumber": "21/1",
      "orderId": 21,
      "paySystemId": 11,
      "paySystemName": "Cash",
      "sum": 0,
      "currency": "USD",
      "paid": false,
      "datePaid": "2020-05-17T20:00:00.000Z",
      "dateBill": "2020-05-17T20:00:00.000Z",
      "responsibleId": 1,
      "isReturn": "N",
      "comments": "",
      "xmlId": "bx_5ec2368b6e74d"
    }
  ],
  "meta": {
    "total": 99,
    "hasMore": true
  }
}

Key fields are shown. For the full payment response, see GET /v1/payments/:id.

Error response example

403 — no scope:

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

Errors

HTTP Code Description
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionFiltering by a field that is not in the payment schema
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
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

Auto-pagination: when limit > 50, Vibecode automatically requests several pages from Bitrix24 and returns all records in a single response.

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

The isReturn field is a string with three values. It accepts "N" (regular payment), "Y" (return) and "P" (partial return) — filtering by it works on these string values.

See also