Metorik logo {dev}
MENU navbar-image

Metorik API Docs

Use the Metorik API to integrate with store data and automation workflows. This documentation currently covers products, reporting resources, and Engage endpoints.

All requests should be sent as JSON to the Metorik API base URL and authenticated with your store API key.

Base URL
https://app.metorik.com/api/v1/store
Guide

Overview

Creating API keys

Metorik API Keys screen
  1. Open your store in Metorik.
  2. Go to Settings -> Metorik API (link).
  3. Click Create API Key.
  4. Enter a descriptive name so you know what the key is used for.
  5. Select one or more scopes for the key.
  6. Choose an expiration, or leave it without one if needed.
  7. Copy the key when it is shown and store it somewhere safe.
Metorik create API key modal

Available scopes

  • Reports & Data - Read-only access to reporting and catalog data endpoints.
  • Engage - Access to supported Engage endpoints, including reading and writing some Engage data.

Authentication

Send every request with the Authorization header set as a Bearer token. The documented endpoints here all use the same token-based auth scheme.

API keys are created per store and should be treated like passwords. Store them securely and rotate or revoke them if they are ever exposed.

Make sure the API key includes the scope required by the endpoint you are calling.

Send the key

Every API request must include your API key in the Authorization header as a Bearer token.

Replace your_api_key_here with the actual key you created in Metorik, then send the request normally. 

Authorization: Bearer your_api_key_here

Rate limits

Authenticated API endpoints are protected by rate limits to keep the service stable.

  • 60 requests per minute per store or API key.

If you exceed a limit, the API returns 429 Too Many Requests. Wait briefly and retry with backoff instead of sending bursts of repeated requests.

Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers. Throttled responses also include Retry-After and X-RateLimit-Reset.

Dates

Date parameters should be sent in the store timezone using YYYY-MM-DD.

If start_date is earlier than the store's earliest available date, it is clamped to that earliest date. If end_date is later than today in the store timezone, it is clamped to today.

The store timezone and earliest available date are returned by the store info endpoint, and date values returned by report endpoints use that same store timezone.

OpenAPI spec

Download the OpenAPI YAML file to import this API into your tooling or generate clients.

Download OpenAPI YAML file

Resource

Store

Store details help you discover the authenticated store context, including timezone, currency, platform, and the earliest available reporting date.

GET /

Store details

Returns the store name, timezone, currency, platform, and earliest available report date for the authenticated API token.

Resource

Segments

Segments expose saved store-wide filters that can be reused across reporting and resource endpoints.

GET /segments

Segments

Returns store-wide saved segments for a store resource.

Parameters
resource   string  required    

Segment resource.

Must be one of:
  • orders
  • customers
  • subscriptions
  • coupons
  • products
  • variations
  • categories
  • refunds
  • carts
page   integer     

Page number. Min 1.

per_page   integer     

Number of segments per page. Min 1, max 100. Defaults to 50.

search   string     

Search saved segments by name.

Resource

Orders

Canonical order endpoints expose order records and totals for the same filtered dataset.

GET /orders

Order data

Returns orders from your store together with billing details and order totals. All returned *_at timestamps are in UTC.

Parameters
page   integer     

Page number for pagination.

per_page   integer     

Number of orders per page. Min 1, max 100.

order_by   string     

Sort field.

Must be one of:
  • order_created_at
  • order_updated_at
  • order_paid_at
  • order_completed_at
  • order_number
  • total
  • total_items
  • total_refunds
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
search   string     

Search term to filter orders.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

custom_fields   string[]     

Optional custom field keys to include in each returned order. Max 25 keys.

filters   string     

Optional JSON-encoded filter array. For guest customer orders, use metorik_customer_id to match the Metorik customer/profile ID. See Order Filters Reference.

Order Filters Reference

Use this reference for /orders filters, /orders/totals filters, order-based report order_filters, and catalog order_filters on products, variations, categories, brands, and coupons.

Filter values are sent as a JSON array of filter objects:

Example filter array 
[
    {
        "field": "billing_address_country",
        "operator": "eq",
        "value": "US"
    }
]
FieldOperators
customer_id eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
customer_saved_filter
Use a saved customer segment ID.
 eq, neq
order_number eq, neq, in, not_in, contains, is_null, not_null
status eq, neq, in, not_in, contains, is_null, not_null
billing_address_email eq, neq, in, not_in, contains, is_null, not_null
billing_address_city eq, neq, in, not_in, contains, is_null, not_null
billing_address_state eq, neq, in, not_in, contains, is_null, not_null
billing_address_country eq, neq, in, not_in, contains, is_null, not_null
shipping_address_city eq, neq, in, not_in, contains, is_null, not_null
shipping_address_state eq, neq, in, not_in, contains, is_null, not_null
shipping_address_country eq, neq, in, not_in, contains, is_null, not_null
payment_method eq, neq, in, not_in, contains, is_null, not_null
payment_method_title eq, neq, in, not_in, contains, is_null, not_null
shipping_method_title eq, neq, in, not_in, contains, is_null, not_null
created_via eq, neq, in, not_in, contains, is_null, not_null
currency eq, neq, in, not_in, contains, is_null, not_null
product
Use 123 or 123-456.
 eq, in
first_or_returning_order
Allowed values: first, returning.
 eq, in
total eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
total_items eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
total_refunds eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
net eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
order_created_at eq, neq, gt, gte, lt, lte, between, is_null, not_null
order_paid_at eq, neq, gt, gte, lt, lte, between, is_null, not_null
order_completed_at eq, neq, gt, gte, lt, lte, between, is_null, not_null
order_type
Subscription stores only. Allowed values: parent, renewal, switch, resubscribe, one-off, parent_only.
 eq, in
