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

Aggregate offers

POST /v1/catalog-offers/aggregate

Counts product offers and aggregates their numeric fields — sum, average, minimum and maximum — with filtering and grouping.

Fields available for aggregation:

  • purchasingPrice — purchase price, suitable for numeric aggregation
  • quantity — stock balance, suitable for numeric aggregation
  • iblockSectionId — catalog section, for groupBy

Request fields (body)

Parameter Type Required Description
Parameterfilter Typeobject Requiredyes DescriptionFiltering by the fields of GET /v1/catalog-offers/fields. The iblockId key is required — the offer catalog ID from GET /v1/catalogs. parentId selects the offers of one parent product; type accepts one exact value: 4 or 5. The date fields dateCreate, timestampX, dateActiveFrom, and dateActiveTo are not accepted: the Bitrix24 method does not apply date filters, and the request is rejected with 400 UNKNOWN_FILTER_FIELD.
Filtering syntax
Parameteraggregate Typearray Requiredno DescriptionAggregations: [{ "field": "purchasingPrice", "function": "sum" }]. Functions: sum, avg, min, max, count. For count, the field is "*". Without the parameter — count only
ParametergroupBy Typestring | string[] Requiredno DescriptionField or array of fields to group by (up to 5). Values — from the list above

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-offers/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "iblockId": 27, "parentId": 7189 },
    "aggregate": [
      { "field": "purchasingPrice", "function": "sum" },
      { "field": "purchasingPrice", "function": "avg" }
    ],
    "groupBy": "iblockSectionId"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/catalog-offers/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "iblockId": 27, "parentId": 7189 },
    "aggregate": [
      { "field": "purchasingPrice", "function": "sum" },
      { "field": "purchasingPrice", "function": "avg" }
    ],
    "groupBy": "iblockSectionId"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-offers/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { iblockId: 27, parentId: 7189 },
    aggregate: [
      { field: 'purchasingPrice', function: 'sum' },
      { field: 'purchasingPrice', function: 'avg' },
    ],
    groupBy: 'iblockSectionId',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/catalog-offers/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { iblockId: 27, parentId: 7189 },
    aggregate: [
      { field: 'purchasingPrice', function: 'sum' },
      { field: 'purchasingPrice', function: 'avg' },
    ],
    groupBy: 'iblockSectionId',
  }),
})

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

To group by several fields, pass an array: "groupBy": ["iblockSectionId", "quantity"], up to 5 fields.

Other scenarios

The blocks below are request bodies.

Number of offers in a catalog — a body without aggregate, the fastest request, with no records fetched. The iblockId filter is required here too:

JSON 
{ "filter": { "iblockId": 27 } }

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.count Typenumber DescriptionTotal number of offers matching the filter
Fielddata.aggregates Typeobject DescriptionAggregation results: { "purchasingPrice": { "sum": 0, "avg": 0 } }. Without numeric functions — an empty object
Fielddata.groups Typearray DescriptionGroups — present only with groupBy. Each element: grouping fields + count + aggregates
Fielddata.meta.totalRecords Typenumber DescriptionTotal number of records
Fielddata.meta.recordsProcessed Typenumber DescriptionNumber of processed records (up to 5000). For a request without numeric functions or groupBy — 0
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. Present only with groupBy
Fielddata.meta.groupsTruncated Typeboolean Descriptiontrue if the number of groups was limited. Present only with groupBy

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 2,
    "aggregates": {
      "purchasingPrice": { "sum": 940, "avg": 470 }
    },
    "groups": [
      {
        "iblockSectionId": null,
        "count": 2,
        "aggregates": { "purchasingPrice": { "sum": 940, "avg": 470 } }
      }
    ],
    "meta": {
      "totalRecords": 2,
      "recordsProcessed": 2,
      "truncated": false,
      "groupTotal": 1,
      "groupsTruncated": false
    }
  }
}

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

Error response example

400 — a field outside the list available for aggregation:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "groupBy field 'nonexistent' is not aggregatable on this entity. Available: purchasingPrice, quantity, iblockSectionId."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FILTER DescriptionThe required filter filter.iblockId was not passed — checked before the Bitrix24 call; the message contains an example body
HTTP400 CodeUNSUPPORTED_FILTER Descriptionfilter.type received a value other than 4 and 5, an array, or an operator
HTTP400 CodeINVALID_PARAMS DescriptionThe groupBy field is outside the available list — the message lists the allowed ones
HTTP400 CodeINVALID_PARAMS DescriptionA numeric function over an unknown field — Field '<name>' not found. Available numeric fields: ...
HTTP400 CodeINVALID_PARAMS DescriptionMore than 5 fields passed in groupBy
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the catalog scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
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

count is resolved in one request. Numeric functions are not. count is computed in a single call regardless of the size of the result set. The sum, avg, min, max functions and groupBy load records page by page — up to 5000 — and compute the values on the server side. If more than 5000 records match the filter, meta.truncated is true, and the aggregates and groups are built over the first 5000. 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.

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. For full details, see Aggregation POST — the 5000-record ceiling.

See also