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

Aggregate shipment items

POST /v1/shipment-items/aggregate

Counts shipment items and computes the sum, average, minimum and maximum of the product quantity, with filtering and grouping by shipment or basket item.

Standard fields

Field Purpose
quantity Product quantity in the item — the main field for sum / avg / min / max. Also available for groupBy
reservedQuantity Reserved quantity — a numeric field for sum / avg / min / max and groupBy
orderDeliveryId Shipment ID from GET /v1/shipments — used in groupBy to break items down by shipment
basketId Basket item ID from GET /v1/basket-items — used in groupBy to break items down by basket product

The fields allowed in groupBy are listed in the aggregatable array of GET /v1/shipment-items/fields. Numeric functions accept any field of type number from the same schema, including id, which is outside aggregatable.

User fields. If you pass a nonexistent field to sum / avg / min / max, the 400 INVALID_PARAMS response lists the allowed numeric fields. That list contains only the standard shipment item fields — basketId, id, orderDeliveryId, quantity, reservedQuantity. It contains no user fields.

Request fields (body)

Field Type Required Description
aggregate array no Array of expressions { "field": "quantity", "function": "sum" }, up to 5 per request. Functions: count, sum, avg, min, max. For count, the field is "*". Without the parameter, only count is returned
filter object no Filtering by the fields of GET /v1/shipment-items/fields.
Filtering syntax. Example: { "orderDeliveryId": 985 }
groupBy string | string[] no A field or array of fields to group by, up to 5 fields. Allowed values come from the aggregatable array: quantity, reservedQuantity, orderDeliveryId, basketId
groupOrderBy array no Group sorting: [{ "field": "quantity:sum", "direction": "desc" }]. The field takes count, a field name from groupBy, or <field>:<function> from aggregate. Works only together with groupBy
groupLimit number no Limit on the number of returned groups, from 1 to 1000. Works only together with groupBy

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipment-items/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "orderDeliveryId": { "$in": [975, 985] } },
    "aggregate": [
      { "field": "*", "function": "count" },
      { "field": "quantity", "function": "sum" },
      { "field": "quantity", "function": "avg" }
    ],
    "groupBy": "orderDeliveryId"
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipment-items/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "orderDeliveryId": { "$in": [975, 985] } },
    "aggregate": [
      { "field": "*", "function": "count" },
      { "field": "quantity", "function": "sum" },
      { "field": "quantity", "function": "avg" }
    ],
    "groupBy": "orderDeliveryId"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { orderDeliveryId: { $in: [975, 985] } },
    aggregate: [
      { field: '*', function: 'count' },
      { field: 'quantity', function: 'sum' },
      { field: 'quantity', function: 'avg' },
    ],
    groupBy: 'orderDeliveryId',
  }),
})

const { success, data } = await res.json()
// data.groups — product quantity per shipment
console.log(data.groups)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { orderDeliveryId: { $in: [975, 985] } },
    aggregate: [
      { field: '*', function: 'count' },
      { field: 'quantity', function: 'sum' },
      { field: 'quantity', function: 'avg' },
    ],
    groupBy: 'orderDeliveryId',
  }),
})

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

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

Other scenarios

The blocks below are request bodies.

Only the number of items in a shipment — without the aggregate array no records are loaded, and data.meta.recordsProcessed in the response is 0:

JSON 
{ "filter": { "orderDeliveryId": 985 } }

Shipments with the largest product quantity — the first two groups by descending sum of quantity:

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

Total and maximum product quantity across all items, without grouping:

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

Response fields

Field Type Description
success boolean Always true on success
data.count number Number of shipment items matching the filter
data.aggregates object Results of numeric functions by field: { "quantity": { "sum": 16, "avg": 5.33 } }. An empty object if aggregate contains only count: the count result comes in data.count and data.groups[].count, not here
data.groups array Present only with groupBy. Each element holds the grouping field values, count and aggregates for the group
data.meta.totalRecords number Total number of records matching the filter
data.meta.recordsProcessed number Number of records processed, up to 5000
data.meta.truncated boolean true if the numbers were not computed over all records matching 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 subpage error. The size of the shortfall comes in data.meta.recordsShortfall, the cut-short slice in data.meta.pageErrorSample. Always present, false on a complete response. If the request has neither groupBy nor numeric functions, no records are loaded and the flag is always false
data.meta.groupTotal number Present only with groupBy — the number of groups before groupLimit is applied
data.meta.groupsTruncated boolean Present only with groupBy. true if the group list was cut by groupLimit