custom_fields.{key}
Replace {key} with the custom field key.
 eq, neq, in, not_in, contains, is_null, not_null
tags (Shopify only)
Shopify only.
 eq, contains, in
  • Multiple filters are combined with AND.
  • between expects an array with exactly two values.
  • in and not_in expect an array value.
  • Date values must be valid dates.
  • product values must be a numeric product ID like 123 or a product-variation pair like 123-456.
GET /orders/totals

Order totals

Returns summary totals for the same order dataset as the orders list endpoint. All returned *_at timestamps are in UTC.

Parameters
search   string     

Search term to filter orders before totaling.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

filters   string     

Optional JSON-encoded filter array. For guest customer orders, use metorik_customer_id to match the Metorik customer/profile ID. See Order Filters Reference.

Resource

Refunds

GET /refunds

Refund data

Returns refunds from your store together with the refunded order and customer summary details. All returned *_at timestamps are in UTC.

Parameters
page   integer     

Page number for pagination.

per_page   integer     

Number of refunds per page. Min 1, max 100.

order_by   string     

Sort field.

Must be one of:
  • refund_created_at
  • amount
  • reason
  • refund_id
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
search   string     

Search term to filter refunds.

segment   integer     

Optional saved store-wide refund segment ID. You can find the ID on the refund segments page.

filters   string     

Optional JSON-encoded refund segment filters. See Refund Filters Reference.

Refund Filters Reference

Use this reference for /refunds filters and /refunds/totals filters. Refund filters use the same internal segment filter format as saved refund segments.

Filter values are sent as a JSON array of filter objects:

Example filter array 
[
    {
        "field": "amount",
        "type": "number",
        "role": "greater-than",
        "value": 25
    }
]
FieldTypeRoles
amount number between, equals, not-equals, less-than, less-than-equals, greater-than, empty, not-empty
refund_created_at date on-exactly, before, after, date-between, in-the-past, over, weekday, weekend, empty, not-empty
product
Use product IDs or product-variation pairs like 123-456.
 productSelect include, dont-include
category categorySelect include, dont-include
vendor remoteSelect list, not-in-list, list-contains
customer
Matches refunded order billing email.
 customerSelect list, not-in-list
refund_id number equals, not-equals, less-than, greater-than
reason string contains, not-contains, equals, not-equals, empty, not-empty
status remoteSelect list, not-in-list
days_between_order_and_refund number between, equals, not-equals, less-than, less-than-equals, greater-than, empty, not-empty
order_id
Mapped internally to store_order_refunds.order_id.
 number equals, not-equals, less-than, greater-than
order_number string equals, not-equals, contains, not-contains, empty, not-empty
order_created_at date on-exactly, before, after, date-between, in-the-past, over, weekday, weekend, empty, not-empty
billing_address_country remoteSelect list, not-in-list
billing_address_state string contains, not-contains, equals, not-equals, empty, not-empty
shipping_address_country remoteSelect list, not-in-list
shipping_address_state string contains, not-contains, equals, not-equals, empty, not-empty
payment_method_title remoteSelect list, not-in-list
payment_method remoteSelect list, not-in-list
currency remoteSelect list, not-in-list
refunded_order_saved_filter
Use a saved order segment ID.
 filterSelect equals, not-equals
tags (Shopify only)
Shopify only.
 string contains, not-contains, equals, not-equals, empty, not-empty
  • Multiple filters are combined with AND unless filters_match=any is supplied.
  • between and date-between use value for the start and additional_value for the end.
  • list, not-in-list, include, and dont-include accept an array or comma-separated values.
  • Date values are interpreted in the store timezone and compared against UTC refund/order timestamps.
GET /refunds/totals

Refund totals

Returns summary totals for the same refund dataset as the refunds list endpoint. All returned *_at timestamps are in UTC.

Parameters
search   string     

Search term to filter refunds before totaling.

segment   integer     

Optional saved store-wide refund segment ID. You can find the ID on the refund segments page.

filters   string     

Optional JSON-encoded refund segment filters. See Refund Filters Reference.

Resource

Customers

Canonical customer endpoints expose customer records and totals for the same filtered dataset.

GET /customers

Customer data

Returns customers from your store together with all-time customer statistics, or period-based customer statistics when order_start_date and order_end_date are provided. All returned *_at timestamps are in UTC.

Parameters
page   integer     

Page number for pagination.

per_page   integer     

Number of customers per page. Min 1, max 100.

order_by   string     

Sort field.

Must be one of:
  • customer_created_at
  • customer_id
  • full_name
  • email
  • first_order_date
  • last_order_date
  • order_count
  • total_spent
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
search   string     

Search term to filter customers.

segment   integer     

Optional saved store-wide customer segment ID. You can find the ID on the customer segments page.

order_start_date   string     

Optional start date in the store timezone using YYYY-MM-DD format. Requires order_end_date. When provided, customer order stats are calculated for this period.

order_end_date   string     

Optional end date in the store timezone using YYYY-MM-DD format. Requires order_start_date. When provided, customer order stats are calculated for this period.

custom_fields   string[]     

Optional custom field keys to include in each returned customer. Max 25 keys.

filters   string     

Optional JSON-encoded filter array. See Customer Filters Reference.

Customer Filters Reference

Use this reference for /customers filters, /customers/totals filters, and customer-based report customer_filters.

Filter values are sent as a JSON array of filter objects:

Example filter array 
[
    {
        "field": "total_spent",
        "operator": "gte",
        "value": 100
    }
]
FieldOperators
customer_id eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
has_orders_in_segment
Use a saved order segment ID.
 eq
email eq, neq, in, not_in, contains, is_null, not_null
full_name eq, neq, in, not_in, contains, is_null, not_null
product
Any successful purchased product. Use 123 or 123-456.
 eq, in
