API docs by Redocly

OBS Public API (1.5.0)

Download OpenAPI specification:

Public WordPress API Endpoints by OBS

The authentication is realized with an additional WordPress user that has a specific user role, only allowing it to access certain endpoints, no other WordPress access (you need the matching OBS plugin to provide that user role). To authenticate with the API, you need to create an Application Password for that user as username/password is not allowed for WordPress API access. Use the username and Application Password with BasicAuth

Orders

Get all order numbers of the last 30 days of order

Get all order numbers of the last 30 days of orders that were already transferred to the middleware (done every 2 minutes).

Authorizations:
BasicAuth
query Parameters
newer_than
string <date-time>

Filter the orders (of the last 30 days) to be newer than the passed ISO 8601 / RFC 3339 timestamp

Responses

Response samples

Content type
application/json
[
  • "1698243392.125004871",
  • "1697624864.125008737",
  • "1697549911.125007887"
]

Get the order details for an order number

Only returns orders with status = 2

Authorizations:
BasicAuth
path Parameters
order_number
required
string (Order_Number) [0-9]{10}\.[0-9]{8,9}
Example: 1639331260.125003824

(Required) The order number

Responses

Response samples

Content type
application/json
{
  • "order_number": "1697624864.125008737",
  • "shop_id": 125,
  • "erp_order_number": "",
  • "status": 1,
  • "type": 0,
  • "products": [
    ],
  • "customer_data": {
    },
  • "shipping": {
    },
  • "payment": {
    },
  • "price": {
    },
  • "erp_customer_id": 0,
  • "customer_id": "",
  • "zip": "12345",
  • "order_created": "2021-12-12 19:52:03",
  • "shipping_handler_details": [
    ]
}

Update the value of the shipping handler details field of an order

Replaces the current value, to add details, first get the current value

Authorizations:
BasicAuth
path Parameters
order_number
required
string (Order_Number) [0-9]{10}\.[0-9]{8,9}
Example: 1639331260.125003824

(Required) The order number

Request Body schema: application/json
Array of objects (Shipping_Handler_Details)
Array
name
required
string

Name of the delivery company/ delivery type. Displayed to the shop customer on the order overview page (Oneboxshop Cart) as the shipping handler.

description
string

Description of the delivery company/ delivery type. Displayed to the shop customer on the order overview page (Oneboxshop Cart) as the shipping handler hint.

tracking_number
string

Tracking code that can be used to track this delivery

tracking_url
string

Tracking URL that can be used to track this delivery. If passed, a button is displayed to the shop customer on the order overview page (Oneboxshop Cart) that links to this tracking page.

product_ids
required
Array of strings

The product IDs this shipping/ delivery is used for

object non-empty

Per product_id, the amount of the product. Optional, but must not be empty if present

timestamp_change
string
expected_delivery
string

Responses

Request samples

Content type
application/json
{
  • "shipping_handler_details": [
    ]
}

Append one set of shipping handler details to the order's shipping handler details

Retrieves the shipping handler details of the order, adds the new set to it, and saves it back to the database.

Authorizations:
BasicAuth
path Parameters
order_number
required
string (Order_Number) [0-9]{10}\.[0-9]{8,9}
Example: 1639331260.125003824

(Required) The order number

Request Body schema: application/json
object (Shipping_Handler_Details)

Real shipping/ delivery details entered by ERP or external: Tracking data, parcel info, etc. Empty when order created

name
required
string

Name of the delivery company/ delivery type. Displayed to the shop customer on the order overview page (Oneboxshop Cart) as the shipping handler.

description
string

Description of the delivery company/ delivery type. Displayed to the shop customer on the order overview page (Oneboxshop Cart) as the shipping handler hint.

tracking_number
string

Tracking code that can be used to track this delivery

tracking_url
string

Tracking URL that can be used to track this delivery. If passed, a button is displayed to the shop customer on the order overview page (Oneboxshop Cart) that links to this tracking page.

product_ids
required
Array of strings

The product IDs this shipping/ delivery is used for

object non-empty

Per product_id, the amount of the product. Optional, but must not be empty if present

timestamp_change
string
expected_delivery
string

Responses

Request samples

Content type
application/json
{
  • "shipping_handler_details": {
    }
}

Analytics

Which analytics data sources are available on this shop

