---
title: "Commercial analytics"
method: GET
path: "/analytics/commercial"
tags: ["Analytics"]
---

# Commercial analytics

`GET /analytics/commercial`

## Request

- Base URL: `https://joinways.app/api/v1`
- URL: `https://joinways.app/api/v1/analytics/commercial`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://joinways.app/oauth/authorize`, token URL `https://joinways.app/api/oauth/token`, scopes: `mcp.read`)

Sales over the period (the Reports page "Sales" tab). Signatures and signed revenue are dated by `confirmed_at`; opportunities, losses and the conversion rate by the event's creation (creation cohort). Conversion rate = confirmed / closed options (confirmed + lost + cancelled). The pipeline is the open options now, whatever the period, valued from their latest quote or expected revenue and weighted by their win probability.

**Changed in 1.3.0:** the legacy top-level fields are kept but use these definitions: `total_events_created` = opportunities created in the period, `total_confirmed` = those confirmed, `conversion_rate` = the conversion rate above (rounded, 0 when no option is closed), `total_revenue_excl_tax` = revenue signed in the period, `total_expected_revenue` = value of the open pipeline. Amounts are in the workspace `currency` (per-currency breakdowns were removed).
**Role permission:** `reports.view`.

## Query parameters

- `from` string, date
- `to` string, date
- `venues` string
- `compare` 'year' | 'previous' | 'none'

## Response `200`

Sales metrics for the period.

- CommercialAnalytics
  - `period` object: Effective period after defaults and caps.
    - `from` string, date
    - `to` string, date
    - `today` string, date: Today in the workspace time zone.
    - `timezone` string
  - `comparison` object, nullable
    - `mode` 'year' | 'previous'
    - `from` string, date
    - `to` string, date
  - `venue_ids` string[], nullable: Venue filter applied; `null` = all venues.
  - `currency` string: Workspace currency of every amount (amounts are excl. tax, 2 decimals).
  - `total_events_created` integer: Legacy — opportunities created in the period.
  - `total_confirmed` integer: Legacy — of which confirmed.
  - `conversion_rate` integer: Legacy — conversion rate in %, rounded (0 when not computable).
  - `total_revenue_excl_tax` number: Legacy — revenue signed in the period.
  - `total_expected_revenue` number: Legacy — value of the open pipeline.
  - `kpis` object
    - `signed_revenue` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `signed` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `created` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `closed` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `lost` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `cancelled` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `transformation_rate` ReportRate: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
      - `previous_pct` number, nullable
      - `change_points` number, nullable: Difference in percentage points with the comparison period.
    - `cancellation_rate` ReportRate: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
      - `previous_pct` number, nullable
      - `change_points` number, nullable: Difference in percentage points with the comparison period.
    - `average_ticket` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
    - `cycle_median_days` ReportMetric: A value for the period and for the comparison period.
      - `current` number, nullable
      - `previous` number, nullable: Comparison period value; `null` with `compare=none` or when not computable.
      - `change_pct` number, nullable: Relative change in % (1 decimal); `null` when `previous` is null or 0.
  - `funnel` object: Inquiries received in the period and what became of them.
    - `received` integer
    - `accepted` integer
    - `quoted` integer
    - `confirmed` integer
    - `win_rate` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
  - `pipeline` object: Open options now (not bound to the period).
    - `open_options` integer
    - `valued_options` integer
    - `value` number
    - `value_from_quotes` number
    - `weighted_value` number, nullable: Σ value × win probability of the options with a known amount; `null` without enough history (30 options that signed or were lost, at least 5 of each).
    - `scored_options` integer
    - `history_closed_options` integer: Options of the last 24 months the win model learns from: closed, or followed open until today (survival model).
    - `global_win_rate_pct` number, nullable
  - `monthly` object[]: One row per month of the period; `previous_*` is the aligned comparison month.
    - `month` string
    - `signed_revenue` number
    - `previous_signed_revenue` number, nullable
    - `signed` integer
    - `previous_signed` integer, nullable
    - `created` integer
    - `previous_created` integer, nullable
  - `by_venue` object[]
    - `location_id` string, uuid
    - `name` string, nullable
    - `created` integer: Opportunities created in the period.
    - `signed` integer: Signatures dated in the period.
    - `revenue` number: Signed revenue excl. tax.
    - `revenue_change_pct` number, nullable
    - `average_ticket` number, nullable
    - `transformation_rate` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `cancellation_rate` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `cycle_average_days` number, nullable
    - `coverage` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
  - `by_source` object[]
    - `source_key` string
    - `label` string
    - `created` integer: Opportunities created in the period.
    - `signed` integer: Signatures dated in the period.
    - `revenue` number: Signed revenue excl. tax.
    - `revenue_change_pct` number, nullable
    - `average_ticket` number, nullable
    - `transformation_rate` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `cancellation_rate` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `cycle_average_days` number, nullable
    - `coverage` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
  - `by_owner` object[]
    - `member_id` string, uuid
    - `name` string
    - `dominant_venue` string, nullable
    - `created` integer: Opportunities created in the period.
    - `signed` integer: Signatures dated in the period.
    - `revenue` number: Signed revenue excl. tax.
    - `revenue_change_pct` number, nullable
    - `average_ticket` number, nullable
    - `transformation_rate` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `cancellation_rate` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `cycle_average_days` number, nullable
    - `coverage` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
  - `by_type` object[]
    - `event_type` string
    - `created` integer: Opportunities created in the period.
    - `signed` integer: Signatures dated in the period.
    - `revenue` number: Signed revenue excl. tax.
    - `revenue_change_pct` number, nullable
    - `average_ticket` number, nullable
    - `transformation_rate` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `cancellation_rate` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
    - `cycle_average_days` number, nullable
    - `coverage` ReportRatio: A rate with its numerator and denominator.
      - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
      - `numerator` integer
      - `denominator` integer
  - `loss_reasons` object[]
    - `reason` string
    - `count` integer
  - `coverage` ReportCoverage: Confirmed/signed events with a known amount (`numerator`) out of all of them (`denominator`), and where the amount came from.
    - `pct` number, nullable: 0–100, 1 decimal; `null` when the denominator is 0.
    - `numerator` integer
    - `denominator` integer
    - `from_event` integer, nullable
    - `from_quote` integer, nullable
    - `from_platform` integer, nullable

## Other responses

- `400`: Validation failed (`invalid_request`). For a body that fails the schema, `details` holds `formErrors` and `fieldErrors`.
- `401`: Missing, invalid, expired or revoked bearer token (`unauthorized`).
- `403`: The token lacks the `mcp.read` scope, or its owner's role lacks the `reports.view` permission (reports carry revenue).
- `429`: Too many requests (`rate_limited`). `details.reason`: `per-ip`, `per-account-minute`, `per-account-day`, or `email_rate_limited` (email budget). Always carries `Retry-After`: wait that many seconds.

---

[API](https://skmtc.dev/joinways/apis/joinways-public-api.md) · [All operations](https://skmtc.dev/joinways/apis/joinways-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/joinways/apis/joinways-public-api/revisions/39e84309953e?raw)