# Reports API (/docs/reports/reports-api)

Comecero keeps a set of ready-made reports for your shop: subscriptions and MRR, sales, card approvals, your storefront's visits and searches, the usage your customers record through usage billing, and which traffic sources bring in revenue. They are the numbers behind the Dashboard and the Reports pages, and you can read every one of them through the API.

Business and usage numbers update every hour, cart counts once a day, and storefront numbers as visits happen. An answer may be up to 15 minutes old (see below). Each report covers your own shop only, in the mode of your token: a live token reads live data, a test token reads test data.

## List the reports [#list-the-reports]

```http
GET /api/v1/reports
```

See [List the analytics reports](/api/reports/list-analytics-reports). It answers each report's `name`, `description`, whether it covers a period (`period`), whether it takes a currency (`currency`) and its usual number of days (`default_days`).

## Read a report [#read-a-report]

See [Get an analytics report](/api/reports/get-analytics-report).

```bash title="Request"
curl "https://api.comecero.com/api/v1/reports/business-mrr?from=2026-01-01&to=2026-03-31&currency=USD" \
  -H "Authorization: Bearer $COMECERO_TEST_TOKEN"
```

```http
GET /api/v1/reports/business-mrr?from=2026-01-01&to=2026-03-31&currency=USD
Authorization: Bearer {token}
```

```json
{
  "object": "report",
  "name": "business-mrr",
  "account_id": "AA0001",
  "test": false,
  "date_start": "2026-01-01",
  "date_end": "2026-03-31",
  "currency": "USD",
  "columns": ["account_id", "month_end", "mrr", "arr", "subscriptions", "unconverted"],
  "data": [
    { "account_id": "AA0001", "month_end": "2026-01-31", "mrr": 50, "arr": 600, "subscriptions": 1, "unconverted": 0 }
  ],
  "truncated": false,
  "ready": true
}
```

| Parameter | What it is |
|---|---|
| `from`, `to` | The first and last day, both included, as `yyyy-MM-dd` in UTC. At most 1,096 days. Left out: the report's usual period up to today. |
| `currency` | For money reports: a 3-letter code such as `USD` or `EUR`. Default `USD`. |
| `format` | `csv` for the same rows as CSV, with a header line. A text cell that starts with `=`, `+`, `-` or `@` gets a `'` in front, so a spreadsheet never runs it as a formula. |

- `data` holds at most 100,000 rows; `truncated` is `true` when there were more. Ask for a shorter period.
- `ready` is `false` for a new shop whose reports are still being prepared (within an hour of its first data).
- Money is in the currency you ask for. Payments and refunds in other currencies are converted at the rate of their own day; MRR, subscription months and promotions at the rate of the period's last day. Anything with no rate is left out and counted in `unconverted` (a count of items, not an amount).
- Storefront reports take no currency: `revenue` and `revenue_alt` are in the shop's two reporting currencies.

## Who may read them [#who-may-read-them]

Any token of your shop with the reports read permission: a secret API key, or a signed-in dashboard user. Never a shopper's limited token. A token can only ever read its own shop's reports, whatever the request says.

Each token may ask for about 120 reports a minute, 40 at once (each API server counts on its own, so the limit is approximate). Over that, the API answers `429 Too Many Requests` with `Retry-After`. The same report for the same period within 15 minutes is answered from memory, but still counts toward the limit.

## The reports [#the-reports]