Response example

JSON 
{
  "success": true,
  "data": {
    "count": 3,
    "aggregates": {
      "quantity": {
        "sum": 16,
        "avg": 5.333333333333333
      }
    },
    "groups": [
      {
        "orderDeliveryId": 975,
        "count": 1,
        "aggregates": {
          "quantity": {
            "sum": 1,
            "avg": 1
          }
        }
      },
      {
        "orderDeliveryId": 985,
        "count": 2,
        "aggregates": {
          "quantity": {
            "sum": 15,
            "avg": 7.5
          }
        }
      }
    ],
    "meta": {
      "totalRecords": 3,
      "recordsProcessed": 3,
      "truncated": false,
      "groupTotal": 2,
      "groupsTruncated": false
    }
  }
}

Without groupBy, the data.groups, data.meta.groupTotal and data.meta.groupsTruncated fields are absent from the response.

Error response example

400 — the field is not in the schema, and the message lists the allowed numeric fields:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'weight' not found. Available numeric fields: basketId, id, orderDeliveryId, quantity, reservedQuantity."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS count is passed with a field other than "*"
400 INVALID_PARAMS aggregate is passed as a non-array or an empty array
400 INVALID_PARAMS aggregate contains more than 5 expressions
400 INVALID_PARAMS Unknown function — the message lists the allowed ones
400 INVALID_PARAMS sum / avg / min / max without a field or with the field "*"
400 INVALID_PARAMS The field for sum / avg / min / max is not numeric, for example xmlId — the message names its type
400 INVALID_PARAMS The field for sum / avg / min / max is not in the schema — the message contains the list of numeric fields
400 INVALID_PARAMS The field or function fields are passed at the top level of the body instead of the aggregate array
400 INVALID_PARAMS groupBy is neither a string nor an array of strings
400 INVALID_PARAMS A field in groupBy is outside the aggregatable array, for example xmlId — the message contains the list of allowed ones
400 INVALID_PARAMS groupBy contains more than 5 fields
400 INVALID_PARAMS groupBy contains a reserved name: count, aggregates, meta, groups
400 INVALID_PARAMS groupOrderBy or groupLimit is passed without groupBy, or the value of one of them is invalid
400 UNKNOWN_FILTER_FIELD Unknown field in filter — the message contains the list of shipment item fields
400 INVALID_FILTER_FIELD A field name in filter starts with the unsupported prefix @ or !@
400 INVALID_FILTER_OPERATOR Unsupported operator in filter or a logical condition, for example $or
400 INVALID_FILTER_SHAPE filter is not passed as an object of conditions, for example as a string
400 INVALID_DUPLICATE_FILTER_FIELD Two filter conditions reduce to one Bitrix24 condition, for example $ne and $nin on the same field. Pass one of them
403 SCOPE_DENIED The API key lacks the sale scope
401 MISSING_API_KEY The X-Api-Key header is missing
401 TOKEN_MISSING The API key has no configured tokens
429 RATE_LIMITED Request limit exceeded: 300 per minute per portal, and all API keys of the portal share one limit. The exact value is in the x-ratelimit-limit header (the ceiling is divided across replicas). Retry after the period in the Retry-After header

Full list of common API errors — Errors.

Known specifics

count versus numeric functions. A request without groupBy and without numeric functions runs as a single request to Bitrix24 — no records are loaded, and the response time does not depend on the number of items. As soon as the request contains sum / avg / min / max or groupBy, including together with a single count, records are loaded page by page, at most 5000, and aggregated on the Vibecode side. With meta.truncated: true, the truncated: true marker is set both inside each field object in data.aggregates and on each element of data.groups, and data.meta.warnings carries the AGGREGATE_TRUNCATED warning. For an exact number on a large result set, use a request without groupBy and numeric functions, or narrow the filter, for example by orderDeliveryId. Full details — Aggregation POST — the 5000-record ceiling.

The count includes items of the system shipment. The selection includes the same records as the item list, including items of the system shipment, which holds the unallocated remainder of the basket. Therefore, the sum of quantity for a basket item without a shipment filter equals the product quantity in the basket. To count only what has been shipped, filter by the orderDeliveryId of shipments from GET /v1/shipments.

See also