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

Aggregate basket item properties

POST /v1/basket-item-properties/aggregate

Counts basket item properties by filter and grouping fields, and calculates the sum, average, minimum, and maximum of numeric fields.

Standard fields

Field Purpose
FieldbasketId PurposeBasket item ID. Source: GET /v1/basket-items. For groupBy and numeric functions
Fieldcode PurposeProperty symbolic code — for groupBy
Fieldsort PurposeSort order — for sum, avg, min, max
Fieldid PurposeProperty ID. Source: GET /v1/basket-item-properties. A numeric field

Fields for groupBy are listed in data.aggregatable of GET /v1/basket-item-properties/fields. Numeric functions accept fields of type number: id, basketId, sort.

Request body fields

Field Type Required Description
Fieldaggregate Typearray Requiredno DescriptionAn array of expressions with field and function. Functions: count, sum, avg, min, max. For count, the field is "*". When omitted, defaults to [{ "field": "*", "function": "count" }]
Fieldfilter Typeobject Requiredno DescriptionFilter by fields from GET /v1/basket-item-properties/fields.
Filtering syntax. Example: { "basketId": 1001 }
FieldgroupBy Typestring | string[] Requiredno DescriptionA grouping field or array of fields: basketId, code
FieldgroupOrderBy Typearray Requiredno DescriptionSort groups using objects with field and direction. Use count, a field from groupBy, or <field>:<function> from a numeric aggregate expression. Directions: asc, desc. Defaults to desc. Requires groupBy
FieldgroupLimit Typenumber Requiredno DescriptionNumber of groups to return. Requires groupBy

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/basket-item-properties/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aggregate":[{"field":"*","function":"count"}],"groupBy":"code","groupOrderBy":[{"field":"count","direction":"desc"}],"groupLimit":3}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/basket-item-properties/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"aggregate":[{"field":"*","function":"count"}],"groupBy":"code","groupOrderBy":[{"field":"count","direction":"desc"}],"groupLimit":3}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-item-properties/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "aggregate": [
      {
        "field": "*",
        "function": "count"
      }
    ],
    "groupBy": "code",
    "groupOrderBy": [
      {
        "field": "count",
        "direction": "desc"
      }
    ],
    "groupLimit": 3
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-item-properties/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "aggregate": [
      {
        "field": "*",
        "function": "count"
      }
    ],
    "groupBy": "code",
    "groupOrderBy": [
      {
        "field": "count",
        "direction": "desc"
      }
    ],
    "groupLimit": 3
  }),
})

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

To group by multiple fields, pass groupBy as an array.

Other scenarios

The blocks below are request bodies.

Count properties of one basket item:

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

Sum the sort order and find the maximum property ID:

JSON 
{
  "aggregate": [
    {
      "field": "sort",
      "function": "sum"
    },
    {
      "field": "id",
      "function": "max"
    }
  ]
}

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.count Typenumber DescriptionTotal number of properties matching the filter
Fielddata.aggregates Typeobject DescriptionNumeric results by field and function. Empty for count alone
Fielddata.aggregates.<field>.truncated Typeboolean DescriptionPresent as true when numeric results were calculated from an incomplete set of records
Fielddata.groups Typearray DescriptionPresent with groupBy. Each group contains the grouping field value, count, and aggregates
Fielddata.groups[].count Typenumber DescriptionNumber of processed records in the group
Fielddata.groups[].aggregates Typeobject DescriptionNumeric results within the group
Fielddata.groups[].truncated Typeboolean DescriptionPresent as true for an incomplete set of records. The group's count and calculations cover the processed records
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of records matching the filter
Fielddata.meta.recordsProcessed Typenumber DescriptionNumber of processed records, up to 5000. 0 without grouping or numeric functions
Fielddata.meta.truncated Typeboolean Descriptiontrue when fewer records were read than the reported total, including due to the 5000-record cap, or when reading stopped on a subpage error. false for a complete response. Always false without grouping or numeric functions
Fielddata.meta.recordsShortfall Typenumber DescriptionNumber of unread records: totalRecords - recordsProcessed. Present when records are missing, including at the 5000-record cap
Fielddata.meta.pageErrorSample Typeobject DescriptionA sample subpage error. Present when reading stopped on an error
Fielddata.meta.warnings Typearray DescriptionContains a warning with code AGGREGATE_TRUNCATED for an incomplete set of records
Fielddata.meta.groupTotal Typenumber DescriptionPresent with groupBy: the number of groups before groupLimit is applied
Fielddata.meta.groupsTruncated Typeboolean DescriptionPresent with groupBy. true when groupLimit limits the returned groups

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 249,
    "aggregates": {},
    "groups": [
      {
        "code": "CATALOG.XML_ID",
        "count": 69,
        "aggregates": {}
      },
      {
        "code": "PRODUCT.XML_ID",
        "count": 69,
        "aggregates": {}
      },
      {
        "code": "Color",
        "count": 39,
        "aggregates": {}
      }
    ],
    "meta": {
      "totalRecords": 249,
      "recordsProcessed": 249,
      "truncated": false,
      "groupTotal": 7,
      "groupsTruncated": true
    }
  }
}

Without groupBy, the response omits data.groups.

Error response example

400 — the field name is not available for grouping:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'name' is not aggregatable on this entity. Available: basketId, code."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionUnknown aggregate function
HTTP400 CodeINVALID_PARAMS DescriptionThe groupBy field is neither basketId nor code
HTTP400 CodeINVALID_PARAMS DescriptionA numeric function was requested for a string field such as value
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The reason is in error.message
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 could not be reached
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 access tokens are configured
HTTP429 CodeRATE_LIMITED DescriptionThe request rate limit was exceeded. Retry after the interval in the Retry-After header

For the full list of common API errors, see Error codes.

Known specifics

Counting and calculations. A lone count without groupBy does not download records. Numeric functions and grouping require reading records.

See also