What each number means, in plain words: [Reports and analytics](/docs/reports#what-the-numbers-mean).

## Business [#business]

### business-card-approval [#business-card-approval]

Card payment attempts approved and declined, and the approval rate, per day.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `account_id` | LowCardinality(String) |
| `day` | Date |
| `approved` | UInt64 |
| `declined` | UInt64 |
| `approval_rate` | Nullable(Float64) |

### business-card-approval-by-brand [#business-card-approval-by-brand]

Card approval rate by card brand.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `account_id` | LowCardinality(String) |
| `brand` | String |
| `approved` | UInt64 |
| `declined` | UInt64 |
| `approval_rate` | Nullable(Float64) |

### business-card-declines [#business-card-declines]

The most common decline reasons.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `account_id` | LowCardinality(String) |
| `code` | String |
| `declined` | UInt64 |

### business-cart-conversion [#business-cart-conversion]

Carts created, carts completed and the conversion rate, per day.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `account_id` | LowCardinality(String) |
| `day` | Date |
| `carts_created` | UInt64 |
| `carts_completed` | UInt64 |
| `conversion_rate` | Nullable(Float64) |

### business-customer-value [#business-customer-value]

Net sales, paying customers and revenue per paying customer.

- Period: `from` and `to`, default the last 30 days
- Money: takes `currency` (default `USD`)

| Column | Type |
|---|---|
| `account_id` | LowCardinality(String) |
| `gross` | Float64 |
| `refunds` | Float64 |
| `net` | Float64 |
| `paying_customers` | UInt64 |
| `revenue_per_customer` | Nullable(Float64) |
| `payments` | UInt64 |
| `unconverted` | UInt64 |

### business-freshness [#business-freshness]

When the numbers were last brought up to date.

- No period: it describes the data as it is now

| Column | Type |
|---|---|
| `exported_at` | DateTime64(3, 'UTC') |
| `loaded_at` | DateTime64(3, 'UTC') |

### business-mrr [#business-mrr]

Monthly recurring revenue (and ARR) at the end of each month, with paying subscriptions.

- Period: `from` and `to`, default the last 365 days
- Money: takes `currency` (default `USD`)

| Column | Type |
|---|---|
| `account_id` | LowCardinality(String) |
| `month_end` | Date |
| `mrr` | Float64 |
| `arr` | Float64 |
| `subscriptions` | UInt64 |
| `unconverted` | UInt64 |

### business-promotions [#business-promotions]

Paid orders, sales, discount and average order by promotion code ('' = no code).

- Period: `from` and `to`, default the last 30 days
- Money: takes `currency` (default `USD`)

| Column | Type |
|---|---|
| `account_id` | LowCardinality(String) |
| `promotion_code` | String |
| `orders` | UInt64 |
| `sales` | Float64 |
| `discount` | Float64 |
| `average_order` | Nullable(Float64) |
| `unconverted` | UInt64 |

### business-sales-by-country [#business-sales-by-country]

Completed payments, refunds and net sales by billing country.

- Period: `from` and `to`, default the last 30 days
- Money: takes `currency` (default `USD`)

| Column | Type |
|---|---|
| `account_id` | LowCardinality(String) |
| `country` | LowCardinality(String) |
| `payments` | UInt64 |
| `gross` | Float64 |
| `refunds` | Float64 |
| `net` | Float64 |
| `unconverted` | UInt64 |

### business-subscription-months [#business-subscription-months]

Per month: MRR and subscriptions at the start, new, expansion (items added), contraction (items cancelled), churned, churn rate and revenue churn rate.

- Period: `from` and `to`, default the last 365 days
- Money: takes `currency` (default `USD`)

| Column | Type |
|---|---|
| `account_id` | LowCardinality(String) |
| `month` | Date |
| `start_mrr` | Float64 |
| `new_mrr` | Float64 |
| `churned_mrr` | Float64 |
| `expansion_mrr` | Float64 |
| `contraction_mrr` | Float64 |
| `churned_mrr_from_start` | Float64 |
| `start_subscriptions` | UInt64 |
| `new_subscriptions` | UInt64 |
| `churned_subscriptions` | UInt64 |
| `churned_from_start` | UInt64 |
| `churn_rate` | Nullable(Float64) |
| `revenue_churn_rate` | Nullable(Float64) |
| `unconverted` | UInt64 |

## Revenue by traffic source [#revenue-by-traffic-source]

### revenue-by-source [#revenue-by-source]

Storefront purchases' payments, refunds, net, orders and new subscriptions by traffic source, with each source's share of all revenue.

- Period: `from` and `to`, default the last 30 days
- Money: takes `currency` (default `USD`)

| Column | Type |
|---|---|
| `source` | String |
| `payments` | UInt64 |
| `gross` | Float64 |
| `refunds` | Float64 |
| `net` | Float64 |
| `orders` | UInt64 |
| `new_subscriptions` | UInt64 |
| `share_of_revenue` | Nullable(Float64) |
| `unconverted` | UInt64 |

### revenue-coverage [#revenue-coverage]

Per day: all revenue, the part with a storefront visit behind it, and its share.

- Period: `from` and `to`, default the last 30 days
- Money: takes `currency` (default `USD`)

| Column | Type |
|---|---|
| `day` | Date |
| `revenue` | Float64 |
| `covered_revenue` | Float64 |
| `covered_share` | Nullable(Float64) |

## Storefront and business side by side [#storefront-and-business-side-by-side]

### business-side-by-side [#business-side-by-side]

Per day, side by side: storefront visitors and visits, carts created, paid orders and new subscriptions.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `day` | Date |
| `visitors` | UInt64 |
| `visits` | UInt64 |
| `carts` | UInt64 |
| `paid_orders` | UInt64 |
| `new_subscriptions` | UInt64 |

## Storefront [#storefront]

### storefront-daily [#storefront-daily]

Visits, purchases and confirmed revenue per day.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `day` | Date |
| `visits` | UInt64 |
| `purchases` | UInt64 |
| `revenue` | Float64 |
| `revenue_alt` | Float64 |

### storefront-field-errors [#storefront-field-errors]

Checkout fields shoppers got wrong, and by which rule.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `field` | String |
| `rule` | String |
| `times` | UInt64 |
| `visits` | UInt64 |

### storefront-overview [#storefront-overview]

Visitors, visits, page views, buying visits, purchases, confirmed orders and their revenue.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `visitors` | UInt64 |
| `visits` | UInt64 |
| `page_views` | UInt64 |
| `buying_visits` | UInt64 |
| `purchases` | UInt64 |
| `orders` | UInt64 |
| `revenue` | Float64 |
| `revenue_alt` | Float64 |

### storefront-page-health [#storefront-page-health]

Page speed (the slowest quarter of loads) and errors, by page kind.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `page_type` | LowCardinality(String) |
| `lcp_p75_ms` | Float64 |
| `inp_p75_ms` | Float64 |
| `cls_p75` | Float64 |
| `errors` | UInt64 |

### storefront-payment-failures [#storefront-payment-failures]

Failed payment attempts by method and the gateway's codes.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `method` | String |
| `code` | String |
| `response_code` | String |
| `failures` | UInt64 |

### storefront-payment-methods [#storefront-payment-methods]

Payments that went through and attempts that failed, by method.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `method` | String |
| `paid` | UInt64 |
| `failed` | UInt64 |

### storefront-products [#storefront-products]

Per product: visits that viewed, added and bought it.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `product_id` | String |
| `viewing_visits` | UInt64 |
| `adding_visits` | UInt64 |
| `buying_visits` | UInt64 |
| `viewed_and_bought` | UInt64 |

### storefront-promo-rejected [#storefront-promo-rejected]

Promotion codes shoppers tried that were refused, and why.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `code` | String |
| `reason` | String |
| `times` | UInt64 |

### storefront-searches [#storefront-searches]

What shoppers searched for, and searches that found nothing.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `term` | String |
| `searches` | UInt64 |
| `no_results` | UInt64 |

### storefront-upsells [#storefront-upsells]

Upsells shown and accepted.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `shown` | UInt64 |
| `accepted` | UInt64 |

### storefront-visit-groups [#storefront-visit-groups]

The top 15 traffic sources, campaigns, countries, devices, browsers, systems, languages and pop checkout pages, with buying visits and revenue.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `kind` | String |
| `value` | String |
| `visits` | UInt64 |
| `buying_visits` | UInt64 |
| `orders` | UInt64 |
| `revenue` | Float64 |
| `revenue_alt` | Float64 |

### storefront-visit-steps [#storefront-visit-steps]

How far visits got in each checkout (shop, pop, payment page, invoice), and unfinished checkouts by trouble.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `funnel_shop` | Array(UInt64) |
| `funnel_pop` | Array(UInt64) |
| `funnel_pay` | Array(UInt64) |
| `funnel_invoice` | Array(UInt64) |
| `checkouts` | UInt64 |
| `abandoned` | UInt64 |
| `field_error_abandoned` | UInt64 |
| `price_changed_abandoned` | UInt64 |
| `payment_failed_abandoned` | UInt64 |
| `promo_rejected_abandoned` | UInt64 |

## Usage [#usage]

### usage-customers [#usage-customers]

The 50 customers with the most of each metric in the period.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `metric` | LowCardinality(String) |
| `aggregation` | LowCardinality(String) |
| `customer_id` | String |
| `value` | SimpleAggregateFunction(max, Decimal(38, 6)) |
| `events` | UInt64 |
| `last_hour` | DateTime('UTC') |

### usage-daily [#usage-daily]

Per metric and day: the value (total, or a gauge's busiest hour) and events.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `metric` | LowCardinality(String) |
| `aggregation` | LowCardinality(String) |
| `day` | Date |
| `value` | Decimal(38, 6) |
| `events` | UInt64 |

### usage-freshness [#usage-freshness]

When usage was last brought up to date.

- No period: it describes the data as it is now

| Column | Type |
|---|---|
| `loaded_at` | Nullable(DateTime('UTC')) |

### usage-hourly [#usage-hourly]

Usage events per hour, every metric together.

- Period: `from` and `to`, default the last 30 days

| Column | Type |
|---|---|
| `hour` | DateTime('UTC') |
| `events` | UInt64 |