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

Aggregate orders

POST /v1/orders/aggregate

Count orders and numeric aggregations (sum, avg, min, max) over the price field. Supports filtering and grouping by statusId, payed, canceled, personTypeId, responsibleId, userId.

Standard fields

Field Purpose
price The only numeric field — suitable for sum / avg / min / max
statusId Categorical — used in groupBy (order statuses)
payed, canceled Boolean — used in groupBy (paid / canceled)
personTypeId, responsibleId, userId Identifiers — used in groupBy (by payer type, responsible employee, buyer)

Full list of aggregatable fields — the aggregatable array in GET /v1/orders/fields.

Request fields (body)

Field Type Required Description
aggregate array no Array of aggregations: [{ "field": "price", "function": "sum" }]. Functions: count, sum, avg, min, max. For count, the field is "*". Without the parameter — only count (a single request to Bitrix24, records are not fetched)
filter object no Filtering — the same fields as in GET /v1/orders. Filter syntax
groupBy string | string[] no Field or array of fields to group by (maximum 5). Allowed values — from the aggregatable array
groupOrderBy array no Group sorting: [{ "field": "price:sum", "direction": "desc" }]. Fields: count, a dim name from groupBy, or <field>:<function>
groupLimit number no Limit on the number of returned groups (1-1000)

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/orders/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "price", "function": "sum" },
      { "field": "price", "function": "avg" }
    ],
    "groupBy": "statusId"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/orders/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "aggregate": [
      { "field": "price", "function": "sum" },
      { "field": "price", "function": "avg" }
    ],
    "groupBy": "statusId"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/orders/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [
      { field: 'price', function: 'sum' },
      { field: 'price', function: 'avg' },
    ],
    groupBy: 'statusId',
  }),
})

const { success, data } = await res.json()
// data.groups — array of groups by statusId
console.log(data.groups)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/orders/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    aggregate: [{ field: 'price', function: 'sum' }],
    groupBy: 'statusId',
  }),
})

const { success, data } = await res.json()

Other scenarios

Count records — count with field "*", the fastest request without fetching records. Without the aggregate array the result is the same:

JSON 
{ "aggregate": [{ "field": "*", "function": "count" }] }

Sum across all orders without grouping:

JSON 
{
  "aggregate": [{ "field": "price", "function": "sum" }]
}

Top 3 statuses by payment sum, sorted:

JSON 
{
  "aggregate": [{ "field": "price", "function": "sum" }],
  "groupBy": "statusId",
  "groupOrderBy": [{ "field": "price:sum", "direction": "desc" }],
  "groupLimit": 3
}

Response fields

Field Type Description
success boolean Always true on success
data.count number Total number of orders matching the filter
data.aggregates object Aggregation results: { "price": { "sum": ..., "avg": ... } }
data.groups array Groups (present only when groupBy is set). Each element: grouping fields + count + aggregates
data.meta.totalRecords number Total number of records processed for the aggregation
data.meta.recordsProcessed number Number of records processed (up to 5000)
data.meta.truncated boolean true if there are more than 5000 records — aggregation runs over the first 5000
data.meta.groupTotal number Number of groups before groupLimit is applied (only when groupBy is set)
data.meta.groupsTruncated boolean Whether the group list was truncated by groupLimit

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 194,
    "aggregates": {
      "price": { "sum": 2890284.0999999996 }
    },
    "groups": [
      {
        "statusId": "N",
        "count": 181,
        "aggregates": { "price": { "sum": 2876316.6299999994 } }
      },
      {
        "statusId": "T",
        "count": 8,
        "aggregates": { "price": { "sum": 2998.5 } }
      },
      {
        "statusId": "P",
        "count": 6,
        "aggregates": { "price": { "sum": 9958.97 } }
      },
      {
        "statusId": "F",
        "count": 1,
        "aggregates": { "price": { "sum": 1010 } }
      },
      {
        "statusId": "S",
        "count": 1,
        "aggregates": { "price": { "sum": 0 } }
      }
    ],
    "meta": {
      "totalRecords": 194,
      "recordsProcessed": 194,
      "truncated": false,
      "groupTotal": 5,
      "groupsTruncated": false
    }
  }
}

Without groupBy, the data.groups field is absent from the response.

Error response example

400 — field in groupBy is not aggregatable:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'foo' is not aggregatable on this entity. Available: price, statusId, payed, canceled, personTypeId, responsibleId, userId."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS Unknown function or non-existent field in aggregate / groupBy — the message contains the list of allowed fields
400 INVALID_PARAMS More than 5 fields passed in groupBy
400 INVALID_PARAMS Reserved keywords in groupBy: count, aggregates, meta, groups
403 SCOPE_DENIED The API key does not have the sale scope
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

count vs numeric functions. count is computed with a single request to Bitrix24 — records are not fetched, the response time does not depend on the number of orders. sum / avg / min / max load records page by page (maximum 5000) and compute on the Vibecode side. With more than 5000 records, meta.truncated will be true, and the aggregation runs over the first 5000.

Boolean fields in grouping. groupBy: "payed" or groupBy: "canceled" returns groups with true / false values.

See also