Analytics

This guide covers reading your account's sales and performance data through the API: which reports exist, how to pull them without harming your live integration, and how to compute the numbers your account is also judged by: the same way the Platform computes them. Endpoint detail is in Analytics Endpoints. The vocabulary of orders and money comes from Orders and Core Concepts; read those first.

Goal and prerequisites

Goal: reporting you can act on and defend: revenue that matches your payment records, performance metrics computed from the same definitions the Platform uses, and pulls that never compete with your order flow for rate budget.

Prerequisites: an API key with analytics scope, orders and payments flowing (Orders, Payments), and a place on your side to store report results: analytics is read, stored, and compared over time, not re-derived from raw orders on every view.

What counts as revenue

The single most common analytics defect is counting intent as income

• An order counts toward sales when it is paid, not when it is placed. A payment-pending order is a funnel event; include it in conversion reporting and exclude it from revenue.
• Revenue reduces when money goes back: refunds and reversals (Payments) come out of the period's figures by the rules your accounting uses, applied consistently.
• Amounts arrive as decimal strings with a currency (Overview). Aggregate in decimal arithmetic, per currency, and never blend currencies into one total.

Where a finance-grade figure is needed, reconcile against the payment and payout records (Payments Endpoints) rather than re-deriving money from order lines: orders tell you what was sold; payment records tell you what was earned and settled.

Pulling reports

1. Use the analytics resources for aggregates. Analytics Endpoints provides the account's sales and performance reporting: totals, breakdowns by product and period, and the service-level measures described below. Asking the API for an aggregate is one call; downloading every order to sum it yourself is thousands.
2. Bound every pull by period. State the date range on every request. An unbounded pull is slow, expensive in rate budget (Rate Limit Headers), and almost never the question actually being asked.
3. Page correctly. Where a report returns collections, walk them with cursor pagination (Pagination & Filtering) and reconcile counts against the report's stated totals before you store the result.
4. Materialize recurring reports. Run the pull on a schedule, store the result, and serve dashboards from the stored result. Recomputing "sales by product, trailing ninety days" on every dashboard view is how reporting takes down the integration it reports on.
5. Pull off-peak and cache. Analytics traffic shares your key's rate budget with orders and inventory. Schedule heavy pulls away from your fulfillment peaks.

The metrics that matter

• Sales value (paid orders) and net sales (paid minus refunded): the top line, by period, product, and brand.
• Units and orders: volume beneath the value; a revenue rise on falling units is a price story, not a demand story.
• Return rate: refunded value and returned units over paid, by product and by reason. This is the quality signal the catalog runs on; feed it back into Catalog reviews.
• Fulfillment latency: payment to shipment, and shipment to delivery, per order. Slow tails, not averages, are where buyers are lost.

The metrics you are measured by

Your account's standing is computed from service levels stated in the Service Level Requirements: response times, fulfillment times, return handling among them. Two rules for working with them

1. Use the Platform's definitions. Read these measures from the analytics resources, which compute them as the Platform computes them. If your integration re-derives "on-time rate" by its own formula, you will eventually dispute a standing decision with a number the Platform does not recognize.
2. Watch them before they bite. The same reports that explain a standing change after the fact predict it beforehand. An integration that surfaces your service-level trend to your operations team is worth more than one that produces prettier sales charts. Standing, and what follows from it, is covered in Governance.

Events versus current state

An order's current status tells you where it is, not how long each stage took. Stage durations: time to confirm, time to ship, time in return: come from the sequence of events and state changes over the order's life, which is why orders should be captured as they happen (Webhooks) and stored on your side: history you did not record at the time cannot be reconstructed later from current state. If a metric needs event history your integration has not been keeping, build the honest version from the day recording starts rather than approximating a past that was not measured.

Failure handling

• Totals that do not match your payment records: check, in order: unpaid orders counted as revenue; refunds not deducted; mixed currencies summed together; period boundaries in the wrong timezone (all Platform timestamps are UTC, Overview).
• 429 during a reporting pull: the pull is competing with live traffic. Shrink the window, slow the walk, move the schedule.
• A report that returns nothing for a period with known sales: confirm the analytics scope is on the key (Authentication and Authorization) and that the period filter is what you intended, before concluding data is missing.
• Two reports disagreeing: they were computed at different times over live data, or with different definitions. Record the pull time and the definition with every stored report so disagreements are explainable.

What good looks like

Reports run on a schedule into your store, each stamped with its period, definition, and pull time; revenue ties to payment records to the cent; service-level measures are watched weekly by a human who can act on them; and no dashboard anywhere recomputes history per view. Ten metrics that change behavior beat a hundred that decorate.