Volume Discounts
Introduction
A volume discount is a tiered quantity discount on one product (id_product) on one storefront: when a buyer purchases at least a given number of units, each unit gets a percentage or a fixed amount off. A volume discount has 1 to 5 thresholds, and a higher threshold grants a higher discount.
A volume discount applies to all of your units of that product on the storefront. It has a start date and an optional end date, and every threshold reports its own sales statistics.
Volume Discount Lifecycle
Every volume discount has a status field that reflects its current point in the lifecycle. Some transitions are triggered by you through PATCH /volume-discounts, others happen automatically: the system checks volume discounts periodically, so an automatic transition can take a few minutes after the date is reached.
Statuses
| Status | Meaning | How it is reached |
|---|---|---|
new |
The volume discount has been created and is not applied to orders yet. | Every volume discount is created with this status. |
active |
The volume discount is applied to orders. | Automatically when start_date is reached (and end_date has not passed). You can also activate a new volume discount early, or reactivate an inactive one. |
inactive |
You have deactivated the volume discount. It is not applied to orders. | You deactivate an active volume discount. |
completed |
The volume discount has ended. This is a terminal state. | Automatically after end_date has passed, from new, active or inactive. |
overwritten |
A newer volume discount for the same product and storefront replaced this one. This is a terminal state. | Automatically, when another volume discount for the same product and storefront becomes active and their validity periods overlap. Only an active volume discount can be overwritten; the one that became active stays active. |
deleted |
The volume discount has been removed. This is a terminal state. Deleted volume discounts are never returned by GET /volume-discounts; the status only appears in the PATCH /volume-discounts response. |
You delete a new volume discount, or deactivate one that is still new. |
unknown |
Returned only if the backend reports a status this API version does not know yet. Treat it as forward-compatible and do not rely on it. It is not a filter value. | – |
Status changes you can request
| Target status | Allowed from | Note |
|---|---|---|
active |
new, inactive |
– |
inactive |
active |
Volume discounts that are still new are deleted instead. |
deleted |
new |
– |
Endpoint Reference
The following endpoints allow you to create, list and change the status of your volume discounts.
Create Volume Discounts
To create volume discounts, send a POST request to /volume-discounts with 1 to 500 volume discounts. Each entry describes one product on one storefront, identified by either id_product or ean.
201.
Request fields
| Field | Required | Allowed values / format | Notes |
|---|---|---|---|
volume_discounts |
Yes | Array, 1–500 entries | Each entry is one volume discount for one product on one storefront. |
volume_discounts[].storefront |
Yes | Any currently-supported storefront code (see Storefronts and Locales). | |
volume_discounts[].id_product |
Exactly one of id_product or ean |
Positive integer | All entries in one request must use the same identifier: either all id_product or all ean. |
volume_discounts[].ean |
Exactly one of id_product or ean |
Non-empty string | Must resolve to one of your products. An EAN that cannot be resolved returns 422. |
volume_discounts[].discount_type |
Yes | PERCENTAGE, ABSOLUTE |
Applies to every threshold of the entry. |
volume_discounts[].start_date |
Yes | YYYY-MM-DD |
Today or later (Europe/Berlin). |
volume_discounts[].end_date |
No | YYYY-MM-DD or null |
Must be after start_date. Omit it or send null for a volume discount without an end date. |
volume_discounts[].thresholds |
Yes | Array, 1–5 entries | Can be sent in any order. See the threshold rules below. |
thresholds[].quantity |
Yes | Integer, 1–100 | Minimum number of units a buyer has to purchase to get this threshold's discount. |
thresholds[].discount_value |
Yes | Integer | For PERCENTAGE: 2–85 (percent off per unit). For ABSOLUTE: amount off per unit in the minor currency unit (e.g. cents), at least 50; on pl at least 200, on cz at least 1200. |
Threshold rules
- The lowest
quantityis at most25. - After sorting the thresholds by
quantity, bothquantityanddiscount_valuestrictly increase: no two thresholds share a quantity, and a higher quantity always grants a higher discount.
Example Request
{
"volume_discounts": [
{
"storefront": "de",
"id_product": 306215652,
"discount_type": "PERCENTAGE",
"start_date": "2026-12-01",
"end_date": "2026-12-31",
"thresholds": [{ "quantity": 3, "discount_value": 5 }]
}
]
}
Example Response (201 Created)
{
"data": [
{
// server-assigned ID; use it to address the volume discount in PATCH /volume-discounts
"id_volume_discount": 4,
"storefront": "de",
// every volume discount is created as new
"status": "new",
"discount_type": "PERCENTAGE",
"id_product": 306215652,
"start_date": "2026-12-01",
"end_date": "2026-12-31",
"created_at": "2026-01-01T12:14:21Z",
"updated_at": "2026-01-01T12:14:21Z",
"thresholds": [
{
"quantity": 3,
"discount_value": 5,
// statistics start at 0
"total_sales": 0,
"conversions": 0,
"utilization_rate": 0
}
]
}
]
}
data is empty; fetch them with GET /volume-discounts.
POST /volume-discounts — Possible Errors
| HTTP Status | Problem Type | When | Next steps |
|---|---|---|---|
| 400 Bad Request | /problems/validation-error |
The request body is invalid, e.g. a field is missing or out of range, id_product and ean are mixed, start_date is in the past, or the thresholds break the threshold rules. |
Check the errors array in the response body; each entry describes one invalid field. |
| 401 Unauthorized | /problems/unauthorized |
Authentication headers are missing or the request signature is invalid. Authentication failures may also return invalid-credentials, corrupted-signature, inactive-account or missing-or-invalid-request-header; see the authentication documentation. |
Ensure the request is correctly signed. |
| 422 Unprocessable Content | /problems/volume-discounts/unresolvable-eans |
An ean could not be resolved to one of your products. |
Check the message field for the EANs that failed to resolve, and verify they are valid and belong to your account. |
| 422 Unprocessable Content | /problems/validation-error |
The backend rejected an entry. | Check the errors array for the reasons, correct the entries and send the request again. |
| 500 Internal Server Error | /problems/server-error |
An unexpected error occurred on the server side. | Contact support if the issue persists. |
| 503 Service Unavailable | /problems/service-unavailable |
The volume discount service or the EAN resolution is temporarily unavailable. | Retry the request after a brief delay. Contact support if the issue persists. |
Get Volume Discounts List
Use GET /volume-discounts to retrieve a paginated list of your volume discounts. All query parameters are optional.
Query parameters
| Parameter | Allowed values / format | Notes |
|---|---|---|
storefront |
Storefront code, repeatable | Pass the parameter multiple times to filter by several storefronts (e.g. ?storefront=de&storefront=cz). When omitted, volume discounts across all storefronts are returned. |
status |
new, active, inactive, completed, overwritten; repeatable |
Pass the parameter multiple times to filter by several statuses (e.g. ?status=new&status=active). When omitted, volume discounts of all these statuses are returned. Deleted volume discounts are never returned. |
id_product |
Positive integer, repeatable | Filter by one or more products. Cannot be combined with ean. |
ean |
Non-empty string, repeatable | Filter by one or more products identified by EAN. Cannot be combined with id_product. Every EAN must resolve to one of your products; otherwise 422 is returned. |
start_date |
YYYY-MM-DD |
Return only volume discounts whose validity period overlaps the given period. An open-ended volume discount overlaps every period that ends on or after its start date. start_date must not be after end_date. |
end_date |
YYYY-MM-DD |
|
sort |
field:direction |
field is one of start_date, end_date, conversions, total_sales, utilization_rate; direction is asc or desc (e.g. ?sort=conversions:desc). |
offset |
Integer ≥ 0, default 0 |
Number of volume discounts to skip. Must be a multiple of limit. |
limit |
Integer 1–100, default 30 |
Number of volume discounts per page. |
Response fields
| Field | Description |
|---|---|
id_volume_discount |
ID of the volume discount. |
storefront |
Storefront of the volume discount. |
status |
Lifecycle status; see Volume Discount Lifecycle. |
discount_type |
PERCENTAGE or ABSOLUTE. |
id_product |
The product the volume discount applies to. |
start_date |
First day the volume discount is valid, YYYY-MM-DD (Europe/Berlin). |
end_date |
Last day the volume discount is valid, YYYY-MM-DD (Europe/Berlin). null for an open-ended volume discount. |
created_at |
ISO 8601 timestamp (UTC) of when the volume discount was created. |
updated_at |
ISO 8601 timestamp (UTC) of the last change to the volume discount. |
thresholds[].quantity |
Minimum number of units a buyer has to purchase to get this threshold's discount. |
thresholds[].discount_value |
Discount granted at this threshold: a percentage for PERCENTAGE, or an amount in the storefront's minor currency unit (cents) for ABSOLUTE. |
thresholds[].total_sales |
Integer. Revenue from this threshold's conversions: the sum of units × price paid per unit after the discount was applied, in the storefront's minor currency unit (cents). |
thresholds[].conversions |
Integer. Number of order units bought at this threshold, i.e. that reached its quantity and got its discount. |
thresholds[].utilization_rate |
Float between 0 and 1 (0.18 means 18%). Share of all order units checked out with this volume discount attached that landed on this threshold, including those that bought too few units to reach any threshold. |
The threshold statistics are 0 when nothing has been sold at the threshold yet.
Example Response
{
"data": [
{
"id_volume_discount": 4,
"storefront": "de",
"status": "active",
"discount_type": "PERCENTAGE",
"id_product": 306215652,
"start_date": "2026-01-01",
"end_date": "2026-01-31",
"created_at": "2026-01-01T12:14:21Z",
"updated_at": "2026-01-05T08:02:11Z",
"thresholds": [
{
"quantity": 3,
"discount_value": 5,
"total_sales": 12000,
"conversions": 24,
"utilization_rate": 0.18
},
{
"quantity": 10,
"discount_value": 12,
"total_sales": 4500,
"conversions": 3,
"utilization_rate": 0.02
}
]
}
],
"pagination": {
"offset": 0,
"limit": 30,
"total": 1
}
}
GET /volume-discounts — Possible Errors
| HTTP Status | Problem Type | When | Next steps |
|---|---|---|---|
| 400 Bad Request | /problems/validation-error |
One or more query parameters are invalid, e.g. an unknown status, id_product combined with ean, an unsupported sort, or an offset that is not a multiple of limit. |
Check the errors array in the response body; each entry describes one invalid parameter. |
| 401 Unauthorized | /problems/unauthorized |
Authentication headers are missing or the request signature is invalid. Authentication failures may also return invalid-credentials, corrupted-signature, inactive-account or missing-or-invalid-request-header; see the authentication documentation. |
Ensure the request is correctly signed. |
| 422 Unprocessable Content | /problems/volume-discounts/unresolvable-eans |
An ean could not be resolved to one of your products. |
Check the message field for the EANs that failed to resolve, and verify they are valid and belong to your account. |
| 500 Internal Server Error | /problems/server-error |
An unexpected error occurred on the server side. | Contact support if the issue persists. |
| 503 Service Unavailable | /problems/service-unavailable |
The volume discount service or the EAN resolution is temporarily unavailable. | Retry the request after a brief delay. Contact support if the issue persists. |
Change Volume Discount Status
Use PATCH /volume-discounts to activate, deactivate or delete up to 2000 volume discounts at once. Which status changes are allowed is described in the lifecycle.
Request fields
| Field | Required | Allowed values / format | Notes |
|---|---|---|---|
storefront |
No | Any currently-supported storefront code (see Storefronts and Locales). | Limits the change to one storefront. When omitted, volume discounts on every storefront are changed. |
status |
Yes | active, inactive, deleted |
Target status for every item. |
items |
Yes | Array, 1–2000 entries | Each item has exactly one of id_volume_discount, id_product or ean, and all items use the same identifier. |
items[].id_volume_discount |
One identifier per item | Positive integer | Changes this volume discount. |
items[].id_product |
One identifier per item | Positive integer | Changes all volume discounts of this product. |
items[].ean |
One identifier per item | Non-empty string | Changes all volume discounts of the product with this EAN. Must resolve to one of your products. |
status: "inactive", volume discounts that are still new are deleted, not deactivated.
Partial success
Volume discounts that do not exist, belong to another seller, or cannot move to the target status are skipped, not rejected. The response status tells you whether anything was skipped:
200 OK: every identifier changed at least one volume discount.207 Multi-Status: some identifiers changed nothing (summary.succeededis less thansummary.total). The body has the same shape as for200.
The response body:
itemshas one entry per product with at least one changed volume discount. Itsdata.volume_discountslists those volume discounts with their new status. Products where nothing changed are not listed.summary.totalis the number of distinct identifiers in the request. EANs are counted after they are resolved, so several EANs of the same product count once.summary.succeededis the number of identifiers with at least one changed volume discount.
Example Request
{
"status": "inactive",
"items": [{ "id_volume_discount": 4 }]
}
Example Response
{
"data": {
"items": [
{
"id_product": 306215652,
"data": {
"volume_discounts": [
{
"id_volume_discount": 4,
"storefront": "de",
// status after the change; deleted is possible here
"status": "inactive"
}
]
}
}
],
"summary": {
"total": 1,
"succeeded": 1
}
}
}
PATCH /volume-discounts — Possible Errors
| HTTP Status | Problem Type | When | Next steps |
|---|---|---|---|
| 400 Bad Request | /problems/validation-error |
The request body is invalid, e.g. an unknown status, an item with no or several identifiers, or identifiers mixed across items. |
Check the errors array in the response body; each entry describes one invalid field. |
| 401 Unauthorized | /problems/unauthorized |
Authentication headers are missing or the request signature is invalid. Authentication failures may also return invalid-credentials, corrupted-signature, inactive-account or missing-or-invalid-request-header; see the authentication documentation. |
Ensure the request is correctly signed. |
| 422 Unprocessable Content | /problems/volume-discounts/unresolvable-eans |
With ean items: an ean could not be resolved to one of your products. |
Check the message field for the EANs that failed to resolve, and verify they are valid and belong to your account. |
| 422 Unprocessable Content | /problems/validation-error |
The backend rejected the request. | Check the errors array for the reasons, correct the request and send it again. |
| 500 Internal Server Error | /problems/server-error |
An unexpected error occurred on the server side. | Contact support if the issue persists. |
| 503 Service Unavailable | /problems/service-unavailable |
The volume discount service or the EAN resolution is temporarily unavailable. | Retry the request after a brief delay. Contact support if the issue persists. |