Reports whether the OBS Metrics sales and tracking tables exist. Does not require OBS Metrics to be active.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

How much data the analytics are based on, and when it was last imported

Oldest order date, last successful import time and whole-table record counts. Not period-scoped.

Authorizations:
BasicAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Revenue, order count, AOV and units sold in the period

revenue is SUM(orders.sum_total): the final order total (incl. shipping + payment, after voucher). Tax-inclusive, except for tax-exempt orders (delivery outside the EU, EU reverse charge), whose total is net -- the sum can therefore mix gross and net totals. Percentage vouchers are rounded to the cent per item before being multiplied by the quantity, so recomputing a total from its parts can differ by a few cents. See meta.revenue_basis.

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

status
string
Enum: "1" "2" "100" "accepted"

Optional order processing-stage filter: 1 (new), 100 (in progress), 2 (accepted), or the alias 'accepted' (= 2). Default: all. This is a processing stage, NOT a cancellation filter. Other values are ignored (= all).

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Top brands, categories or products by gross line revenue Deprecated

revenue is SUM(order_products.amount * price): product line value before voucher, excluding shipping/payment, tax-inclusive. Ordered by revenue DESC. See meta.revenue_basis.

Authorizations:
BasicAuth
query Parameters
by
required
string
Enum: "brand" "category" "product"

Grouping for the top list.

range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

status
string
Enum: "1" "2" "100" "accepted"

Optional order processing-stage filter: 1 (new), 100 (in progress), 2 (accepted), or the alias 'accepted' (= 2). Default: all. This is a processing stage, NOT a cancellation filter. Other values are ignored (= all).

limit
integer [ 1 .. 100 ]
Default: 10

Row limit, clamped server-side to 1..100.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Complete, pageable sales aggregates over any combination of dimensions

The general form of sales/top: the same aggregation over order lines, but grouped by whatever you ask for (including day), not capped at a ranking, and pageable via a keyset cursor -- so a consumer can pull an entire period and know from pagination.has_more that it saw every row. Rows only exist where there was a sale; a product with no sale on a day is simply absent, which after a complete pull is exactly what makes a zero derivable. Revenue is always item_gross_before_voucher. Dimensions: day, month, product, wrapper, brand, category, attribute, traffic_group. traffic_group is the traffic group of the order (Direct, Organic, Paid; same classification as the tracking traffic groups), so dimensions=traffic_group closes the funnel of tracking/breakdown per channel. Like the tracking data it is recorded only in the shop itself, not by the ERP: OBS Metrics copies it daily from the shop's order queue, which keeps orders for 28 days. Data therefore starts 28 days before the shop's OBS Metrics update that introduced it; older orders, and orders placed without a traffic group (visitor tracking off), are grouped as Unknown. records.order_traffic in data-foundation counts the orders recorded so far: null means the shop's OBS Metrics does not record traffic groups; a count that stops growing means recording has stopped (it runs with the daily OBS Metrics import, so that import must be set up). A shop whose OBS Metrics is too old answers the traffic_group dimension with 400 invalid_dimensions and the traffic_group filter with 409 metrics_required.

Authorizations:
BasicAuth
query Parameters
dimensions
required
string
Example: dimensions=day,product

Comma-separated grouping dimensions. Order matters: it defines the row order and therefore the cursor. Any unknown name is 400 invalid_dimensions. Use month for monthly groups (e.g. month,brand); the breakdown endpoints have no granularity parameter. A shop whose OBS Metrics predates the month dimension answers it with 400 invalid_dimensions.

sort
string
Enum: "revenue" "qty" "orders"

Omit for the pageable mode: rows ordered by the dimensions ascending, cursor supported, complete result set. Set it for the ranked mode: rows ordered by that measure descending, capped at limit, no cursor. Ranked mode is what /sales/top does.

range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

status
string
Enum: "1" "2" "100" "accepted"

Optional order processing-stage filter: 1 (new), 100 (in progress), 2 (accepted), or the alias 'accepted' (= 2). Default: all. This is a processing stage, NOT a cancellation filter. Other values are ignored (= all).

limit
integer [ 1 .. 10000 ]
Default: 1000

Row limit, clamped server-side to 1..10000. Prefer large pages: every page re-runs the same aggregation, so a few big pages are much cheaper than many small ones.

cursor
string

