---
title: "Aggregate Orders"
method: POST
path: "/crm/orders/aggregate"
tags: ["CRM Service Calls", "CRM Aggregate"]
---

# Aggregate Orders

`POST /crm/orders/aggregate`

Aggregate orders by group-by fields — ideal for dashboards, charts, and analytics.

Use this endpoint to build order distribution charts, fulfillment status views,
or revenue breakdowns by order type.

**Request Body (AggregateRequest):** Same as leads/aggregate.

**Examples:**
- Orders by stage: `{"group_by_fields": ["stage"]}`
- Orders by type with amount: `{"group_by_fields": ["order_type"], "aggregate_field": "total_amount"}`

## Request body

- AggregateRequest — Request body for aggregate/group-by queries.
  - `group_by_fields` string[], required — Fields to group by, e.g. ["lead_status"], ["stage", "marketing_source"]
  - `aggregate_field` string, nullable — Numeric field to aggregate, e.g. "value_of_sale", "estimated_budget"
  - `match_filter_dict` string, nullable — JSON-stringified MongoDB filter to narrow the dataset before aggregation
  - `sort_dict` string, nullable — JSON-stringified sort criteria, e.g. {"count": -1}
  - `page_size` integer — Maximum number of groups to return
  - `page_num` integer — Page number (1-indexed)

## Response `200`

Successful Response

- AggregateResponse — Response for aggregate queries.
  - `groups` AggregateGroup[] — List of aggregate groups
    - `group_by` string — Human-readable label e.g. "Status: contacted"
    - `group_by_values` object, nullable — Programmatic values e.g. {"lead_status": "contacted"}
    - `count` integer — Number of records in this group
    - `total_value` number, nullable — Sum of aggregate_field
    - `avg_value` number, nullable — Average of aggregate_field
    - `max_value` number, nullable — Max of aggregate_field
    - `min_value` number, nullable — Min of aggregate_field
    - `entity_ids_list` unknown[], nullable — List of entity IDs in this group
      - unknown
  - `total_groups` integer — Total number of groups returned
  - `aggregate_field` string, nullable — The numeric field that was aggregated
  - `group_by_fields` string[] — Fields that were grouped by

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/ambivo/apis/ambivo-api.md) · [All operations](https://skmtc.net/ambivo/apis/ambivo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ambivo/ambivo-api/versions/165a6d16a9a0/schema)