first_product
First successful purchased product. Use 123 or 123-456.
 eq, in
subsequent_product
Subsequent (2nd+) successful purchased product. Use 123 or 123-456.
 eq, in
category
Any successful purchased category. Use the category ID, e.g. 123.
 eq, in
first_category
First successful purchased category. Use the category ID, e.g. 123.
 eq, in
subsequent_category
Subsequent (2nd+) successful purchased category. Use the category ID, e.g. 123.
 eq, in
billing_address_city eq, neq, in, not_in, contains, is_null, not_null
billing_address_country eq, neq, in, not_in, contains, is_null, not_null
shipping_address_city eq, neq, in, not_in, contains, is_null, not_null
shipping_address_country eq, neq, in, not_in, contains, is_null, not_null
role eq, neq, in, not_in, contains, is_null, not_null
order_count eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
item_count eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
total_spent eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
first_order_date eq, neq, gt, gte, lt, lte, between, is_null, not_null
last_order_date eq, neq, gt, gte, lt, lte, between, is_null, not_null
first_order_type
Subscription stores only. Allowed values: parent, renewal, switch, resubscribe, one-off, parent_only.
 eq, in
customer_created_at eq, neq, gt, gte, lt, lte, between, is_null, not_null
customer_updated_at eq, neq, gt, gte, lt, lte, between, is_null, not_null
metorik_profile eq, neq
custom_fields.{key}
Replace {key} with the custom field key.
 eq, neq, in, not_in, contains, is_null, not_null
tags (Shopify only) eq, contains, in
GET /customers/totals

Customer totals

Returns summary totals for the same customer dataset as the customers list endpoint. When order_start_date and order_end_date are provided, customer order stats are calculated for that period. All returned *_at timestamps are in UTC.

Parameters
search   string     

Search term to filter customers before totaling.

segment   integer     

Optional saved store-wide customer segment ID. You can find the ID on the customer segments page.

order_start_date   string     

Optional start date in the store timezone using YYYY-MM-DD format. Requires order_end_date. When provided, customer order stats are calculated for this period.

order_end_date   string     

Optional end date in the store timezone using YYYY-MM-DD format. Requires order_start_date. When provided, customer order stats are calculated for this period.

filters   string     

Optional JSON-encoded filter array. See Customer Filters Reference.

Resource

Subscriptions

Canonical subscription endpoints expose subscription records and recurring revenue totals for the same filtered dataset.

GET /subscriptions

Subscription data

Returns subscriptions from your store together with subscription billing fields and recurring revenue metrics. All returned *_date timestamps are in UTC.

Parameters
page   integer     

Page number for pagination.

per_page   integer     

Number of subscriptions per page. Min 1, max 100.

order_by   string     

Sort field.

Must be one of:
  • subscription_id
  • status
  • customer_id
  • start_date
  • next_payment_date
  • trial_end_date
  • end_date
  • cancelled_date
  • total
  • total_items
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
search   string     

Search term to filter subscriptions.

segment   integer     

Optional saved store-wide subscription segment ID. You can find the ID on the subscription segments page.

custom_fields   string[]     

Optional custom field keys to include in each returned subscription. Max 25 keys.

filters   string     

Optional JSON-encoded filter array. See Subscription Filters Reference.

Subscription Filters Reference

Use this reference for /subscriptions filters, /subscriptions/totals filters, and subscription-based report subscription_filters.

Filter values are sent as a JSON array of filter objects:

Example filter array 
[
    {
        "field": "billing_period",
        "operator": "eq",
        "value": "month"
    }
]
FieldOperators
subscription_id eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
status eq, neq, in, not_in, contains, is_null, not_null
customer_id eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
product
Use 123 or 123-456.
 eq, in
active_at_time
Returns subscriptions that were active on the given date. Use exact YYYY-MM-DD format.
 eq
billing_period
Common values: day, week, month, year.
 eq, neq, in, not_in, contains, is_null, not_null
billing_interval eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
start_date eq, neq, gt, gte, lt, lte, between, is_null, not_null
next_payment_date eq, neq, gt, gte, lt, lte, between, is_null, not_null
trial_end_date eq, neq, gt, gte, lt, lte, between, is_null, not_null
end_date eq, neq, gt, gte, lt, lte, between, is_null, not_null
cancelled_date eq, neq, gt, gte, lt, lte, between, is_null, not_null
total eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
total_items eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
renewal_orders_count eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
renewal_orders_total eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
parent_order_total eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
days_between_started_and_cancelled eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
requires_manual_renewal
Use true or false.
 eq, neq
custom_fields.{key}
Replace {key} with the custom field key.
 eq, neq, in, not_in, contains, is_null, not_null
GET /subscriptions/totals

Subscription totals

Returns summary totals for the same subscription dataset as the subscriptions list endpoint. All returned *_date timestamps are in UTC.

Parameters
search   string     

Search term to filter subscriptions before totaling.

segment   integer     

Optional saved store-wide subscription segment ID. You can find the ID on the subscription segments page.

filters   string     

Optional JSON-encoded filter array. See Subscription Filters Reference.

Resource

Carts

GET /carts

Cart data

Returns carts from your store. Recovery URLs are authenticated data and raw cart tokens, sessions, and payloads are never returned.

Parameters
page   integer     

Page number.

per_page   integer     

Results per page. Min 1, max 100.

search   string     

Search cart customer names and email addresses.

order_by   string     

Sort field.

Must be one of:
  • updated_at
  • started_at
  • abandoned_at
  • recovered_at
  • total
  • total_items
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
segment   integer     

Optional saved store-wide cart segment ID.

filters   string     

