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

Aggregate basket items

POST /v1/basket-items/aggregate

Counts items and computes numeric aggregations (sum, avg, min, max) over the price and quantity fields. Supports filtering and grouping by orderId, productId, currency.

Standard fields

Field Purpose
Fieldprice PurposeNumeric — suitable for sum / avg / min / max (aggregations over the unit price)
Fieldquantity PurposeNumeric — suitable for sum / avg / min / max (aggregations over quantity)
Fieldcurrency PurposeCategorical — used in groupBy (by currency)
FieldorderId, productId PurposeIdentifiers — used in groupBy (by order or product)

The full list of aggregatable fields is shown in the table above.

Request fields (body)

Parameter Type Required Description
Parameteraggregate Typearray Requiredno DescriptionArray of aggregations: [{ "field": "quantity", "function": "sum" }]. Functions: count, sum, avg, min, max. For count, the field is "*". Without the parameter — count only
Parameterfilter Typeobject Requiredno DescriptionFiltering — the same fields as in GET /v1/basket-items. Filtering syntax
ParametergroupBy Typestring | string[] Requiredno DescriptionA field or array of fields to group by (maximum 5)
ParametergroupOrderBy Typearray Requiredno DescriptionGroup sorting: [{ "field": "quantity:sum", "direction": "desc" }]
ParametergroupLimit Typenumber Requiredno DescriptionLimit on the number of returned groups (1-1000)

Examples

curl — personal key

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

curl — OAuth application

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

JavaScript — personal key

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

const { success, data } = await res.json()
console.log('Top 5 products by sales:', data.groups)

JavaScript — OAuth application

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

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" }] }

Total value of all items in an order:

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

Top 3 products by total sales:

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

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.count Typenumber DescriptionTotal number of items matching the filter
Fielddata.aggregates Typeobject DescriptionAggregation results: { "quantity": { "sum": ... }, "price": { "avg": ... } }
Fielddata.groups Typearray DescriptionGroups (only with groupBy)
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of records
Fielddata.meta.recordsProcessed Typenumber DescriptionNumber of processed records (up to 5000)
Fielddata.meta.truncated Typeboolean Descriptiontrue when the numbers were computed over only some of the records that match the filter: fewer records were read than data.count promised — including when more than 5000 matched the filter — or the slice was cut short by a sub-page error. The size of the gap is reported in data.meta.recordsShortfall, the interrupted slice in data.meta.pageErrorSample. Always present, and false on a complete response. If the request has neither groupBy nor a numeric function, no records are fetched and the flag is always false
Fielddata.meta.groupTotal Typenumber DescriptionNumber of groups before groupLimit
Fielddata.meta.groupsTruncated Typeboolean DescriptionWhether the group list was truncated by groupLimit

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 261,
    "aggregates": {
      "quantity": { "sum": 412 }
    },
    "groups": [
      {
        "productId": 119,
        "count": 23,
        "aggregates": { "quantity": { "sum": 47 } }
      },
      {
        "productId": 245,
        "count": 18,
        "aggregates": { "quantity": { "sum": 36 } }
      },
      {
        "productId": 87,
        "count": 14,
        "aggregates": { "quantity": { "sum": 21 } }
      }
    ],
    "meta": {
      "totalRecords": 261,
      "recordsProcessed": 261,
      "truncated": false,
      "groupTotal": 89,
      "groupsTruncated": true
    }
  }
}

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

Error response example

400 — a field in groupBy does not support aggregation:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'foo' is not aggregatable on this entity. Available: price, quantity, currency, orderId, productId."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionUnknown aggregation function
HTTP400 CodeINVALID_PARAMS DescriptionNon-existent numeric field in aggregate[].field — message Field 'foo' not found. Available numeric fields: …
HTTP400 CodeINVALID_PARAMS DescriptionA field in groupBy does not support aggregation — the message contains the list of allowed fields
HTTP400 CodeINVALID_PARAMS DescriptionMore than 5 fields passed in groupBy
HTTP400 CodeINVALID_PARAMS DescriptionReserved keywords in groupBy: count, aggregates, meta, groups
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks 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 exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

count versus numeric functions. count is computed in a single request to Bitrix24 — records are not fetched and the response returns quickly at any volume. sum / avg / min / max fetch records page by page (up to 5000) and compute on the Vibecode side. With more than 5000 records, meta.truncated will be true. The ceiling is not the only reason for this marker: it also appears when fewer records were read than data.count promised, and the size of the gap is reported in data.meta.recordsShortfall.

Including unfinished baskets. The result set also includes items with orderId: null (products in unfinished baskets). To exclude them, add filter[orderId][!]=null.

The truncation marker travels with the number itself. When a response arrives with meta.truncated: true, the marker truncated: true sits inside every field object in data.aggregates and on every element of data.groups, and data.meta.warnings gains a warning with the code AGGREGATE_TRUNCATED. A client that reads only the number itself therefore sees that it was computed over only some of the records. None of these markers appear on a complete response. Full details — Aggregation POST — the 5000-record ceiling.

See also