Metorik logo {dev} Beta
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

Beta

The new Metorik API is currently in beta. Endpoints and response shapes can change as we iterate.

We are actively evolving it with customer feedback, so if you run into issues or need additional endpoints, please let us know.

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.

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.

filters   string     

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

Order Filters Reference

Use this reference for /orders filters, /orders/totals 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
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_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
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
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
tags (Shopify only) eq, contains, in
product eq, 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.

filters   string     

Optional JSON-encoded filter array. See Order 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.

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.

Customer Filters Reference

Use this reference for /customers filters and /customers/totals 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
email eq, neq, in, not_in, contains, is_null, not_null
full_name eq, neq, in, not_in, contains, is_null, not_null
product eq, in
first_product eq, in
subsequent_product eq, in
category eq, in
first_category eq, in
subsequent_category 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
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
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.

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
  • billing_period
  • billing_interval
  • start_date
  • next_payment_date
  • trial_end_date
  • end_date
  • cancelled_date
  • total
  • total_items
  • total_mrr
  • renewal_orders_count
  • renewal_orders_total
  • parent_order_total
order_dir   string     

Sort direction.

Must be one of:
  • asc
  • desc
search   string     

Search term to filter subscriptions.

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.

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
  • gross_items_sold
  • 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.

order_filters   string     

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

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.

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
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
  • gross_items_sold
  • 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.

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.

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
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.

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
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.

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.

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
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 100. Defaults to 50.

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.

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.

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
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
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
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
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/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
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

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

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.

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.

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.

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.

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   integer     

Limit results to pairs involving this product.

variation_id   integer     

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.

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.