Optional JSON array of cart filters using field, operator, and value.

filters_match   string     

Match all or any supplied filters.

Must be one of:
  • all
  • any
Cart Filters Reference

Use this strict public filter shape for /carts and /carts/totals filters, and for report cart_filters. Each filter accepts only field, operator, and value.

Example filter array
[
    {
        "field": "status",
        "operator": "eq",
        "value": "abandoned"
    }
]
FieldOperators
email, locale, currency, vendor eq, neq, contains, in, not_in, is_null, not_null
status
Values: in-progress, abandoned, placed, recovered.
 eq, neq, in, not_in
total, total_items, subtotal, total_discount, total_shipping, customer_id eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
started_at, updated_at, abandoned_at, recovered_at eq, gt, gte, lt, lte, between, is_null, not_null
billing_address_country
Country names and common aliases are normalized to country codes.
 eq, neq, in, not_in, is_null, not_null
product, category
Product values use 123 or 123-456; category values use category IDs.
 eq, neq, in, not_in
customer_saved_filter
Use a store-wide saved customer segment ID.
 eq, neq
customer_has_ordered, customer_never_ordered, customer_no_active_subscriptions
Use yes.
 eq
has_coupons
Use yes or no.
 eq
  • between requires exactly two values.
  • in and not_in require arrays containing at most 25 values.
  • Flat report filters are ANDed with the report date range.
GET /carts/totals

Cart totals

Returns totals for the same filtered cart dataset as the cart list.

Parameters
search   string     

Search cart customer names and email addresses.

segment   integer     

Optional saved store-wide cart segment ID.

filters   string     

Optional JSON array of cart filters using field, operator, and value.

filters_match   string     

Match all or any supplied filters.

Must be one of:
  • all
  • any
Resource

Products

Product endpoints expose product-level sales metrics for a selected date range, plus by-date time series for individual products.

GET /products

Product sales

Returns products from your store together with product-level sales metrics, refunds, and sold date ranges for the selected period.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

page   integer     

Page number for pagination.

per_page   integer     

Number of products per page. Min 1, max 100.

order_by   string     

Sort field.

Must be one of:
  • title
  • sku
  • product_id
  • product_created_at
  • product_updated_at
  • stock_quantity
  • gross_items_sold
  • daily_gross_items_sold
  • gross_stock_days_left
  • items_refunded
  • net_items_sold
  • gross_sales
  • net_orders
  • net_sales
  • first_sold
  • last_sold
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
search   string     

Search term to filter products.

custom_fields   string[]     

Optional custom field keys to include in each returned product. Max 25 keys.

filters   string     

Optional JSON-encoded product filter array. Supports common product fields, tags, brand/vendor, and custom_fields.{key}.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating product sales. See Order Filters Reference.

Product Filters Reference

Use this reference for /products filters. Product filters narrow the product rows returned. Use order_filters separately to narrow the orders used for sales calculations.

Filter values are sent as a JSON array of filter objects:

Example filter array 
[
    {
        "field": "status",
        "operator": "eq",
        "value": "publish"
    }
]
FieldOperators
title eq, neq, in, not_in, contains, is_null, not_null
sku eq, neq, in, not_in, contains, is_null, not_null
type eq, neq, in, not_in, contains, is_null, not_null
status eq, neq, in, not_in, contains, is_null, not_null
vendor eq, neq, in, not_in, contains, is_null, not_null
product_id eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
stock_quantity eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
current_price eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
regular_price eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
sale_price eq, neq, in, not_in, gt, gte, lt, lte, between, is_null, not_null
in_stock
Allowed values: in-stock, out-of-stock, on-backorder.
 eq, neq
product_created_at eq, gt, gte, lt, lte, between, is_null, not_null
product_updated_at eq, gt, gte, lt, lte, between, is_null, not_null
category
Use the category ID, e.g. 123.
 eq, in, neq, not_in
custom_fields.{key}
Replace {key} with the custom field key.
 eq, neq, in, not_in, contains, is_null, not_null
GET /products/{product}/by-date

Product sales by date

Returns product sales over time for a single product in the selected period. Date buckets use the store timezone.

Parameters
product   integer  required    

The product ID.

start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating product sales. See Order Filters Reference.

Resource

Variations

Variation endpoints expose variation-level sales metrics for a selected date range, plus by-date time series for individual variations.

GET /variations

Variation sales

Returns product variations from your store together with variation-level sales metrics, refunds, and sold date ranges for the selected period.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

page   integer     

Page number for pagination.

per_page   integer     

Number of variations per page. Min 1, max 100.

order_by   string     

Sort field.

Must be one of:
  • sku
  • variation_id
  • variation_created_at
  • variation_updated_at
  • stock_quantity
  • gross_items_sold
  • daily_gross_items_sold
  • gross_stock_days_left
  • items_refunded
  • net_items_sold
  • gross_sales
  • net_orders
  • net_sales
  • first_sold
  • last_sold
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
search   string     

Search term to filter variations.

filters   string     

Optional JSON-encoded variation filter array. Supports common variation fields and parent product brand/vendor, type, status, and category.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating variation sales. See Order Filters Reference.

GET /variations/{variation}/by-date

Variation sales by date

Returns sales over time for a single variation in the selected period. Date buckets use the store timezone.

Parameters
variation   integer  required    

The variation ID.

start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating variation sales. See Order Filters Reference.

Resource

Categories

Category endpoints expose category-level sales metrics for a selected date range, plus by-date time series for individual categories.

GET /categories

Category sales

Returns product categories from your store together with category-level sales metrics, refunds, and order counts for the selected period.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

page   integer     

Page number for pagination.

per_page   integer     

Number of categories per page. Min 1, max 100.

