Analytics

get_analytics_summary

read

Get analytics summary

Copy page

Answer "how is the store doing" without reading orders one by one.

Overview

Returns aggregate trading totals for the connected Store over a reporting period of 7, 30, 90 or 365 complete UTC days: order count, product count, and revenue in integer minor units broken down by currency. It is a pre-aggregated summary rather than an event export, so the response size does not grow with traffic, and it contains no customer personal data. It requires the analytics:read scope and has no side effects.

Permission

Requires theanalytics:readpermission. A connection without it answersinsufficient_scopenaming the permission to approve.

Annotations

readOnlyHinttrue

destructiveHintfalse

idempotentHinttrue

openWorldHintfalse

Prerequisites

A merchant has connected this store and approved the analytics:read scope.

Arguments

periodstring

How many complete UTC days to report over. Defaults to 30d. This set is closed.

One of: 7d, 30d, 90d, 365d

end_datestring

The inclusive final UTC day, as YYYY-MM-DD. It must be before the current UTC date and defaults to yesterday.

Result

One summary covering complete UTC days, with the half-open query bounds it used. Revenue is one row per currency; rows are never converted or summed across currencies, and historical rows with an unusable stored currency appear honestly in a null-currency row.

request_idstringalways present

storeobjectalways present

store.idintegeralways present

store.namestringalways present

periodstringalways present

One of: 7d, 30d, 90d, 365d

starts_atstringalways present

The inclusive start of the reported window, UTC.

ends_beforestringalways present

The exclusive end of the reported window, UTC.

order_countintegeralways present

product_countintegeralways present

revenuearray of objectalways present

One row per currency. Amounts are never converted or added across rows.

revenue[].currencystring or null

ISO 4217, or null for historical rows whose stored currency is unusable.

revenue[].amountintegeralways present

Integer minor units of currency.

revenue[].order_countintegeralways present

Error cases

insufficient_scope

The connection was approved without analytics:read.

invalid_parameter

period is not one of the four supported windows, or end_date is not a UTC YYYY-MM-DD date before today.

The last 30 complete days

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_analytics_summary",
    "arguments": {
      "period": "30d"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "period": "30d",
      "starts_at": "2026-06-20T00:00:00Z",
      "ends_before": "2026-07-20T00:00:00Z",
      "order_count": 18,
      "product_count": 21,
      "revenue": [
        {
          "currency": "AUD",
          "amount": 248900,
          "order_count": 16
        },
        {
          "currency": "NZD",
          "amount": 31100,
          "order_count": 2
        }
      ]
    }
  }
}

A reporting period that does not exist (error)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_analytics_summary",
    "arguments": {
      "period": "14d"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "invalid_parameter",
        "title": "Invalid query parameter",
        "detail": "The period parameter must be one of: 7d, 30d, 90d, 365d.",
        "recovery": "Correct the parameter named in parameter. Dates are YYYY-MM-DD in UTC and identifiers are integers between 1 and 2147483647.",
        "parameter": "period",
        "allowed_values": [
          "7d",
          "30d",
          "90d",
          "365d"
        ]
      }
    }
  }
}