Deals

Deals are sales opportunities linked to contacts and tracked through pipeline stages. The financial fields are aggregatable, which makes deals the natural entity for revenue reporting.

Fields

Legend: F filterable, S sortable, A aggregatable, G groupable.

Notes

• stage vs last_stage map to the same underlying value but are scoped by deal status. Pending deals expose stage; closed deals (won, lost, and every deal in a delivery pipeline) expose last_stage. The non-applicable one is null in projections, and filtering by stage implicitly restricts the result set to pending deals.
• Stage values are integers but not sequential. A typical pipeline uses values like 10, 20, 40. Stage numbers and their labels are account-configurable.
• Sales vs delivery pipelines. A pipeline is either a sales pipeline (deals run pending → won/lost) or a delivery pipeline (post-sales project tracking, where every deal is won and the stages track delivery progress). Deals in a delivery pipeline are always won, so their position lives in last_stage, not stage. Use context() to see each pipeline’s type.
• Financial fields (amount, total_amount, cost, total_cost, margin, commission, commission_percentage) are all aggregatable and valid as the argument to sum, avg, min, max, median, and percentile.
• close_date is writable via the MCP create/update tools, but only on won or lost deals (or together with status: "won"/"lost" in the same call). Pending deals have no close date; setting it on one is rejected with a hint to use expected_close_date instead.
• Lookups: contact (via contact_id). Pull the contact’s fields inline as contact.<field> — for example contact.last_name, contact.company_name, or contact.country_code — in select, where, and order_by. See Concepts › Lookups.
• Custom fields are queryable by name as custom_fields.<name> in select, where, and order_by; select custom_fields.* (or *) to return all of them. Filterability and sortability depend on the field’s type. Numeric custom fields can also be aggregated ({ "sum": ["custom_fields.<name>"] }), and min/max work on date custom fields. group_by and distinct on custom fields are not supported: group by a top-level field and filter on the custom field in where instead. Use describe to discover an account’s custom-field names and types.

Example queries

Top 25 open deals by amount, each with its contact’s company (a lookup):

{
  "from": "deals",
  "select": ["name", "amount", "contact.company_name"],
  "where": { "status": "pending" },
  "order_by": [{ "amount": "desc" }],
  "limit": 25
}

Deals I own that closed last quarter:

{
  "from": "deals",
  "where": {
    "owner_id": "ME()",
    "status": "won",
    "close_date": "LAST_QUARTER()"
  }
}

Won revenue this quarter, by owner:

{
  "from": "deals",
  "select": ["owner_id", "count()", { "sum": ["amount"] }],
  "where": { "status": "won", "close_date": "THIS_QUARTER()" },
  "group_by": ["owner_id"]
}

Monthly closed-won trend over the last year:

{
  "from": "deals",
  "select": ["close_date", "count()", { "sum": ["amount"] }],
  "where": {
    "status": "won",
    "close_date": { ">=": { "DAYS_AGO": [365] } }
  },
  "group_by": [{ "MONTH": ["close_date"] }]
}

Stuck deals (in pipeline more than 90 days):

{
  "from": "deals",
  "where": {
    "status": "pending",
    "created_at": { "<": { "DAYS_AGO": [90] } }
  },
  "order_by": [{ "amount": "desc" }]
}