order_by   string     

Sort field.

Must be one of:
  • name
  • category_id
  • products
  • gross_items_sold
  • items_refunded
  • net_items_sold
  • gross_sales
  • net_orders
  • net_sales
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
search   string     

Search term to filter categories.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating category sales. See Order Filters Reference.

GET /categories/{category}/by-date

Category sales by date

Returns category sales over time for a single category in the selected period. Date buckets use the store timezone.

Parameters
category   integer  required    

The category ID.

start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating category sales. See Order Filters Reference.

Resource

Brands

Brand endpoints expose vendor or brand-level sales metrics for a selected date range.

GET /brands

Brand sales

Returns product brands (also known as vendors in some platforms) from your store together with brand-level sales metrics for the selected period.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

page   integer     

Page number for pagination.

per_page   integer     

Number of brands per page. Min 1, max 100.

search   string     

Search term to filter brands.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating brand sales. See Order Filters Reference.

GET /brands/by-date

Brand sales by date

Returns sales over time for a single brand/vendor in the selected period. Date buckets use the store timezone.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

brand   string  required    

The brand/vendor name.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating brand sales. See Order Filters Reference.

Resource

Product Groups

Product group endpoints expose saved product-group sales metrics for a selected date range.

GET /product-groups

Product group sales

Returns product groups from your store together with group-level sales metrics for the selected period.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

page   integer     

Page number for pagination.

per_page   integer     

Number of product groups per page. Min 1, max 100.

search   string     

Search term to filter product groups.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating product group sales. See Order Filters Reference.

GET /product-groups/{group}/by-date

Product group sales by date

Returns sales over time for a single product group in the selected period. Date buckets use the store timezone.

Parameters
group   integer  required    

The product group ID.

start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating product group sales. See Order Filters Reference.

Resource

Coupons

Coupon endpoints expose coupon usage, discount totals, and by-date usage trends.

GET /coupons

Coupon usage

Returns coupons from your store together with usage and discount totals for the selected period.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

page   integer     

Page number for pagination.

per_page   integer     

Number of coupons per page. Min 1, max 100.

order_by   string     

Sort field.

Must be one of:
  • code
  • coupon_id
  • coupon_created_at
  • coupon_updated_at
  • amount
  • usage_count
  • total_discounted
  • sales_generated
  • sales_generated_gross_profit
  • last_used_at
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
search   string     

Search term to filter coupons.

has_usage   boolean     

Filter coupons by whether they were used in the selected period.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating coupon usage and sales. See Order Filters Reference.

GET /coupons/{coupon}/by-date

Coupon usage by date

Returns coupon usage and discount totals over time for a single coupon in the selected period. Date buckets use the store timezone.

Parameters
coupon   string  required    

The coupon ID or coupon code. Numeric-only values are treated as coupon IDs first, so numeric-only coupon codes may resolve to a coupon ID instead.

start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating coupon usage and sales. See Order Filters Reference.

Resource

Custom Metrics

Custom metrics expose store-wide metric definitions and calculated values for date ranges.

GET /custom-metrics

Custom metrics

Returns all store-wide custom metrics available to the authenticated API key. This endpoint only returns lightweight metric metadata and does not calculate values.

Parameters
page   integer     

Page number. Min 1.

per_page   integer     

Number of custom metrics per page. Min 1, max 50. Defaults to 10.

search   string     

Search by custom metric name. Max 80 characters.

GET /custom-metrics/{metric}/value

Custom metric value

Calculates a single store-wide custom metric for the requested date range and returns both the raw numeric value and a store-formatted display value. Metrics that reference non-store-wide segments are rejected.

Parameters
metric   integer  required    

The custom metric ID.

start_date   string     

Start date in the store timezone using YYYY-MM-DD format. Defaults to the store earliest date when omitted.

end_date   string     

End date in the store timezone using YYYY-MM-DD format. Defaults to today in the store timezone when omitted.

Resource

Goals

GET /goals

Goals

Returns store-wide goals available to the authenticated API key. Values are stored snapshots from the goal sync cycle; use calculated_at to determine freshness.

Parameters
ids   string     

Comma-separated goal IDs to return.

status   string     

Current period status.

Must be one of:
  • achieved
  • in_progress
  • missed
  • upcoming
  • unavailable
period_type   string     

Goal period type.

Must be one of:
  • weekly
  • monthly
  • quarterly
  • yearly
  • custom
is_recurring   boolean     

Filter recurring or one-time goals.

search   string     

Search by goal name. Max 80 characters.

refresh   boolean     

Refresh stale current period snapshots for goals returned on this page.

page   integer     

Page number. Each page contains 10 goals. Min 1.

GET /goals/{goal}

Goal

Returns a store-wide goal. The selected current period is refreshed before the response is returned when it can be calculated.

Parameters
goal   integer  required    

The goal ID.

include_periods   boolean     

Include historical/current period snapshots.

Resource

Reports

Reports expose store performance metrics over time and grouped summaries for revenue, orders, and customers.

Time Series

GET /reports/customers-by-date

Customers by date

Returns new customers over time together with their related lifetime order count, spend, and item totals for each period. Responses are capped at 1500 time periods.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_by   string     

Numeric row metric used to sort time buckets, such as customers, orders, or gross.

order_dir   string     

Sort direction when order_by is provided.

Must be one of:
  • asc
  • desc
limit   integer     

Maximum sorted rows to return. Requires order_by. Min 1, max 100.

segment   integer     

Optional saved store-wide customer segment ID. You can find the ID on the customer segments page.

customer_filters   string     

Optional JSON-encoded array of customer-level filters applied before calculating the report. See Customer Filters Reference. Cannot be combined with segment.

GET /reports/orders-by-date

