Queek docs
Merchant endpoint reference

Analytics

GET
/analytics/traffic

Requires scope merchant-analytics-traffic-read.

Reads up to 30 days of anonymous storefront traffic for this store: daily views and visits, bot request count, and measurement metadata. Visits are not unique visitors because shared mobile networks can group shoppers. Bot requests count requests and are not views. Figures can lag live traffic by up to about ten minutes (daily totals refresh every five minutes and responses are cached for up to five); only the installed app's own key with this grant can use this route.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

days?integer

Number of days of traffic to return, counting back from today: 1 to 30 (default 30).

Range1 <= value <= 30
app_id?string

Not accepted: the calling installation is identified by its key.

installation_id?string

Not accepted: the calling installation is identified by its key.

source?string

Not accepted: the source is the calling installation.

source_app_id?string

Not accepted: the source is the calling installation.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/analytics/traffic?days=30" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Traffic retrieved.",  "data": {    "range": {      "days": 3,      "start": "2026-10-01T00:00:00+01:00",      "end": "2026-10-03T23:59:59+01:00"    },    "cards": {      "views": 31,      "visits": 21,      "bot_requests": 4    },    "charts": {      "views_trend": [        {          "date": "2026-10-01",          "views": 10,          "visits": 7        },        {          "date": "2026-10-02",          "views": 12,          "visits": 8        },        {          "date": "2026-10-03",          "views": 9,          "visits": 6        }      ]    },    "meta": {      "collecting_since": "2026-09-20T00:00:00+01:00",      "raw_retention_days": 14,      "dedupe_window_minutes": 30    }  }}
GET
/analytics/sales

Requires scope merchant-analytics-sales-read.

Reads the store’s sales for a range of whole days: order counts, gross revenue and average order value of completed orders, daily, weekly or monthly order and revenue trends (daily up to 31 days, weekly up to 90), and orders by status and by sales channel. start_date and end_date (YYYY-MM-DD, both or neither) default to the last 30 days; a range may be at most 90 days and may not end after today (422 otherwise). Amounts are decimal strings in the store currency. Net revenue, fees and settlements are payments data and are not included. Figures are computed from the store’s orders, cached for up to three minutes and shared by every app of the store, so they can lag a new order by that long. Each installation may make 20 analytics reads a minute and 1,000 a day across the sales, products and customers routes (429 with Retry-After beyond that); a cached answer counts too.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

start_date?|

First day of the range (YYYY-MM-DD, in the store time zone). Send with end_date.

Formatdate
end_date?|

Last day of the range, inclusive (YYYY-MM-DD, in the store time zone). Send with start_date.

Formatdate
app_id?string

Not accepted: the calling installation is identified by its key.

installation_id?string

Not accepted: the calling installation is identified by its key.

source?string

Not accepted: the source is the calling installation.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/analytics/sales?start_date=2026-09-21&end_date=2026-09-27" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Sales analytics retrieved.",  "data": {    "range": {      "start": "2026-09-21",      "end": "2026-09-27",      "days": 7    },    "currency": "USD",    "currency_meta": {      "code": "USD",      "symbol": "$",      "precision": 2    },    "cards": {      "total_orders": 128,      "completed_orders": 104,      "cancelled_orders": 9,      "gross_revenue": "4837.00",      "avg_order_value": "46.51"    },    "charts": {      "order_trends": [        {          "period": "2026-09-21",          "orders": 4        },        {          "period": "2026-09-22",          "orders": 7        }      ],      "revenue_trends": [        {          "period": "2026-09-21",          "revenue": "184.80"        },        {          "period": "2026-09-22",          "revenue": "323.60"        }      ],      "status_distribution": [        {          "status": "completed",          "orders": 104        },        {          "status": "pending",          "orders": 13        },        {          "status": "cancelled",          "orders": 9        },        {          "status": "rejected",          "orders": 2        }      ],      "channel_distribution": [        {          "channel": "storefront",          "name": "Storefront",          "orders": 71        },        {          "channel": "pos",          "name": "POS",          "orders": 57        }      ]    },    "meta": {      "period": "daily"    }  }}
GET
/analytics/products

