Your agent can read the same numbers the store owner sees under Analytics: sales, profit after every cost, payments, ads, traffic, checkout and upsells, subscriptions, email and SMS, delivery, support and chargebacks. They are computed by the same code as the owner’s screens, so what your agent tells the owner always matches what they see. The shipments report lists customers’ parcels, so it also needs orders:read.

​
How to use it

  1. Start with the snapshot. One call returns sales, profit, payments, ads, traffic, subscriptions, delivery, support, chargebacks and the cost of a new customer for the range you ask for. Series are left out and lists keep their first 10 rows. A report that could not be built in time is listed under unavailable; ask for it on its own a minute later.
  2. Find the report you need in the catalog. Each report has a name, the area it belongs to, what it shows, the extra arguments it takes and which dates it reads.
  3. Drill in with dtc_metrics_query. You get the full daily (or hourly) series and every row of every table: per campaign, ad account, product, carrier, country, gateway, upsell step, ticket reason or subscription cohort.

​
Dates

Days follow the store’s time zone unless you pass timezone. Money is in US dollars unless you pass currency. An argument a report does not take is refused with a message that says so — it is never silently ignored.

​
What you get back

Most reports use one shape:
  • currency, range (start, end, compareStart, compareEnd: the previous period of the same length).
  • sections, each with metrics or table rows.
  • Each metric: key, label, unit (currency, percent 0–100, multiple, number, duration in seconds, days), value, previous, deltaPct, chart (the series) and improveWhen: "down" when a fall is good news (refunds, bounce rate, reply time).
A null value means there is no data for it — say so; never treat it as zero.

​
Example

Your agent signs in the way Connect your own agent describes. Reports are read as the person who connected the agent, with the same access they have on the dashboard.