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

Aggregate order properties

POST /v1/order-properties/aggregate

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

Standard fields

Field Purpose
FieldpersonTypeId PurposePayer type ID from GET /v1/person-types. For groupBy
Fieldtype PurposeProperty type — for groupBy
Fieldrequired PurposeWhether the field is required when placing an order — for groupBy
Fieldactive PurposeActive flag — for groupBy
Fieldsort PurposeSort order — for sum, avg, min, max
FieldinputFieldLocation PurposeDeprecated field. Bitrix24 does not use it — a numeric field
Fieldid PurposeProperty ID from list order properties. A numeric field
FieldpropsGroupId PurposeGroup ID from a property with the same payer type in list order properties. A numeric field

Fields for groupBy are listed in data.aggregatable of GET /v1/order-properties/fields. Numeric functions accept fields of type number from the same schema: id, personTypeId, propsGroupId, sort, inputFieldLocation.

Request body fields

Field Type Required Description
Fieldaggregate Typearray Requiredno DescriptionAn array of expressions such as { "field": "sort", "function": "sum" }, with 1 to 5 expressions. 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/order-properties/fields.
Filtering syntax. Example: { "id": 125 }
FieldgroupBy Typestring | string[] Requiredno DescriptionA grouping field or an array of up to 5 fields. Allowed fields: personTypeId, type, required, active
FieldgroupOrderBy Typearray Requiredno DescriptionSort groups: [{ "field": "count", "direction": "desc" }]. field accepts count, a field from groupBy, or <field>:<function> from aggregate. Directions: asc, desc. If direction is omitted, defaults to desc. Requires groupBy
FieldgroupLimit Typenumber Requiredno DescriptionNumber of returned groups: an integer from 1 to 1000. When omitted, groups are not limited. Requires groupBy

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/order-properties/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "id": 125 },
    "aggregate": [
      { "field": "*", "function": "count" },
      { "field": "sort", "function": "sum" }
    ],
    "groupBy": ["type", "active"],
    "groupOrderBy": [{ "field": "count", "direction": "desc" }],
    "groupLimit": 10
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/order-properties/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "id": 125 },
    "aggregate": [
      { "field": "*", "function": "count" },
      { "field": "sort", "function": "sum" }
    ],
    "groupBy": ["type", "active"],
    "groupOrderBy": [{ "field": "count", "direction": "desc" }],
    "groupLimit": 10
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-properties/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: 125 },
    aggregate: [
      { field: '*', function: 'count' },
      { field: 'sort', function: 'sum' },
    ],
    groupBy: ['type', 'active'],
    groupOrderBy: [{ field: 'count', direction: 'desc' }],
    groupLimit: 10,
  }),
})

const { data } = await res.json()
console.log('Properties by type and active status:', data.groups)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-properties/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { id: 125 },
    aggregate: [
      { field: '*', function: 'count' },
      { field: 'sort', function: 'sum' },
    ],
    groupBy: ['type', 'active'],
    groupOrderBy: [{ field: 'count', direction: 'desc' }],
    groupLimit: 10,
  }),
})

const { data } = await res.json()

Other scenarios

The blocks below are request bodies.

Count properties matching the filter without grouping or numeric functions — records are not downloaded:

JSON 
{ "filter": { "id": 125 } }

Sum the sort order with grouping when the filter matches no records:

JSON 
{
  "filter": { "id": 125, "code": "ABSENT_DELIVERY_COMMENT" },
  "aggregate": [{ "field": "sort", "function": "sum" }],
  "groupBy": ["type", "active"]
}

For the last request, data.count and the sum are 0, and data.groups is an empty array.

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, such as { "sort": { "sum": 500 } }. 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 grouping field values, count, and aggregates. personTypeId is a number, type is a string, and required and active are boolean
Fielddata.groups[].count Typenumber DescriptionNumber of processed records in the group
Fielddata.groups[].aggregates Typeobject DescriptionNumeric results within the group, in the same format as data.aggregates
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": 1,
    "aggregates": {
      "sort": {
        "sum": 500
      }
    },
    "groups": [
      {
        "type": "STRING",
        "active": false,
        "count": 1,
        "aggregates": {
          "sort": {
            "sum": 500
          }
        }
      }
    ],
    "meta": {
      "totalRecords": 1,
      "recordsProcessed": 1,
      "truncated": false,
      "groupTotal": 1,
      "groupsTruncated": false
    }
  }
}

