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.

Volume discount lifecycle state diagram State diagram showing transitions between volume discount statuses (new, active, inactive, overwritten, completed, deleted) and whether each transition is triggered by a seller action or by the system. end_date passed start_date reached activate overlapping activation delete or deactivate deactivate activate end_date passed end_date passed new active overwritten deleted inactive completed seller action system (time-based or event)

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 –
Note: A requested status change that is not allowed from the current status is skipped; see partial success.

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.

All or nothing. If one entry is invalid, the whole request fails and no volume discount is created. On success the response status is 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 quantity is at most 25.
  • After sorting the thresholds by quantity, both quantity and discount_value strictly 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
                }
            ]
        }
    ]
}
Note: Creation is all or nothing. In rare cases the volume discounts are created but cannot be returned, and 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.
Note: With 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.succeeded is less than summary.total). The body has the same shape as for 200.

The response body:

  • items has one entry per product with at least one changed volume discount. Its data.volume_discounts lists those volume discounts with their new status. Products where nothing changed are not listed.
  • summary.total is 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.succeeded is 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.