Requires scope merchant-analytics-products-read.

Reads what sold in a range of whole days, from completed orders only: units sold, the best seller by revenue and by quantity, the ten top products by revenue and by quantity, and order lines per collection (the ten largest). Same start_date/end_date rules, 90-day limit, caching and request budget as sales analytics. A product with no title shows Unknown.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

start_date?|

First day of the range (YYYY-MM-DD, in the store time zone). Send with end_date.

Formatdate
end_date?|

Last day of the range, inclusive (YYYY-MM-DD, in the store time zone). Send with start_date.

Formatdate
app_id?string

Not accepted: the calling installation is identified by its key.

installation_id?string

Not accepted: the calling installation is identified by its key.

source?string

Not accepted: the source is the calling installation.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/analytics/products?start_date=2026-09-21&end_date=2026-09-27" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Product analytics retrieved.",  "data": {    "range": {      "start": "2026-09-21",      "end": "2026-09-27",      "days": 7    },    "currency": "USD",    "currency_meta": {      "code": "USD",      "symbol": "$",      "precision": 2    },    "cards": {      "total_products_sold": 412,      "bestselling_product": "Smokehouse Party Pack",      "bestselling_product_revenue": "1850.00",      "most_popular_product": "Fresh Lemonade",      "most_popular_product_quantity": 138    },    "charts": {      "top_products_by_revenue": [        {          "name": "Smokehouse Party Pack",          "revenue": "1850.00"        },        {          "name": "Fresh Lemonade",          "revenue": "414.00"        }      ],      "top_products_by_quantity": [        {          "name": "Fresh Lemonade",          "quantity": 138        },        {          "name": "Smokehouse Party Pack",          "quantity": 50        }      ],      "category_distribution": [        {          "name": "Party packs",          "order_lines": 61        },        {          "name": "Drinks",          "order_lines": 54        }      ]    }  }}
GET
/analytics/customers

Requires scope merchant-analytics-customers-read.

Reads aggregate customer figures for a range of whole days: new and returning customers, 7-day and 30-day retention rates (always measured back from today, whatever the range), the average lifetime spend of customers who completed an order in the range, first-time versus loyal buyer counts and orders by payment method. Counts, rates and one average only: no customer, name or contact is returned or can be reached from this route. Same start_date/end_date rules, 90-day limit, caching and request budget as sales analytics.

Authorization

merchantKey
X-Client-Key<token>

The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.

In: header

Query Parameters

start_date?|

First day of the range (YYYY-MM-DD, in the store time zone). Send with end_date.

Formatdate
end_date?|

Last day of the range, inclusive (YYYY-MM-DD, in the store time zone). Send with start_date.

Formatdate
app_id?string

Not accepted: the calling installation is identified by its key.

installation_id?string

Not accepted: the calling installation is identified by its key.

source?string

Not accepted: the source is the calling installation.

Header Parameters

X-Client-Key*string

A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.

X-Request-Id?string

Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/analytics/customers?start_date=2026-09-21&end_date=2026-09-27" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Customer analytics retrieved.",  "data": {    "range": {      "start": "2026-09-21",      "end": "2026-09-27",      "days": 7    },    "currency": "USD",    "currency_meta": {      "code": "USD",      "symbol": "$",      "precision": 2    },    "cards": {      "new_customers": 38,      "returning_customers": 52,      "retention_7_days": 41.5,      "retention_30_days": 33.25,      "avg_customer_ltv": "62.40"    },    "charts": {      "customer_segments": [        {          "segment": "first_time",          "customers": 64        },        {          "segment": "loyal",          "customers": 26        }      ],      "payment_methods": [        {          "method": "Card",          "orders": 61        },        {          "method": "Pos",          "orders": 43        }      ]    }  }}