Orders by date

Returns order metrics over time for orders placed in the selected period. Net values deduct refunds tied to those orders even if the refund happened later, giving you order-focused performance rather than refund timing by period. Responses are capped at 1500 time periods.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_by   string     

Numeric row metric used to sort time buckets, such as gross, net, orders, or items.

order_dir   string     

Sort direction when order_by is provided.

Must be one of:
  • asc
  • desc
limit   integer     

Maximum sorted rows to return. Requires order_by. Min 1, max 100.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/revenue-by-date

Revenue by date

Returns revenue metrics over time for the selected period. Net revenue is calculated by deducting refunds when they happen, even if they relate to orders outside this period, along with other deductions based on your store settings. Responses are capped at 1500 time periods.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_by   string     

Numeric row metric used to sort time buckets, such as gross, net, orders, or refunds.

order_dir   string     

Sort direction when order_by is provided.

Must be one of:
  • asc
  • desc
limit   integer     

Maximum sorted rows to return. Requires order_by. Min 1, max 100.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/profit-by-date

Profit by date

Returns profit metrics over time, including net revenue, costs, profit, and margin for each period in the selected date range. Responses are capped at 1500 time periods.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_by   string     

Numeric row metric used to sort time buckets, such as profit, margin, gross, or net.

order_dir   string     

Sort direction when order_by is provided.

Must be one of:
  • asc
  • desc
limit   integer     

Maximum sorted rows to return. Requires order_by. Min 1, max 100.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/advertising-costs-by-date

Advertising costs by date

Returns advertising cost totals over time, including a breakdown for each advertising method recorded in the selected date range. Responses are capped at 1500 time periods.

The meta.methods object maps each stable method ID used in totals.methods and data[].methods to its display name.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
GET /reports/visitors-by-date

Visitors by date

Returns unique visitors from the store's connected analytics provider, together with either order or new-customer conversion counts and rates. The current supported provider is Google Analytics. These are aggregate metrics and cannot identify which individual visitors did or did not buy. Responses are capped at 1500 time periods.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • day (default)
  • week
  • month
  • year
conversion_basis   string     

Metric used to calculate conversion rate. orders compares orders with visitors; customers compares new customers with visitors.

Must be one of:
  • orders
  • customers
order_by   string     

Numeric row metric used to sort time buckets, such as visitors, orders, customers, or conversion_rate.

order_dir   string     

Sort direction when order_by is provided.

Must be one of:
  • asc
  • desc
limit   integer     

Maximum sorted rows to return. Requires order_by. Min 1, max 100.

GET /reports/orders-new-returning-customers-by-date

Orders new vs returning customers by date

Returns order metrics over time split into new and returning customer groups. A customer is returning for a period when their configured customer date is before that period's effective start date. Responses are capped at 1500 time periods.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
order_by   string     

Numeric row metric used to sort time buckets, such as gross, net, orders, new_orders, or returning_orders.

order_dir   string     

Sort direction when order_by is provided.

Must be one of:
  • asc
  • desc
limit   integer     

Maximum sorted rows to return. Requires order_by. Min 1, max 100.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/carts-started-by-date

Carts started by date

Returns cart started, abandoned, placed, and recovered counts and amounts over time for the selected period. Responses are capped at 1500 time periods. Your store must already have cart tracking/data set up in Metorik for this report to return meaningful cart activity.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
segment   integer     

Optional saved store-wide cart segment ID.

cart_filters   string     

Optional JSON array of cart filters using field, operator, and value.

GET /reports/subscriptions-stats

Subscriptions stats

Requires subscriptions

Returns active subscription and MRR stats over time for subscription stores. Responses are capped at 1500 time periods.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • day (default)
  • week
  • month
GET /reports/subscription-events

Subscription events

Returns subscription signups, renewals, resubscribes, switches, endings, net subscription change, and event revenue over time. Responses are capped at 1500 time periods.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
GET /reports/future-renewal-revenue

Future renewal revenue

Requires subscriptions

Returns projected upcoming subscription renewal revenue over time for subscription stores. If start_date is today, only renewals after the current moment are included; renewals earlier today are excluded. Responses are capped at 1500 time periods.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format. Must be today or later.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

group_by   string     

Time interval for grouping the results.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
  • week
  • month
  • year
segment   integer     

Optional saved store-wide subscription segment ID.

subscription_filters   string     

Optional JSON-encoded array of subscription-level filters applied before projecting renewals. Supports filters like billing_period and parent_order_status.

Grouped Summaries

GET /reports/revenue-grouped-by

Revenue grouped by

Returns revenue metrics grouped by a chosen store dimension, such as billing country, product type, or another supported grouping value. Responses are capped at 1500 grouped rows.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

grouped_by   string  required    

Dimension to group revenue by.

Must be one of:
  • billing_address_country
  • billing_address_state
  • billing_address_city
  • billing_address_postcode
  • shipping_address_country
  • shipping_address_state
  • shipping_address_city
  • shipping_address_postcode
  • payment_method
  • payment_method_title
  • shipping_method_id
  • shipping_method_title
  • currency
  • created_via
  • order_type
  • tax_rate_code
  • tax_rate_label
  • tax_rate_id
  • customer_role
  • custom_field
custom_field_key   string     

Required when grouped_by is custom_field. Custom field key to group orders by.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/orders-grouped-by

Orders grouped by

Returns order metrics grouped by a chosen store dimension, so you can compare order performance across segments like country or other supported grouping values. Responses are capped at 1500 grouped rows.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

grouped_by   string  required    

Dimension to group orders by.

