Vouchers

Introduction

The Vouchers API allows you to create and manage discount vouchers for your products on the Kaufland marketplace. Vouchers give buyers a monetary or percentage discount on selected items, helping you increase visibility and drive sales.

Each voucher is tied to a specific storefront and a set of your product listings. You control the discount type, amount, validity period, and the number of times the voucher can be used.

Prerequisites

Before you can create vouchers, you must accept the Voucher Terms and Conditions for each storefront you want to use. You can check your current acceptance status, storefront eligibility and voucher pricing via the Seller Portal

Voucher Lifecycle

Every voucher has a status field that reflects its current point in the lifecycle. Some transitions are triggered by seller actions, others happen automatically based on time or redemption activity. Knowing the current status is important because most write operations are only permitted in specific states.

Statuses

Performance Metrics

The voucher and voucher-product responses include two performance metrics that are referenced throughout this page. They are also available as sort fields on the list endpoints.

• acos — Advertising Cost of Sales, expressed as a percentage. Computed as (voucher_fee / total_sales) * 100. Lower values indicate a more cost-efficient voucher.
• roas — Return on Ad Spend, expressed as a ratio. Computed as total_sales / voucher_fee. Higher values indicate a higher return per unit of voucher cost.

Both metrics are 0 when no sales have been generated through the voucher. On GET /vouchers/{id_voucher}/products the same formulas are applied per product (using that product's voucher fee and total sales).

Endpoint Reference

The following endpoints allow sellers to retrieve and manage vouchers.

Create Voucher

To create a new voucher, send a POST request to /vouchers. You must specify the discount type and amount, the validity period, the storefront, and either a list of product IDs or EANs the voucher applies to.

The discount_type can be PERCENTAGE or ABSOLUTE. For absolute discounts, provide the value in cents (e.g. 100 = 1 euro). The usage_limit defines the maximum number of redemptions across all participating products.

Request fields

Example Request

{
    "title": "Christmas Sale",
    "storefront": "de",
    "discount_type": "PERCENTAGE",
    "discount_amount": 10,
    "begin_at": "2025-12-16",
    "end_at": "2025-12-20",
    "usage_limit": 100,
    "products": [306215652, 533036228],
    "eans": ["4006381333931"],
    "export_to_third_parties": false
}

Example Response

{
    "data": {
        // server-assigned unique voucher ID; use it to address the voucher in subsequent /vouchers/{id_voucher}* calls
        "id_voucher": 4,
        "title": "Christmas Sale",
        // lifecycle state: new | active | inactive | expired | consumed | deleted
        "status": "new",
        "storefront": "de",
        // PERCENTAGE or ABSOLUTE
        "discount_type": "PERCENTAGE",
        // for PERCENTAGE: integer 1–85 (percent off). For ABSOLUTE: amount in cents
        "discount_amount": 10,
        "begin_at": "2025-12-16",
        "end_at": "2025-12-20",
        // server-set creation timestamp (YYYY-MM-DD)
        "created_at": "2025-12-16",
        "usage_limit": 100,
        // whether the voucher is shared with third-party price-comparison portals (e.g. idealo, Google Shopping)
        "export_to_third_parties": false
    }
}

POST /vouchers — Possible Errors

Get Vouchers List

Use GET /vouchers to retrieve a paginated list of your vouchers. All query parameters are optional.

You can filter by one or more storefronts by passing storefront multiple times (e.g. ?storefront=de&storefront=cz). When omitted, vouchers across all storefronts are returned. Results can also be filtered by one or more status values (new, active, inactive, expired, consumed, deleted) — pass status multiple times to filter by several statuses (e.g. ?status=active&status=new). When omitted, vouchers of all statuses are returned. You can also filter by campaign name or ID using search_term, and sort results with sort=field:direction (e.g. ?sort=redemptions:desc).

To find vouchers that apply to a specific product, use id_product — pass the parameter multiple times to filter by several products (e.g. ?id_product=123&id_product=456). Alternatively, use ean to filter by EAN (e.g. ?ean=4006381333931&ean=4006381333948). Both parameters can be combined. When neither is provided, vouchers for all products are returned.

Use offset (number of vouchers to skip, default 0) and limit (1–100, default 30) to paginate through results.

Query parameters

Example Response

{
    "data": [
        {
            "id_voucher": 4,
            "title": "Christmas Sale",
            // lifecycle state: new | active | inactive | expired | consumed | deleted
            "status": "new",
            "storefront": "de",
            // PERCENTAGE or ABSOLUTE
            "discount_type": "PERCENTAGE",
            // for PERCENTAGE: integer 1–85. For ABSOLUTE: amount in cents
            "discount_amount": 10,
            "begin_at": "2025-12-16",
            "end_at": "2025-12-20",
            // server-set creation timestamp (YYYY-MM-DD)
            "created_at": "2025-12-16",
            "usage_limit": 100,
            "export_to_third_parties": false,
            // total redemptions across every product attached to this voucher
            "number_of_redeemed_vouchers": 0,
            // total fee paid by the seller for this voucher (in cents)
            "voucher_fee": 0,
            // total revenue generated through this voucher (in cents)
            "total_sales": 0,
            // see Performance Metrics
            "acos": 0,
            // see Performance Metrics
            "roas": 0,
            // number of products currently attached to the voucher
            "products_count": 2
        }
    ],
    // pagination cursor; total is the count of vouchers matching the filters, not the page size
    "pagination": {
        "offset": 0,
        "limit": 30,
        "total": 200
    }
}

GET /vouchers — Possible Errors

Get Voucher

To retrieve the full details and performance statistics of a specific voucher, use GET /vouchers/{id_voucher}. This endpoint returns voucher metadata only. To retrieve the associated products, use GET /vouchers/{id_voucher}/products.

Example Response

{
    "data": {
        "id_voucher": 4,
        "title": "Christmas Sale",
        // lifecycle state: new | active | inactive | expired | consumed | deleted
        "status": "new",
        "storefront": "de",
        // PERCENTAGE or ABSOLUTE
        "discount_type": "PERCENTAGE",
        // for PERCENTAGE: integer 1–85. For ABSOLUTE: amount in cents
        "discount_amount": 10,
        "begin_at": "2025-12-16",
        "end_at": "2025-12-20",
        // server-set creation timestamp (YYYY-MM-DD)
        "created_at": "2025-12-16",
        "usage_limit": 100,
        // total redemptions across every product attached to this voucher
        "number_of_redeemed_vouchers": 42,
        // total fee paid by the seller for this voucher (in cents)
        "voucher_fee": 5,
        // total revenue generated through this voucher (in cents)
        "total_sales": 1500,
        // see Performance Metrics
        "acos": 1.25,
        // see Performance Metrics
        "roas": 3.75,
        "export_to_third_parties": false
    }
}

GET /vouchers/{id_voucher} — Possible Errors

Get Voucher Products

To retrieve the paginated list of products associated with a specific voucher, use GET /vouchers/{id_voucher}/products. Use offset and limit to page through results. limit must be between 1 and 100 (default: 30). Results can be filtered by one or more product IDs using id_product — pass the parameter multiple times to filter by several products (e.g. ?id_product=111&id_product=222). Results can be sorted with sort=field:direction (e.g. ?sort=redemptions:desc). Allowed fields: redemptions, acos, roas. Allowed directions: asc, desc.

Each entry in the response carries the acos and roas metrics, computed per product. See Performance Metrics for the definitions and formulas.

Query parameters

Example Response

{
    "data": [
        // each entry: id_product (item ID), acos (see Performance Metrics),
        // roas (see Performance Metrics), number_of_redeemed_vouchers (redemptions on this product only)
        { "id_product": 306215652, "acos": 0.8, "roas": 4.1, "number_of_redeemed_vouchers": 12 },
        { "id_product": 533036228, "acos": 0, "roas": 0, "number_of_redeemed_vouchers": 0 }
    ],
    // pagination cursor; total is the count of products attached to the voucher matching the filters
    "pagination": {
        "offset": 0,
        "limit": 30,
        "total": 2
    }
}

GET /vouchers/{id_voucher}/products — Possible Errors

Deactivate Voucher

To deactivate a list of vouchers and make them no longer visible to customers, send a PATCH request to /vouchers with a JSON body containing the voucher IDs and "status": "inactive". The voucher's status will be updated to inactive, and the updated vouchers will be returned in the response.

Request fields

Example Request

{
    "ids": [4],
    "status": "inactive"
}

Example Response

{
    "data": [
        {
            "id_voucher": 4,
            "title": "Christmas Sale",
            // updated to `inactive` after a successful deactivation
            "status": "inactive",
            "storefront": "de",
            // PERCENTAGE or ABSOLUTE
            "discount_type": "PERCENTAGE",
            // for PERCENTAGE: integer 1–85. For ABSOLUTE: amount in cents
            "discount_amount": 10,
            "begin_at": "2025-12-16",
            "end_at": "2025-12-20",
            // server-set creation timestamp (YYYY-MM-DD)
            "created_at": "2025-12-16",
            "usage_limit": 100,
            "export_to_third_parties": false,
            // total redemptions across every product attached to this voucher
            "number_of_redeemed_vouchers": 0,
            // total fee paid by the seller for this voucher (in cents)
            "voucher_fee": 0,
            // total revenue generated through this voucher (in cents)
            "total_sales": 0,
            // see Performance Metrics
            "acos": 0,
            // see Performance Metrics
            "roas": 0,
            // number of products currently attached to the voucher
            "products_count": 2
        }
    ]
}

PATCH /vouchers — Possible Errors

Delete Vouchers

To permanently remove one or more vouchers, send a DELETE request to /vouchers with the voucher IDs passed as repeated id query parameters (e.g. ?id=1&id=2&id=3). A successful deletion returns HTTP 204 with no response body.

Query parameters

Example Request

DELETE /vouchers?id=1&id=2&id=3

Example Response

HTTP 204 No Content

DELETE /vouchers — Possible Errors

Full endpoint documentation including all parameters and error codes is available under Vouchers.