comecerodocs
Reports and analytics

Reports API

Read every analytics report for your shop with GET /api/v1/reports/{name}, including MRR, churn, card approval, storefront visits and usage.

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

GET /api/v1/reports

See List the 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

See Get an analytics report.

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"
GET /api/v1/reports/business-mrr?from=2026-01-01&to=2026-03-31&currency=USD
Authorization: Bearer {token}
{
  "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
}
ParameterWhat it is
from, toThe 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.
currencyFor money reports: a 3-letter code such as USD or EUR. Default USD.
formatcsv 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

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

What each number means, in plain words: Reports and analytics.

Business

business-card-approval

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

  • Period: from and to, default the last 30 days
ColumnType
account_idLowCardinality(String)
dayDate
approvedUInt64
declinedUInt64
approval_rateNullable(Float64)

business-card-approval-by-brand

Card approval rate by card brand.

  • Period: from and to, default the last 30 days
ColumnType
account_idLowCardinality(String)
brandString
approvedUInt64
declinedUInt64
approval_rateNullable(Float64)

business-card-declines

The most common decline reasons.

  • Period: from and to, default the last 30 days
ColumnType
account_idLowCardinality(String)
codeString
declinedUInt64

business-cart-conversion

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

  • Period: from and to, default the last 30 days
ColumnType
account_idLowCardinality(String)
dayDate
carts_createdUInt64
carts_completedUInt64
conversion_rateNullable(Float64)

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)
ColumnType
account_idLowCardinality(String)
grossFloat64
refundsFloat64
netFloat64
paying_customersUInt64
revenue_per_customerNullable(Float64)
paymentsUInt64
unconvertedUInt64

business-freshness

When the numbers were last brought up to date.

  • No period: it describes the data as it is now
ColumnType
exported_atDateTime64(3, 'UTC')
loaded_atDateTime64(3, 'UTC')

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)
ColumnType
account_idLowCardinality(String)
month_endDate
mrrFloat64
arrFloat64
subscriptionsUInt64
unconvertedUInt64

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)
ColumnType
account_idLowCardinality(String)
promotion_codeString
ordersUInt64
salesFloat64
discountFloat64
average_orderNullable(Float64)
unconvertedUInt64

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)
ColumnType
account_idLowCardinality(String)
countryLowCardinality(String)
paymentsUInt64
grossFloat64
refundsFloat64
netFloat64
unconvertedUInt64

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)
ColumnType
account_idLowCardinality(String)
monthDate
start_mrrFloat64
new_mrrFloat64
churned_mrrFloat64
expansion_mrrFloat64
contraction_mrrFloat64
churned_mrr_from_startFloat64
start_subscriptionsUInt64
new_subscriptionsUInt64
churned_subscriptionsUInt64
churned_from_startUInt64
churn_rateNullable(Float64)
revenue_churn_rateNullable(Float64)
unconvertedUInt64

Revenue by traffic 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)
ColumnType
sourceString
paymentsUInt64
grossFloat64
refundsFloat64
netFloat64
ordersUInt64
new_subscriptionsUInt64
share_of_revenueNullable(Float64)
unconvertedUInt64

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)
ColumnType
dayDate
revenueFloat64
covered_revenueFloat64
covered_shareNullable(Float64)

Storefront and 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
ColumnType
dayDate
visitorsUInt64
visitsUInt64
cartsUInt64
paid_ordersUInt64
new_subscriptionsUInt64

Storefront

storefront-daily

Visits, purchases and confirmed revenue per day.

  • Period: from and to, default the last 30 days
ColumnType
dayDate
visitsUInt64
purchasesUInt64
revenueFloat64
revenue_altFloat64

storefront-field-errors

Checkout fields shoppers got wrong, and by which rule.

  • Period: from and to, default the last 30 days
ColumnType
fieldString
ruleString
timesUInt64
visitsUInt64

storefront-overview

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

  • Period: from and to, default the last 30 days
ColumnType
visitorsUInt64
visitsUInt64
page_viewsUInt64
buying_visitsUInt64
purchasesUInt64
ordersUInt64
revenueFloat64
revenue_altFloat64

storefront-page-health

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

  • Period: from and to, default the last 30 days
ColumnType
page_typeLowCardinality(String)
lcp_p75_msFloat64
inp_p75_msFloat64
cls_p75Float64
errorsUInt64

storefront-payment-failures

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

  • Period: from and to, default the last 30 days
ColumnType
methodString
codeString
response_codeString
failuresUInt64

storefront-payment-methods

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

  • Period: from and to, default the last 30 days
ColumnType
methodString
paidUInt64
failedUInt64

storefront-products

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

  • Period: from and to, default the last 30 days
ColumnType
product_idString
viewing_visitsUInt64
adding_visitsUInt64
buying_visitsUInt64
viewed_and_boughtUInt64

storefront-promo-rejected

Promotion codes shoppers tried that were refused, and why.

  • Period: from and to, default the last 30 days
ColumnType
codeString
reasonString
timesUInt64

storefront-searches

What shoppers searched for, and searches that found nothing.

  • Period: from and to, default the last 30 days
ColumnType
termString
searchesUInt64
no_resultsUInt64

storefront-upsells

Upsells shown and accepted.

  • Period: from and to, default the last 30 days
ColumnType
shownUInt64
acceptedUInt64

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
ColumnType
kindString
valueString
visitsUInt64
buying_visitsUInt64
ordersUInt64
revenueFloat64
revenue_altFloat64

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
ColumnType
funnel_shopArray(UInt64)
funnel_popArray(UInt64)
funnel_payArray(UInt64)
funnel_invoiceArray(UInt64)
checkoutsUInt64
abandonedUInt64
field_error_abandonedUInt64
price_changed_abandonedUInt64
payment_failed_abandonedUInt64
promo_rejected_abandonedUInt64

Usage

usage-customers

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

  • Period: from and to, default the last 30 days
ColumnType
metricLowCardinality(String)
aggregationLowCardinality(String)
customer_idString
valueSimpleAggregateFunction(max, Decimal(38, 6))
eventsUInt64
last_hourDateTime('UTC')

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
ColumnType
metricLowCardinality(String)
aggregationLowCardinality(String)
dayDate
valueDecimal(38, 6)
eventsUInt64

usage-freshness

When usage was last brought up to date.

  • No period: it describes the data as it is now
ColumnType
loaded_atNullable(DateTime('UTC'))

usage-hourly

Usage events per hour, every metric together.

  • Period: from and to, default the last 30 days
ColumnType
hourDateTime('UTC')
eventsUInt64

Reports and analytics

MRR, churn, sales, card approval, storefront visits and usage for your shop, in the dashboard, the API and Claude, with what each number means.

Connect Claude

Connect your own Claude to your shop's reports through the Comecero MCP connection, and ask about sales, MRR, churn, storefront and usage in plain words.

On this page

List the reportsRead a reportWho may read themThe reportsBusinessbusiness-card-approvalbusiness-card-approval-by-brandbusiness-card-declinesbusiness-cart-conversionbusiness-customer-valuebusiness-freshnessbusiness-mrrbusiness-promotionsbusiness-sales-by-countrybusiness-subscription-monthsRevenue by traffic sourcerevenue-by-sourcerevenue-coverageStorefront and business side by sidebusiness-side-by-sideStorefrontstorefront-dailystorefront-field-errorsstorefront-overviewstorefront-page-healthstorefront-payment-failuresstorefront-payment-methodsstorefront-productsstorefront-promo-rejectedstorefront-searchesstorefront-upsellsstorefront-visit-groupsstorefront-visit-stepsUsageusage-customersusage-dailyusage-freshnessusage-hourly