Opaque keyset cursor from pagination.next_cursor of the previous page. Stateless and non-expiring: it encodes the last row's dimension values plus a fingerprint of the query it belongs to. Replaying it against a different window, different dimensions or different filters is 400 invalid_cursor. Not combinable with sort (400 cursor_not_supported).

with_total
boolean
Default: false

Also return meta.total_rows, the total number of groups in the window ignoring limit and cursor. Off by default because it runs the aggregation a second time.

item_wrapper_id
string

Restrict to one product (the wrapper that groups all variants).

item_id
string

Restrict to one concrete product variant.

brand
string

Restrict to one brand. Exact match on the stored value, as returned by the brand dimension.

category
string

Restrict to one category path. Exact match on the stored value, as returned by the category dimension -- not a prefix match.

traffic_group
string
Enum: "Direct" "Organic" "Paid" "Unknown"

Restrict to orders of one traffic group. Unknown selects the orders without a recorded traffic group. Any other value is 400 rest_invalid_param.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    },
  • "meta": {
    }
}

Voucher usage total and per-voucher breakdown

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

status
string
Enum: "1" "2" "100" "accepted"

Optional order processing-stage filter: 1 (new), 100 (in progress), 2 (accepted), or the alias 'accepted' (= 2). Default: all. This is a processing stage, NOT a cancellation filter. Other values are ignored (= all).

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Payment-method distribution with share of orders

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

status
string
Enum: "1" "2" "100" "accepted"

Optional order processing-stage filter: 1 (new), 100 (in progress), 2 (accepted), or the alias 'accepted' (= 2). Default: all. This is a processing stage, NOT a cancellation filter. Other values are ignored (= all).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Average shipping cost, free-shipping share and method distribution

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

status
string
Enum: "1" "2" "100" "accepted"

Optional order processing-stage filter: 1 (new), 100 (in progress), 2 (accepted), or the alias 'accepted' (= 2). Default: all. This is a processing stage, NOT a cancellation filter. Other values are ignored (= all).

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Revenue, orders and units sold per local day or local calendar month

One row per local day (default) or, with granularity=month, per local calendar month; buckets without orders are omitted. Month rows carry month instead of day and use exact local month boundaries (also across DST changes), so a full month row equals sales/summary?month=YYYY-MM. The first and last month are clipped to the requested window (see meta.start/meta.end). The window itself is unchanged: at most 548 days, i.e. up to 20 monthly rows.

Authorizations:
BasicAuth
query Parameters
granularity
string
Default: "day"
Enum: "day" "month"

Bucket size of the timeseries rows: day (default) or month. Any other value is 400 invalid_granularity. Not to be confused with the month parameter, which selects a whole month as the window. The window limit stays 548 days for both.

range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

status
string
Enum: "1" "2" "100" "accepted"

Optional order processing-stage filter: 1 (new), 100 (in progress), 2 (accepted), or the alias 'accepted' (= 2). Default: all. This is a processing stage, NOT a cancellation filter. Other values are ignored (= all).

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Products frequently bought together with a given product (cross-sell)

All-time (not period-scoped) basket combinations from local order history. base_orders_count reports how many orders contain the base product (0 = no local history; empty combinations then just means no data, not necessarily a non-existent product).

Authorizations:
BasicAuth
query Parameters
item_wrapper_id
required
integer

The base product to find combinations for.

min_orders
integer >= 1
Default: 2

Minimum shared orders for a combination to count (default 2).

limit
integer [ 1 .. 100 ]
Default: 10

Row limit, clamped server-side to 1..100.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Product views and add-to-cart, total and per traffic group

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

item_wrapper_id
string

Optional filter to a single product (item_wrapper_id). Empty is treated as not set.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Per traffic group (Direct, Organic, Paid) with views share

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

item_wrapper_id
string

Optional filter to a single product (item_wrapper_id). Empty is treated as not set.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Top products by views or add-to-cart Deprecated

Both metrics are always returned; by selects the sort key. group selects whether rows are products (default), brands or categories.

Authorizations:
BasicAuth
query Parameters
by
required
string
Enum: "views" "cart"

Sort key for the tracking top list.

group
string
Default: "product"
Enum: "product" "brand" "category"

Grouping for the tracking top list: product (default), brand or category. Other values are treated as product.

range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

item_wrapper_id
string