Error response example

400 — the string field name was passed to the numeric function sum:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'name' is not numeric (type: string). Only number fields support sum."
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS Descriptionaggregate is not an array or is empty
HTTP400 CodeINVALID_PARAMS Descriptionaggregate contains more than 5 expressions
HTTP400 CodeINVALID_PARAMS DescriptionThe function is unknown or missing
HTTP400 CodeINVALID_PARAMS DescriptionThe field for count is not "*"
HTTP400 CodeINVALID_PARAMS DescriptionThe field for sum, avg, min, or max is missing or is "*"
HTTP400 CodeINVALID_PARAMS DescriptionA nonnumeric field such as name or defaultValue was passed to a numeric function
HTTP400 CodeINVALID_PARAMS DescriptionThe numeric function field was not found. The message lists allowed fields: id, personTypeId, propsGroupId, sort, inputFieldLocation
HTTP400 CodeINVALID_PARAMS Descriptionop, field, or function was passed at the top level without the aggregate array
HTTP400 CodeINVALID_PARAMS DescriptiongroupBy is not a string or an array of strings, or the array contains a value of another type
HTTP400 CodeINVALID_PARAMS DescriptionThe grouping field is not one of personTypeId, type, required, active
HTTP400 CodeINVALID_PARAMS DescriptiongroupBy has more than 5 fields
HTTP400 CodeINVALID_PARAMS DescriptiongroupBy contains a reserved name: count, aggregates, meta, groups
HTTP400 CodeINVALID_PARAMS DescriptiongroupOrderBy was passed without groupBy
HTTP400 CodeINVALID_PARAMS DescriptiongroupLimit was passed without groupBy
HTTP400 CodeINVALID_PARAMS DescriptiongroupOrderBy is not an array
HTTP400 CodeINVALID_PARAMS DescriptionA groupOrderBy item is not an object with a nonempty string field
HTTP400 CodeINVALID_PARAMS DescriptiongroupOrderBy.direction is neither asc nor desc
HTTP400 CodeINVALID_PARAMS DescriptionThe <field>:<function> key in groupOrderBy.field is absent from the numeric aggregate expressions
HTTP400 CodeINVALID_PARAMS DescriptiongroupOrderBy.field is not count, a field from groupBy, or a numeric aggregate expression key
HTTP400 CodeINVALID_PARAMS DescriptiongroupLimit is not an integer from 1 to 1000
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionUnknown field in filter
HTTP400 CodeINVALID_FILTER_FIELD DescriptionA field name in filter starts with the unsupported prefix @ or !@
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionUnsupported operator, an empty condition object, or $or / $and logical conditions
HTTP400 CodeINVALID_FILTER_SHAPE Descriptionfilter is not an object of conditions, for example a string, number, or array
HTTP400 CodeINVALID_DUPLICATE_FILTER_FIELD DescriptionTwo filter conditions resolve to the same condition, for example $ne and $nin for one field
HTTP422 CodeAGGREGATION_LIMIT_EXCEEDED DescriptionWhen the cap is enforced for the portal, more than 5000 records match the filter and the request requires numeric calculations or grouping. Records are not downloaded. Narrow the filter
HTTP422 CodeBITRIX_ERROR DescriptionThe key's user does not have permission in Bitrix24. The Bitrix24 code is in error.b24Code: 200040300010
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe portal credentials do not have the sale scope (insufficient_scope)
HTTP422 CodeBITRIX_ERROR DescriptionA business error with the Bitrix24 message
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time. Retry after the interval in Retry-After
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 tokens are configured for the API key
HTTP429 CodeRATE_LIMITED DescriptionThe request rate limit was exceeded. The effective limit is in the x-ratelimit-limit header. Retry after the interval in the Retry-After header

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

See also