Must be one of:
  • billing_address_country
  • billing_address_state
  • billing_address_city
  • billing_address_postcode
  • billing_address_company
  • shipping_address_country
  • shipping_address_state
  • shipping_address_city
  • shipping_address_postcode
  • shipping_address_company
  • status
  • customer_role
  • payment_method
  • payment_method_title
  • shipping_method_id
  • shipping_method_title
  • fee_line_title
  • currency
  • created_via
  • order_type
  • custom_field
custom_field_key   string     

Required when grouped_by is custom_field. Custom field key to group orders by.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/customers-grouped-by

Customers grouped by

Returns customer metrics grouped by a chosen store dimension, helping you compare customer activity across segments like billing country or other supported grouping values. Responses are capped at 1500 grouped rows.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

grouped_by   string  required    

Dimension to group customers by.

Must be one of:
  • billing_address_country
  • billing_address_state
  • billing_address_city
  • billing_address_postcode
  • billing_address_company
  • shipping_address_country
  • shipping_address_state
  • shipping_address_city
  • shipping_address_postcode
  • shipping_address_company
  • role
  • customer_type
  • custom_field
  • day
  • week
  • month
  • year
  • first_product
  • first_category
  • first_coupon
custom_field_key   string     

Required when grouped_by is custom_field. Custom field key to group customers by.

segment   integer     

Optional saved store-wide customer segment ID. You can find the ID on the customer segments page.

customer_filters   string     

Optional JSON-encoded array of customer-level filters applied before calculating the report. See Customer Filters Reference. Cannot be combined with segment.

GET /reports/carts-grouped-by

Carts grouped by

Returns cart counts grouped by a selected cart field, including abandoned, placed, and recovered counts and rates. Responses are capped at 1500 grouped rows. Your store must already have cart tracking/data set up in Metorik for this report to return meaningful cart activity.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

grouped_by   string  required    

Dimension to group carts by.

Must be one of:
  • billing_address_country
segment   integer     

Optional saved store-wide cart segment ID.

cart_filters   string     

Optional JSON array of cart filters using field, operator, and value.

Attribution

GET /reports/sources

Sources - referer

Returns order source domain performance for the selected period. Responses are capped at 1500 grouped rows.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

specific   string     

Optional partial domain filter. Responses are capped at 1500 grouped rows.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/sources-landing

Sources - landing

Returns landing path performance for orders in the selected period. Responses are capped at 1500 grouped rows.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/sources-utms

Sources - UTM

Returns grouped UTM performance for orders in the selected period. Responses are capped at 1500 grouped rows.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

source_type   string  required    

Comma-separated UTM fields to group by. Allowed: utm_campaign, utm_medium, utm_source, utm_term, utm_content, utm_id.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/customer-sources

Customer sources - referer

Returns customer acquisition source performance for the selected period. Responses are capped at 1500 grouped rows.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

segment   integer     

Optional saved store-wide customer segment ID. You can find the ID on the customer segments page.

customer_filters   string     

Optional JSON-encoded array of customer-level filters applied before calculating the report. See Customer Filters Reference. Cannot be combined with segment.

GET /reports/customer-sources-landing

Customer sources - landing

Returns customer acquisition landing path performance for the selected period. Responses are capped at 1500 grouped rows.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

segment   integer     

Optional saved store-wide customer segment ID. You can find the ID on the customer segments page.

customer_filters   string     

Optional JSON-encoded array of customer-level filters applied before calculating the report. See Customer Filters Reference. Cannot be combined with segment.

GET /reports/customer-sources-utms

Customer sources - UTM

Returns grouped customer acquisition UTM performance for the selected period. Responses are capped at 1500 grouped rows.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

source_type   string  required    

Comma-separated UTM fields to group by. Allowed: utm_campaign, utm_medium, utm_source, utm_term, utm_content, utm_id.

segment   integer     

Optional saved store-wide customer segment ID. You can find the ID on the customer segments page.

customer_filters   string     

Optional JSON-encoded array of customer-level filters applied before calculating the report. See Customer Filters Reference. Cannot be combined with segment.

Order Breakdowns

GET /reports/orders-by-hour

Orders by hour

Returns order counts and sales totals grouped by hour of day across the selected period.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/orders-by-day

Orders by day of week

Returns order counts and sales totals grouped by weekday across the selected period.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/orders-by-day-hour

Orders by day and hour

Returns order counts, totals, and average order value grouped by weekday and hour across the selected period.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference. Cannot be combined with segment.

GET /reports/orders-devices

Orders devices

Returns order counts and sales totals split by device category for the selected period. When Google Analytics visitor data is available, rows also include unique visitors and conversion rate.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

GET /reports/orders-operating-systems

Orders operating systems

Returns order counts and sales totals split by operating system for the selected period. When Google Analytics visitor data is available, rows also include unique visitors and conversion rate.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

GET /reports/orders-browsers

Orders browsers

Returns order counts and sales totals split by browser for the selected period. When Google Analytics visitor data is available, rows also include unique visitors and conversion rate.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

segment   integer     

Optional saved store-wide order segment ID. You can find the ID on the order segments page.

Product Relationships

GET /reports/products-bought-together

Products bought together

Returns product pairs that were purchased together in the selected period. Use product_id to limit the response to pairs involving a specific product. total_order_count is the number of distinct orders containing product_1 in the same period and filters, including orders that did not contain product_2.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

page   integer     

Page number for pagination.

per_page   integer     

Number of pairs per page. Min 1, max 100.

product_id   string     

Limit results to pairs involving this product.

variation_id   string     

Limit results to pairs involving this variation. Requires product_id.

order_filters   string     

Optional JSON-encoded array of order-level filters applied before calculating the report. See Order Filters Reference.

Cart Reports

GET /reports/carts-products

Cart products

Returns products ranked by cart activity for the selected period.

Parameters
start_date   string  required    