Optional filter to a single product (item_wrapper_id). Empty is treated as not set.

limit
integer [ 1 .. 100 ]
Default: 10

Row limit, clamped server-side to 1..100.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Complete, pageable tracking aggregates over any combination of dimensions

The general form of tracking/top, with day and traffic_group available as dimensions in their own right, so per-product-per-channel-per-day is one request. Rows only exist where there was traffic. Note time_basis is utc_day here while sales/breakdown is local_day.

Authorizations:
BasicAuth
query Parameters
dimensions
required
string
Example: dimensions=day,product

Comma-separated grouping dimensions. Order matters: it defines the row order and therefore the cursor. Any unknown name is 400 invalid_dimensions. Use month for monthly groups (e.g. month,brand); the breakdown endpoints have no granularity parameter. A shop whose OBS Metrics predates the month dimension answers it with 400 invalid_dimensions.

sort
string
Enum: "views" "cart"

Omit for the pageable mode (dimension order, cursor supported, complete). Set for the ranked mode (measure descending, capped, no cursor).

range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

limit
integer [ 1 .. 10000 ]
Default: 1000

Row limit, clamped server-side to 1..10000. Prefer large pages: every page re-runs the same aggregation, so a few big pages are much cheaper than many small ones.

cursor
string

Opaque keyset cursor from pagination.next_cursor of the previous page. Stateless and non-expiring: it encodes the last row's dimension values plus a fingerprint of the query it belongs to. Replaying it against a different window, different dimensions or different filters is 400 invalid_cursor. Not combinable with sort (400 cursor_not_supported).

with_total
boolean
Default: false

Also return meta.total_rows, the total number of groups in the window ignoring limit and cursor. Off by default because it runs the aggregation a second time.

item_wrapper_id
string

Restrict to one product (the wrapper that groups all variants).

item_id
string

Restrict to one concrete product variant.

brand
string

Restrict to one brand. Exact match on the stored value, as returned by the brand dimension.

category
string

Restrict to one category path. Exact match on the stored value, as returned by the category dimension -- not a prefix match.

traffic_group
string
Enum: "Direct" "Organic" "Paid"

Restrict to one traffic group. Any other value is 400 rest_invalid_param.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    },
  • "meta": {
    }
}

Views and add-to-cart per day or month (UTC days; buckets without data omitted)

One row per UTC calendar day (default) or, with granularity=month, per month built from those UTC days. Month rows carry month instead of day. Unlike sales, tracking months therefore start at 00:00 UTC, not at local midnight. The window is unchanged: at most 548 days.

Authorizations:
BasicAuth
query Parameters
granularity
string
Default: "day"
Enum: "day" "month"

Bucket size of the timeseries rows: day (default) or month. Any other value is 400 invalid_granularity. Not to be confused with the month parameter, which selects a whole month as the window. The window limit stays 548 days for both.

range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Average rating, review count and unanswered share

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

vendor
string
Enum: "obs" "ekomi" "trusted_shops"

Optional review-source filter: obs (this shop), ekomi or trusted_shops. Other values are ignored (= all sources).

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Products with the most published reviews, with average rating Deprecated

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

vendor
string
Enum: "obs" "ekomi" "trusted_shops"

Optional review-source filter: obs (this shop), ekomi or trusted_shops. Other values are ignored (= all sources).

limit
integer [ 1 .. 100 ]
Default: 10

Row limit, clamped server-side to 1..100.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Complete, pageable review aggregates over any combination of dimensions

