API docs by Redocly

OBS Public API (1.3.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. 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).

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

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

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": {
    }
}

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

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

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

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

One row per local day with data (days without orders are omitted).

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

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

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

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

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

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": {
    }
}

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

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

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

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

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

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": {
    }
}

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

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

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": {
    }
}