Przewodnik

Analytics and tracking

Sales analytics (revenue, profit, average order value, best sellers, discounts, returns, cancellations, abandoned carts) work automatically from your orders. Traffic sources and conversion funnels need your storefront to send events.

Sending events

Use a publishable key with the analytics:write scope. Send single events or batches of up to 50.

await fetch("https://your-openshopy-domain/api/public/v1/events", {
  method: "POST",
  headers: {
    Authorization: "Bearer os_pk_your_publishable_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    event_type: "product_view",
    session_id: sessionId,          // your own random id per visitor session
    path: location.pathname,
    referrer: document.referrer || null,
    source: utm.source ?? null,      // utm_source; derived from referrer when empty
    medium: utm.medium ?? null,
    campaign: utm.campaign ?? null,
    props: { product_id: "…" },
  }),
});

Event types

`event_type`	When to send
`page_view`	Every page view
`product_view`	Product page view
`add_to_cart` / `remove_from_cart`	Cart changes
`checkout_started`	Customer opens checkout
`purchase`	Order completed (include `order_id`, `value` in minor units and `currency`)
`search`	Search query (put the query in `props.q`)
`custom`	Anything else

The conversion funnel in Analytics counts distinct sessions: all sessions → product_view → add_to_cart → checkout_started → orders placed.

UTM attribution

Pass UTM parameters to carts too (utm object on POST /carts). Orders created from those carts keep the attribution, so revenue by source is accurate even without events.

Reading analytics through the API

text

GET /analytics/summary?from=2026-01-01&to=2026-01-31

Returns quick totals plus a full report: revenue, net sales, cost of goods, tax, shipping, discounts, refunds, average order value, cancellations, new and returning customers, a daily series with profit, best sellers, discount performance, returns, status breakdowns, countries, abandoned carts, traffic sources and the funnel. All report amounts are in the store base currency. Requires a secret key with analytics:read. See Carts & checkout → Analytics for the exact shape.

GET /abandoned-carts lists carts with an email that were not checked out within Settings → Abandoned cart after (minutes).

Profit

Profit uses each order item's unit_cost snapshot (copied from the variant cost at order time): profit = item revenue without tax − cost of goods. Set variant costs to get meaningful margins.