The general form of reviews/top, and the only way to obtain a rating distribution: dimensions=wrapper,rating answers how many one-star reviews a product has, which an average cannot. vendor and locale are likewise not groupable anywhere else. Published reviews only. Dimensions: day, month, product, wrapper, rating, vendor, locale, brand, category. brand and category are not stored with a review but looked up per product from the imported orders (the product's brand and category as sold, not those of the reviewed order specifically); reviews of a product that appears in no imported order are grouped under an empty brand and category. The brand and category filters therefore only match reviews of products that have been sold in an imported order. A shop whose OBS Metrics is too old for brand and category answers those dimensions with 400 invalid_dimensions and those filters with 409 metrics_required.

Authorizations:
BasicAuth
query Parameters
dimensions
required
string
Example: dimensions=day,product

Comma-separated grouping dimensions. Order matters: it defines the row order and therefore the cursor. Any unknown name is 400 invalid_dimensions. Use month for monthly groups (e.g. month,brand); the breakdown endpoints have no granularity parameter. A shop whose OBS Metrics predates the month dimension answers it with 400 invalid_dimensions.

sort
string
Enum: "reviews" "rating"

Omit for the pageable mode (dimension order, cursor supported, complete). Set for the ranked mode (measure descending, capped, no cursor).

range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

vendor
string
Enum: "obs" "ekomi" "trusted_shops"

Optional review-source filter: obs (this shop), ekomi or trusted_shops. Other values are ignored (= all sources).

limit
integer [ 1 .. 10000 ]
Default: 1000

Row limit, clamped server-side to 1..10000. Prefer large pages: every page re-runs the same aggregation, so a few big pages are much cheaper than many small ones.

cursor
string

Opaque keyset cursor from pagination.next_cursor of the previous page. Stateless and non-expiring: it encodes the last row's dimension values plus a fingerprint of the query it belongs to. Replaying it against a different window, different dimensions or different filters is 400 invalid_cursor. Not combinable with sort (400 cursor_not_supported).

with_total
boolean
Default: false

Also return meta.total_rows, the total number of groups in the window ignoring limit and cursor. Off by default because it runs the aggregation a second time.

item_wrapper_id
string

Restrict to one product (the wrapper that groups all variants).

item_id
string

Restrict to one concrete product variant.

locale
string

Restrict to one review locale.

brand
string

Restrict to one brand. Exact match on the stored value, as returned by the brand dimension.

category
string

Restrict to one category path. Exact match on the stored value, as returned by the category dimension -- not a prefix match.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    },
  • "meta": {
    }
}

Ask service KPIs: volume, status split, response rate and first-response time

Aggregates only (no message content). Inquiries counted by created_at.

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Order-level withdrawal/cancellation requests filed in the period

Reflects requests only (customers asking to withdraw/cancel); dealer/ERP resolution is not available. Local data cannot distinguish withdrawal from cancellation.

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Products ranked by the number of inquiries from their product page

Counts inquiries sent through the Ask block on a product page, created in the period and not deleted; inquiries from other pages, order inquiries and withdrawal requests are not included. Ordered by inquiry_count DESC, ties by item_wrapper_id and variant_id. Returns product IDs and counts only, no message content and no customer data. Inquiries without a selected variant are counted under variant_id null, so a product can appear both with null and with specific variants. meta.inquiry_count is the number of product-page inquiries in the period, meta.unattributed_count how many of them could not be linked to a product (no product reference stored, malformed IDs, or a reference that cannot be decrypted, e.g. after the shop's encryption key changed); these are not ranked. There is no filter for a single product.

Authorizations:
BasicAuth
query Parameters
range
string^\d{1,3}d$
Default: "30d"

X full local days ending yesterday (1..548). Default 30d. Not combinable with month.

end
string <date>

Inclusive last day (YYYY-MM-DD), default yesterday in the shop timezone. Today is allowed but returns the partial current day; a future date is 400 invalid_date. Not combinable with month.

month
string^\d{4}-\d{2}$

Whole calendar month YYYY-MM. Not combinable with range/end (else 400 ambiguous_period). This selects the window; it is unrelated to granularity=month and the month dimension, which split a window into monthly rows.

limit
integer [ 1 .. 100 ]
Default: 10

Row limit, clamped server-side to 1..100.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Products

Get price and availability for spare-part products by MPN

Returns price, tax, stock and availability information for the requested MPNs of a single brand. Used to feed the SPF spare-parts catalogue. The response is keyed by MPN; MPNs without a matching product are omitted. At most 100 MPNs are processed per request.

Authorizations:
BasicAuth
Request Body schema: application/json
required
mpns
required
Array of strings [ 1 .. 100 ] items

The MPNs (manufacturer part numbers) of the products to look up. Duplicate values are ignored. At most 100 MPNs are processed per request.

brand
required
string non-empty

The brand the requested products belong to

Responses

Request samples

Content type
application/json
{
  • "mpns": [
    ],
  • "brand": "KTM"
}

Response samples

Content type
application/json
{
  • "93503001000": {
    },
  • "93505088000": {
    },
  • "61430018000": {
    }
}