Start date in the store timezone.

end_date   string  required    

End date in the store timezone.

order_by   string     

Metric used for ranking.

Must be one of:
  • started_count
  • started_total
  • abandoned_count
  • abandoned_total
  • placed_count
  • placed_total
  • recovered_count
  • recovered_total
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
limit   integer     

Maximum rows. Min 1, max 100.

segment   integer     

Optional saved store-wide cart segment ID.

cart_filters   string     

Optional JSON array of cart filters using field, operator, and value.

GET /reports/carts-started-placed-time-difference

Cart started-to-placed time

Returns the distribution of elapsed time between cart start and order placement.

Parameters
start_date   string  required    

Start date in the store timezone.

end_date   string  required    

End date in the store timezone.

group_by   string     

Bucket unit. Omit for automatic selection.

Must be one of:
  • hour (only if range under 1 month)
  • day (default)
segment   integer     

Optional saved store-wide cart segment ID.

cart_filters   string     

Optional JSON array of cart filters using field, operator, and value.

Subscriptions

GET /reports/subscription-retention

Subscription retention

Returns monthly subscription and MRR retention and churn rates. The month before start_date is used internally to calculate the first requested month but is not included in the response.

Parameters
start_date   string  required    

Start date in the store timezone using YYYY-MM-DD format.

end_date   string  required    

End date in the store timezone using YYYY-MM-DD format.

GET /reports/subscription-active-grouped-by

Active subscriptions grouped by

Returns the current active subscription count and MRR grouped by a subscription or parent-order dimension.

Parameters
grouped_by   string  required    

Dimension to group active subscriptions by.

Must be one of:
  • billing_address_country
  • billing_address_state
  • billing_address_city
  • billing_address_postcode
  • shipping_address_country
  • shipping_address_state
  • shipping_address_city
  • shipping_address_postcode
  • payment_method
  • payment_method_title
  • billing_period
  • billing_interval
  • currency
  • custom_field
custom_field_key   string     

Custom subscription field key. Required when grouped_by is custom_field.

country_limit   string     

Optional country code used to constrain state, city, or postcode groups.

billing_period_limit   string     

Optional billing period used when grouping by billing_interval.

Must be one of:
  • day
  • week
  • month
  • year
order_by   string     

Sort field.

Must be one of:
  • grouped_by
  • count
  • total_mrr
  • total
  • total_items
  • average_items
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
limit   integer     

Maximum rows to return. Min 1, max 100. Defaults to 10.

GET /reports/subscription-plans

Subscription plans

Returns plan-level MRR and active subscription counts for subscription products and variations. Dates are optional. Without dates, current values are returned. Monthly history is optional and defaults to the latest 12 months when enabled without dates.

Parameters
start_date   string     

Optional start date in the store timezone using YYYY-MM-DD format. Must be provided with end_date.

end_date   string     

Optional end date in the store timezone using YYYY-MM-DD format. Determines the headline MRR and active subscription snapshot. Must be provided with start_date.

include_monthly_stats   boolean     

Include monthly MRR and active subscription history. Defaults to false.

all_products   boolean     

Include all products that have subscription stats, rather than only subscription product types. Defaults to false.

order_by   string     

Sort field.

Must be one of:
  • mrr
  • active_subscriptions
  • title
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
page   integer     

Page number for pagination.

per_page   integer     

Number of plans per page. Min 1, max 100.

Engage

Profiles

Profiles are lightweight contact records stored in Metorik for Engage. Use this resource to create or remove profile records for a store.

GET /engage/profile

Get a profile by email

Get a Metorik Engage profile by email for a store.

Parameters
email   string  required    

Email address for the profile.

POST /engage/profiles

Create or update a profile

Create or update a Metorik-only Engage profile for a store.

Parameters
email   string  required    

Email address for the profile.

first_name   string     

First name for the profile.

last_name   string     

Last name for the profile.

country   string     

Two-letter country code for the billing country.

company   string     

Company name for the profile.

consent   string     

Consent level to apply.

Must be one of:
  • single
  • double
tags   array|string     

Tags to set on the profile as either an array of tags or a comma-separated string. When sent, tags replace the existing set.

add_tags   array|string     

Tags to add to the profile as either an array of tags or a comma-separated string. Tags are only added if they do not already exist.

remove_tags   array|string     

Tags to remove from the profile as either an array of tags or a comma-separated string. Tags are only removed if they currently exist.

DELETE /engage/profiles

Delete a profile

Delete a Metorik-only Engage profile with no orders.

Parameters
email   string  required    

Email address for the profile to delete.

Engage

Unsubscribes

Unsubscribes track which recipients should no longer receive Engage emails. Use this resource to list, check, create, and remove unsubscribe records.

GET /engage/unsubscribes

List unsubscribes

List unsubscribes for a store.

Parameters
start_date   string     

Only return unsubscribes created on or after this datetime. Legacy after also works, but is deprecated.

end_date   string     

Only return unsubscribes created on or before this datetime. Legacy before also works, but is deprecated.

order   string     

Sort direction by created date.

Must be one of:
  • asc
  • desc
per_page   integer     

Number of results per page.

page   integer     

Page number to fetch.

GET /engage/unsubscribe-status

Check unsubscribe status

Check whether an email address is unsubscribed.

Parameters
email   string  required    

Email address to check.

POST /engage/unsubscribes

Create or update an unsubscribe

Create or update an unsubscribe record for an email address.

Parameters
email   string  required    

Email address to unsubscribe.

reason   string     

Reason the email address was unsubscribed.

DELETE /engage/unsubscribes

Delete an unsubscribe

Delete an unsubscribe record for an email address.

Parameters
email   string  required    

Email address to re-subscribe.