API reference vouchers - WEBSALE Dokumentation

The vouchers/ endpoint provides you with an interface for managing vouchers in our shop system. With this interface, you can create, delete, and view vouchers as well as manage voucher charges, blueprints, and presets. The following sections first describe the data fields and then the methods, which are organized by vouchers, charges, blueprints, and presets.

Supported methods

List of all supported methods.

Command/info	Endpoints	GET	PUT	POST	DELETE
Vouchers	vouchers/
Vouchers (bulk)	vouchers/bulk
Voucher charges	vouchers/charges/
Voucher blueprints	vouchers/templates/
Voucher presets	vouchers/presets/

Data fields

Data fields of a voucher

Name	Type	Meaning
active	Boolean	Indicates whether the voucher is active (true = active, false = deactivated).
chargeId	String	ID of the charge to which the voucher belongs.
createdAt	String	Time of creation of the voucher.
id	String	Unique ID of the voucher.
labels	String[]	Tags or labels for grouping or identifying the voucher (e.g. marketing campaigns).
maxUseCount	Integer	Maximum number of redemptions before the voucher is deactivated.
pool	Boolean	Indicates whether the voucher is part of a pool (shared contingent).
types.appOnly	Boolean	Voucher can only be redeemed via the app.
types.discount	Boolean	Promotional voucher / purchase voucher
types.freeShipping	Boolean	Voucher grants free shipping.
types.keepSurplus	Boolean	Remaining residual value may be kept and redeemed again later.
types.multipleCustomer	Boolean	Voucher can be redeemed multiple times by different customers.
types.newCustomersOnly	Boolean	Voucher may only be used by new customers.
types.existingCustomersOnly	Boolean	Voucher may only be used by existing customers. Cannot be set together with `types.newCustomersOnly`.
types.maxUseCountSet	Boolean	Voucher is limited per user.
types.maxUseCountPerUser	Integer	Maximum number of redemptions per user
updatedAt	String	Time of the last update of the voucher.
validFrom	String	Start of the voucher’s validity.
validUntil	String	End of the voucher’s validity.
validCustomers[].id	Integer	ID of a customer authorized to redeem the voucher.
validCustomers[].number	String	Customer number of an authorized customer.
invalidCustomers[].id	Integer	ID of a customer who is not allowed to redeem the voucher.
invalidCustomers[].number	String	Customer number of a customer who is not allowed to redeem the voucher.
validCategories[].id	String	ID of a category for which the voucher is valid.
validCategories[].includeSubcategories	Boolean	Indicates whether the subcategories of the category are included.
invalidCategories[].id	String	ID of a category for which the voucher is not valid.
invalidCategories[].includeSubcategories	Boolean	Indicates whether the subcategories of the category are excluded.
validProducts[].id	String	ID of the product for which the voucher is valid.
validProducts[].number	String	Product number for which the voucher is valid.
validProducts[].quantity	Integer	Minimum quantity of the product in the basket so that the voucher applies.
validSubshops[]	String[]	List of subshop IDs in which the voucher is valid.
invalidSubshops[]	String[]	List of subshop IDs in which the voucher is not valid.
values[].currency	String	Currency code (e.g. EUR, GBP) for which the respective value applies.
values[].percentValue	Float	Percentage discount (e.g. 0.1 for 10%).
values[].taxId	String	Tax ID applied to the voucher value.
values[].usedValue	Float	Already redeemed value of the voucher (for multiple use).
values[].value	Float	Total value of the voucher in the respective currency.
values[].minOrderValue	Float	Minimum order value in the currency required to redeem the voucher.
values[].maxDiscountValue	Float	Maximum discount amount in the currency for a percentage discount.

Example

{
    "active": true,
    "chargeId": "example-charge",
    "createdAt": "2025-01-17T07:57:26.000Z",
    "id": "VOUCHER-XY57Z3",
    "labels": [
        "summer2025"
    ],
    "maxUseCount": 5,
    "pool": false,
    "types": {
        "appOnly": false,
        "discount": false,
        "freeShipping": false,
        "keepSurplus": true,
        "multipleCustomer": false,
        "newCustomersOnly": false,
        "maxUseCountPerUser": 122,
        "maxUseCountSet": true
    },
    "updatedAt": "2025-01-17T07:57:26.000Z",
    "validCustomers": [
        {
            "id": 48
        },
        {
            "number": "1234"
        }
    ],
    "validProducts": [
        {
            "number": "go1",
            "quantity": 1
        }
    ],
    "validSubshops": [
        "deutsch"
    ],
    "values": [
        {
            "currency": "EUR",
            "percentValue": 0.0,
            "taxId": "",
            "usedValue": 10.0,
            "value": 42.0
        },
        {
            "currency": "GBP",
            "minOrderValue": 50.0,
            "percentValue": 0.0,
            "taxId": "",
            "value": 10.0
        }
    ]
}

Data fields of a voucher charge

Name	Type	Meaning
createdAt	String	Time of creation of the voucher charge (ISO 8601 format, UTC).
creator	Integer	ID of the user who created the charge.
description	String	Free-text description of the voucher charge.
id	String	Unique ID of the voucher charge.
name	String	Name of the voucher charge.
redeemed	Integer	Indicates whether vouchers of the charge have been redeemed. Possible values: `0 = NotRedeemed` `1 = PartiallyRedeemed` `2 = Redeemed`
updatedAt	String	Time of the last update of the charge (ISO 8601 format, UTC).
voucherChargeCount	Integer	Number of vouchers created with this charge.
voucherData	Object	Details about vouchers. All fields match the fields of vouchers.

Example

{
    "createdAt": "2025-04-11T13:25:53.000Z",
    "creator": 1,
    "description": "",
    "id": "82",
    "name": "myCharge",
    "redeemed": 0,
    "updatedAt": "2025-04-11T13:25:53.000Z",
    "voucherChargeCount": 1,
    "voucherData": {
        "labels": [
            "82"
        ],
        "maxUseCount": 999,
        "pool": false,
        "types": {
            "appOnly": false,
            "discount": true,
            "freeShipping": true,
            "keepSurplus": false,
            "maxUseCountSet": false,
            "multipleCustomer": true,
            "newCustomersOnly": false
        },
        "validProducts": [
            {
                "id": "100-41232",
                "quantity": 1
            }
        ],
        "values": [
            {
                "currency": "EUR",
                "minOrderValue": 1,
                "percentValue": 0,
                "taxId": "19",
                "usedValue": 0,
                "value": 55
            }
        ]
    }
}

Data fields of a voucher blueprint

Name	Type	Meaning
active (optional)	Boolean	Indicates whether the blueprint is active.
createdAt	String	Time at which the blueprint was created (ISO 8601 format, UTC).
templateId	String	Technical ID or unique name of the voucher blueprint.
updatedAt	String	Time of the last update of the blueprint (ISO 8601 format, UTC).
validFrom (optional)	String	Start of validity.
validUntil (optional)	String	End of validity.

Further fields match the fields of vouchers.

Example

{
    "active": true,
    "chargeId": "53",
    "createdAt": "2025-04-09T08:57:59.000Z",
    "labels": [],
    "templateId": "newTemplateName2",
    "types": {
        "appOnly": false,
        "discount": false,
        "freeShipping": false,
        "keepSurplus": false,
        "maxUseCountSet": false,
        "multipleCustomer": false,
        "newCustomersOnly": false
    },
    "updatedAt": "2025-04-29T08:48:39.000Z",
    "values": [
        {
            "currency": "EUR",
            "minOrderValue": 10,
            "percentValue": 0,
            "taxId": "",
            "value": 1
        }
    ]
}

Data fields of a voucher preset

Name	Type	Meaning
createdAt	String	Time at which the preset was created (ISO 8601 format, UTC).
updatedAt	String	Time of the last update of the preset (ISO 8601 format, UTC).
presetId	String	Technical ID or unique name of the voucher preset.
system	Boolean	Indicates whether the preset was provided by Websale. Not all fields can be edited in such presets.
data.count	Integer	Number of vouchers
data.data	Object	Details about the voucher. All fields match the fields of vouchers.

Example

{
    "createdAt": "1970-01-01T00:33:45.000Z",
    "data": {
        "count": 1,
        "data": {
            "active": true,
            "basketProducts": [],
            "chargeId": "",
            "labels": [],
            "maxUseCount": 19,
            "name": "myPreset",
            "types": {
                "appOnly": false,
                "discount": true,
                "freeShipping": false,
                "keepSurplus": false,
                "maxUseCountSet": false,
                "multipleCustomer": true
            },
            "values": [
                {
                    "currency": "GBP",
                    "minOrderValue": 40,
                    "taxId": "19",
                    "value": 20
                }
            ]
        }
    },
    "presetId": "myPreset",
    "system": false,
    "updatedAt": "1970-01-01T00:33:45.000Z"
}

Methods for managing vouchers

This section describes all endpoints for managing individual vouchers. Through the interface, vouchers can be created, deleted, and retrieved. Updating individual vouchers is planned for a future version. The management of voucher charges is handled in a separate section. For all operations, corresponding read, write, create, or delete permissions are required.

GET vouchers

This method returns a paginated list of all vouchers present in the system. Filter and sort parameters can be used to specifically restrict and order the results. The returned voucher data includes information on activity, validity, redemption conditions, and value specifications. Read permissions are required for access.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers?size=100

Response

{
    "endReached": true,
    "items": [
        {
            "active": true,
            "chargeId": "example-charge",
            "createdAt": "2025-01-17T07:57:26.000Z",
            "id": "VOUCHER-XY57Z3",
            "labels": [
                "summer2025"
            ],
            "maxUseCount": 5,
            "pool": false,
            "types": {
                "appOnly": false,
                "discount": false,
                "freeShipping": false,
                "keepSurplus": true,
                "multipleCustomer": false,
                "newCustomersOnly": false,
                "maxUseCountSet": false
            },
            "updatedAt": "2025-01-17T07:57:26.000Z",
            "validCustomers": [
                {
                    "id": 48
                },
                {
                    "number": "1234"
                }
            ],
            "validProducts": [
                {
                    "number": "go1",
                    "quantity": 1
                }
            ],
            "validSubshops": [
                "deutsch"
            ],
            "values": [
                {
                    "currency": "EUR",
                    "percentValue": 0.0,
                    "taxId": "",
                    "usedValue": 10.0,
                    "value": 42.0
                },
                {
                    "currency": "GBP",
                    "minOrderValue": 50.0,
                    "percentValue": 0.0,
                    "taxId": "",
                    "value": 10.0
                }
            ]
        }
    ],
    "nextPageToken": "Mw",
    "totalCount": 1
}

Filter fields

id, active, pool, chargeId, createdAt, updatedAt, validFrom, validUntil, maxUseCount

Sort fields

id, active, pool, chargeId, createdAt, updatedAt, validFrom, validUntil, maxUseCount

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read voucher data.
400 Bad Request	”invalidValue”
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:”.

PUT vouchers/{id} - Coming soon

This method updates the properties of an existing voucher by its unique ID. Through the request body, various fields such as activation status, validity periods, values, or redemption conditions can be changed. On successful update, a confirmation is returned. Write permissions for voucher data are required.

This method is not yet implemented and is planned for a future version.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/1CUA-8341-FD8Q-KPJ2

Response

{
    "updateVoucher": "not implemented"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write voucher data.

POST vouchers

This method creates one or more new vouchers. The vouchers can either be assigned to a new charge or appended to an existing charge. For a new charge to be created, the chargeId field in the request body must be empty. The shop does not automatically extend an existing charge. Vouchers are only appended to an existing charge if you explicitly request this. To do so, specify the query parameter appendToCharge and pass the chargeId of the charge in the request body. The parameter itself does not require a value. If appendToCharge is missing and the chargeId is already in use, the shop rejects the request with duplicateEntry. The existing charge then remains unchanged. When appending, the new vouchers must have the same type as the existing charge. A maximum of 10,000 vouchers can be created per request. The count parameter is optional and has the default value 1. All products, categories, and customers named in the validity rules must exist in the shop. On successful creation, the associated charge ID and the number of created vouchers are returned. Create permissions for voucher data are required.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers

Request body

{
    "count": 1,
    "data": {
        "active": true,
        "name": "cvcv89",
        "chargeId": "",
        "maxUseCount": 1,
        "values": [
            {
                "value": 55,
                "currency": "GBP",
                "minOrderValue": 55,
                "taxId": ""
            }
        ],
        "types": {
            "keepSurplus": false,
            "discount": true,
            "freeShipping": false,
            "maxUseCountPerUser": 1,
            "maxUseCountSet": true,
            "multipleCustomer": true,
            "appOnly": false
        },
        "basketProducts": [],
        "labels": []
    }
}

Response

{
    "success": true,
    "chargeId": "122",
    "count": 1
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create voucher data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidFormat”	`count` is not a number. `data` is not an object.
400 Bad Request	”missing”	`data` is missing. `appendToCharge` is set, and `chargeId` is missing.
400 Bad Request	”invalidValue”	`count` ∉ [1;10000] `appendToCharge` is set, and the existing charge has a different type than the new vouchers.
400 Bad Request	”invalidCombination”	`count` ≠ 1 and `id` is not empty. When creating multiple vouchers, the ID is generated automatically and cannot be set manually. `newCustomersOnly` and `existingCustomersOnly` are set.
400 Bad Request	”duplicateEntry”	`id` already exists. `chargeId` already exists, and `appendToCharge` is not set.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.

DELETE vouchers/{id}

This method deletes an existing voucher by its unique ID. On successful deletion, the ID of the removed voucher is returned as confirmation. Delete permissions for voucher data are required for execution.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/ZZ3R-2ZPC-UDGF-S6DG

Response

{
    "id": "ZZ3R-2ZPC-UDGF-S6DG"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete voucher data.
400 Bad Request	”notFound”	The voucher was not found.

POST vouchers/bulk

This method allows you to create or update multiple vouchers in a single request (bulk import). The request body must contain a JSON array in which each element is an object with a data field that contains the voucher data. A maximum of 10,000 entries can be provided per request. Invalid entries are skipped and listed under skippedLines in the response. If a voucher with the same ID already exists, it is checked whether the data is compatible. With the query parameter ?force, an update can be forced. Create permissions for voucher data are required.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/bulk

Query parameters

Parameter	Type	Meaning
force	Flag	If set, existing vouchers with the same ID are updated without a compatibility check.

Request body

[
    {
        "data": {
            "id": "BULK-0001",
            "active": true,
            "chargeId": "charge-1",
            "maxUseCount": 1,
            "values": [
                {
                    "value": 10,
                    "currency": "EUR",
                    "minOrderValue": 20,
                    "taxId": ""
                }
            ],
            "types": {
                "keepSurplus": false,
                "discount": true,
                "freeShipping": false,
                "maxUseCountPerUser": 1,
                "maxUseCountSet": true,
                "multipleCustomer": false,
                "appOnly": false
            },
            "basketProducts": [],
            "labels": ["import-2025"]
        }
    },
    {
        "data": {
            "id": "BULK-0002",
            "active": true,
            "chargeId": "charge-1",
            "maxUseCount": 5,
            "values": [
                {
                    "value": 25,
                    "currency": "EUR",
                    "minOrderValue": 50,
                    "taxId": ""
                }
            ],
            "types": {
                "keepSurplus": true,
                "discount": false,
                "freeShipping": false,
                "maxUseCountPerUser": 1,
                "maxUseCountSet": false,
                "multipleCustomer": true,
                "appOnly": false
            },
            "basketProducts": [],
            "labels": []
        }
    }
]

Response

{
    "items": [
        "BULK-0001",
        "BULK-0002"
    ],
    "skippedLines": []
}

Response with skipped lines

{
    "items": [
        "BULK-0001"
    ],
    "skippedLines": [
        {
            "lineNumber": 2,
            "errorType": "invalidParameters",
            "fieldErrors": {
                "data": "invalidFormat"
            }
        }
    ]
}

Error codes

Errors in individual entries do not result in an error status. Such entries are skipped and listed in the response under skippedLines with the fieldErrors field. Examples include invalidFormat (no valid data object), invalidValue (the chargeId already exists with a different type), and invalidCombination (newCustomersOnly and existingCustomersOnly are set at the same time).

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create voucher data.
400 Bad Request		Request body could not be loaded or is not an array.

DELETE vouchers/bulk

This method allows you to delete multiple vouchers in a single request. The request body must contain a JSON array in which each element is an object with the id of the voucher to be deleted. A maximum of 10,000 entries can be provided per request. Invalid entries are skipped and listed under skippedItems in the response. Delete permissions for voucher data are required.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/bulk

Request body

[
    {
        "id": "BULK-0001"
    },
    {
        "id": "BULK-0002",
        "pool": true
    }
]

Data fields per entry

Field	Type	Required	Meaning
id	String	Yes	The unique ID of the voucher to be deleted.
pool	Boolean	No	Indicates whether this is a pool voucher (default: `false`).

Response

{
    "items": [
        "BULK-0001",
        "BULK-0002"
    ],
    "skippedItems": []
}

Response with skipped entries

{
    "items": [
        "BULK-0001"
    ],
    "skippedItems": [
        {
            "lineNumber": 2,
            "errorType": "invalidParameters",
            "fieldErrors": {
                "id": "missing"
            }
        }
    ]
}

Error codes

Errors in individual entries do not result in an error status. Such entries are skipped and listed in the response under skippedItems with the fieldErrors field. Examples include invalidFormat (the entry is not a valid JSON object) and missing (the mandatory id field is missing).

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete voucher data.
400 Bad Request		Request body could not be loaded or is not an array.

Methods for voucher charges

This section describes all endpoints for managing voucher charges. A voucher charge is a group of vouchers that can be created and managed together. Through the interface, charges can be listed, filtered, and deleted. In addition, the creator information and the labels of existing charges can be retrieved. Charges are created when vouchers are created via POST vouchers. The function for updating charges is planned for a future version. For all operations, corresponding read, write, create, or delete permissions are required.

GET vouchers/charges

This method returns a paginated list of all voucher charges present in the system. Filter and sort parameters can be used to restrict and order the list by various criteria. The returned data contains information about the charge itself as well as the associated voucher settings. Read permissions are required for access.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/charges?size=100

Response

{
    "endReached": true,
    "items": [
        {
            "createdAt": "2025-01-17T07:56:50.000Z",
            "creator": 0,
            "description": "Example Charge",
            "id": "example-charge",
            "name": "Example Charge",
            "redeemed": 0,
            "updatedAt": "2025-01-17T07:56:50.000Z",
            "voucherChargeCount": 1,
            "voucherData": {
                "labels": [
                    "bar"
                ],
                "maxUseCount": 5,
                "pool": false,
                "types": {
                    "appOnly": false,
                    "discount": false,
                    "freeShipping": false,
                    "keepSurplus": true,
                    "multipleCustomer": false,
                    "newCustomersOnly": false,
                    "maxUseCountSet": false
                },
                "validCustomers": [
                    {
                        "id": 48
                    },
                    {
                        "number": "1234"
                    }
                ],
                "validProducts": [
                    {
                        "number": "go1",
                        "quantity": 1
                    }
                ],
                "validSubshops": [
                    "deutsch"
                ],
                "values": [
                    {
                        "currency": "EUR",
                        "percentValue": 0.0,
                        "taxId": "",
                        "usedValue": 10.0,
                        "value": 42.0
                    },
                    {
                        "currency": "GBP",
                        "minOrderValue": 50.0,
                        "percentValue": 0.0,
                        "taxId": "",
                        "value": 10.0
                    }
                ]
            }
        }
    ],
    "nextPageToken": "MQ",
    "totalCount": 1
}

Filter fields

id, createdAt, updatedAt, type, name, creator, labels, description

Sort fields

id, createdAt, updatedAt, type, name, creator, description

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read voucher data.
400 Bad Request	”invalidValue”
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:”.

GET vouchers/charges/creators

This method returns a list of user accounts with IDs and emails that have created voucher charges. For manually created charges, the name corresponds to the email address of the user account; for imported charges, “Import” is displayed instead. Read permissions are required for access.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/charges/creators

Response

[
    {
        "id": 42,
        "name": "m.mustermann@websale.de"
    }
]

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read voucher data.

GET vouchers/charges/labels

This method returns a list of all labels assigned to voucher charges. Labels are used for categorizing charges and are considered in the full-text search. Access to this information requires read permissions for voucher data.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/charges/labels

Response

[ "label1", "label2" ]

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read voucher data.

PUT vouchers/charges/{chargeid} - Coming soon

This method updates the properties of an existing voucher charge by its unique ID. Through the request body, fields such as name, description, or additional labels can be changed. On successful update, a confirmation is returned. Write permissions for voucher data are required.

This method is not yet implemented and is planned for a future version.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/charges/123456789

Response

{
    "updateCharge": "not implemented"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write voucher data.

DELETE vouchers/charges/{chargeid}

This method deletes an existing voucher charge together with all vouchers it contains by the specified charge ID. On successful deletion, the ID of the removed charge is returned as confirmation. Delete permissions for voucher data are required for execution.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/charges/123456789

Response

{
    "chargeId": "123456789"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete voucher data.
400 Bad Request	”notFound”	The charge was not found.

Methods for voucher blueprints

This section describes all endpoints for managing voucher blueprints (templates). Voucher blueprints define predefined configurations such as discount types, validity periods, values, and other conditions for vouchers. Through the interface, blueprints can be created, updated, retrieved, deleted, and organized with labels. Note: The templateId field internally corresponds to the name column in the database. Despite this assignment, however, within the API you may not sort or filter by name, nor query or set the value explicitly. All operations are performed exclusively via templateId. For all operations, corresponding read, write, create, or delete permissions are required.

GET vouchers/templates

This method returns a paginated list of all existing voucher blueprints (templates). Filter and sort parameters can be used to restrict and order the list. The blueprints define default values for vouchers or voucher charges that can later be created based on these blueprints. Read permissions are required for access.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/templates

Response

{
    "endReached": true,
    "items": [
        {
            "active": true,
            "chargeId": "template-charge",
            "createdAt": "2025-02-19T12:45:47.000Z",
            "labels": [],
            "templateId": "Example Template",
            "types": {
                "appOnly": false,
                "discount": false,
                "freeShipping": false,
                "keepSurplus": false,
                "multipleCustomer": false,
                "newCustomersOnly": false,
                "maxUseCountSet": false
            },
            "updatedAt": "2025-02-19T12:45:47.000Z",
            "values": [
                {
                    "currency": "EUR",
                    "minOrderValue": 0.0,
                    "percentValue": 0.0,
                    "taxId": "",
                    "value": 1.0
                }
            ]
        }
    ],
    "nextPageToken": "MA",
    "totalCount": 1
}

Filter fields

templateId, chargeId, labels, values, active, createdAt, updatedAt, validFrom, validUntil, maxUseCount

Sort fields

id, templateId, chargeId, createdAt, updatedAt, active, validFrom, validUntil, maxUseCount

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read voucher data.
400 Bad Request	”invalidValue”
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:”.

GET vouchers/templates/labels

This method returns a list of all labels assigned to voucher blueprints (templates). Labels are used for categorizing blueprints and are considered in the full-text search. Read permissions are required for access.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/templates/labels

Response

[ "label1", "label2" ]

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read voucher data.

PUT vouchers/templates/{templateId}

This method updates the properties of an existing voucher blueprint (template) by its unique ID, where the ID corresponds to the name of the blueprint. Through the request body, fields such as name, status, values, types, or labels can be adjusted. The data object is written completely. Therefore, send the complete blueprint and not just the changed fields. If the templateId in the request body differs from the value in the path, the blueprint is renamed. Vouchers that have already been issued keep the rules with which they were issued. On successful update, the updated blueprint is returned. Write permissions for voucher data are required.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/templates/oldTemplateName

Request

{
    "templateId": "newTemplateName",
    "data": {
        "active": true,
        "chargeId": "54",
        "createdAt": "2025-02-19T12:45:47.000Z",
        "labels": [],
        "types": {
            "appOnly": false,
            "discount": false,
            "freeShipping": false,
            "keepSurplus": false,
            "multipleCustomer": false,
            "newCustomersOnly": false,
            "maxUseCountSet": false
        },
        "updatedAt": "2025-02-19T12:45:47.000Z",
        "values": [
            {
                "currency": "EUR",
                "minOrderValue": 0.0,
                "percentValue": 0.0,
                "taxId": "",
                "value": 1.0
            }
        ]
    }
}

Response

{
    "active": true,
    "chargeId": "54",
    "createdAt": "2025-02-19T12:45:47.000Z",
    "labels": [],
    "templateId": "newTemplateName",
    "types": {
        "appOnly": false,
        "discount": false,
        "freeShipping": false,
        "keepSurplus": false,
        "multipleCustomer": false,
        "newCustomersOnly": false,
        "maxUseCountSet": false
    },
    "updatedAt": "2025-02-19T12:45:47.000Z",
    "values": [
        {
            "currency": "EUR",
            "minOrderValue": 0.0,
            "percentValue": 0.0,
            "taxId": "",
            "value": 1.0
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write voucher data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidFormat”	`templateId` is not a string. `data` is not an object.
400 Bad Request	”missing”	`templateId` or `data` is missing.
400 Bad Request	”invalidValue”	`chargeId` refers to a non-existent charge.
400 Bad Request	”duplicateEntry”	`name` or `chargeId` are already in use.
400 Bad Request	”notFound”	The blueprint was not found.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.

POST vouchers/templates

This method creates a new voucher blueprint (template) based on the submitted configuration data. The request body must contain a unique templateId and a data object with the relevant voucher settings. On successful creation, the new blueprint is returned. Create permissions for voucher data are required.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/templates

Request body

{
    "templateId": "myNewTemplate",
    "data": {
        "data": {
            "active": true,
            "name": "myNewTemplate",
            "chargeId": "",
            "maxUseCount": 1,
            "values": [
                {
                    "value": 15,
                    "currency": "EUR",
                    "minOrderValue": 55,
                    "taxId": "19"
                }
            ],
            "types": {
                "keepSurplus": false,
                "discount": true,
                "freeShipping": false,
                "maxUseCountSet": false,
                "multipleCustomer": true,
                "appOnly": false
            },
            "basketProducts": [
                {
                    "id": "100-41232"
                }
            ],
            "labels": [
                "Summer"
            ]
        },
        "templateId": "myNewTemplate"
    }
}

Response

{
    "active": null,
    "chargeId": "55",
    "createdAt": "2025-02-19T12:45:47.000Z",
    "labels": [
        "Summer"
    ],
    "templateId": "myNewTemplate",
    "types": {
        "appOnly": false,
        "discount": true,
        "freeShipping": false,
        "keepSurplus": false,
        "maxUseCountSet": false,
        "multipleCustomer": true,
        "newCustomersOnly": false
    },
    "updatedAt": "2025-02-19T12:45:47.000Z",
    "values": [
        {
            "currency": "EUR",
            "minOrderValue": 55,
            "percentValue": 0,
            "taxId": "19",
            "value": 15
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create voucher data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidFormat”	`templateId` is not a string. `data` is not an object. Further fields have the wrong type.
400 Bad Request	”missing”	`templateId` is missing. `data` is missing.
400 Bad Request	”duplicateEntry”	`templateId` or `chargeId` are already in use.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.

DELETE vouchers/templates/{templateId}

This method deletes an existing voucher blueprint (template) by its unique ID, where the ID corresponds to the name of the blueprint. On successful deletion, the templateId of the removed blueprint is returned as confirmation. Delete permissions for voucher data are required for execution.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/templates/myTemplate

Response

{
    "templateId": "myTemplate"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete voucher data.
400 Bad Request	”notFound”	The blueprint was not found.

Methods for voucher presets

This section describes all endpoints for managing voucher presets. In contrast to voucher blueprints, which can be flexibly created and adapted by users, voucher presets are standardized structures that define specific types or properties of vouchers. Presets serve as a basis for creating new vouchers according to fixed specifications and are often more tightly coupled to the system. Through the interface, these presets can be retrieved and adjusted as needed. For all operations, corresponding read and write permissions are required. Note: The presetId field internally corresponds to the name column in the database. Despite this assignment, however, within the API you may not sort or filter by name, nor query or set the value directly. All operations are performed exclusively via presetId.

GET vouchers/presets

This method returns a paginated list of all existing voucher presets. Filter and sort parameters can be used to restrict and order the list by properties such as system status or creation date. The presets contain predefined settings for creating new vouchers. Read permissions are required for access.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/presets

Response

{
    "endReached": true,
    "items": [
        {
            "createdAt": "1970-01-01T00:33:45.000Z",
            "data": {
                ...
            },
            "presetId": "123",
            "system": false,
            "updatedAt": "1970-01-01T00:33:45.000Z"
        }
    ],
    "nextPageToken": "MA",
    "totalCount": 1
}

Filter fields

presetId, system, labels, values, active, validFrom, validUntil, maxUseCount, createdAt, updatedAt

Sort fields

presetId, system, createdAt, updatedAt

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read voucher data.
400 Bad Request	”invalidValue”
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”unknownOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	`size` is not an integer. A filter value is invalid.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:”.

GET vouchers/presets/labels

This method returns a list of all labels assigned to voucher presets. Labels are used for categorizing presets and are considered in the full-text search. Read permissions are required for access to this information.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/presets/labels

Response

[ "label1", "label2" ]

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to read voucher data.

PUT vouchers/presets/{presetid}

This method updates the properties of an existing voucher preset by its unique ID, where the ID corresponds to the name of the preset. Through the request body, the new settings of the preset are provided. These include discount types, values, terms of use, and further attributes. The data object is written completely. Therefore, please send the complete preset and not just the changed fields. If presetId in the request body differs from the value in the path, the preset is renamed. Vouchers that have already been created remain unchanged. On successful update, the updated preset is returned. Write permissions for voucher data are required.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/presets/oldPresetName

Request body

{
    "data": {
        "count": 1,
        "data": {
            "active": true,
            "name": "newPresetName",
            "chargeId": "",
            "values": [
                {
                    "value": 55,
                    "currency": "GBP",
                    "minOrderValue": 100,
                    "taxId": ""
                }
            ],
            "types": {
                "keepSurplus": false,
                "discount": true,
                "freeShipping": false,
                "maxUseCountPerUser": 1,
                "maxUseCountSet": true,
                "multipleCustomer": true,
                "appOnly": false
            },
            "basketProducts": [],
            "labels": [],
            "maxUseCount": 1
        }
    },
    "presetId": "newPresetName"
}

Response

{
    "createdAt": "2025-04-11T13:25:53.000Z",
    "data": {
        "count": 1,
        "data": {
            "active": true,
            "name": "newPresetName",
            "chargeId": "",
            "values": [
                {
                    "value": 55,
                    "currency": "GBP",
                    "minOrderValue": 100,
                    "taxId": ""
                }
            ],
            "types": {
                "keepSurplus": false,
                "discount": true,
                "freeShipping": false,
                "maxUseCountPerUser": 1,
                "maxUseCountSet": true,
                "multipleCustomer": true,
                "appOnly": false
            },
            "basketProducts": [],
            "labels": [],
            "maxUseCount": 1
        }
    },
    "presetId": "newPresetName",
    "system": false,
    "updatedAt": "2025-04-11T13:25:53.000Z"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to write voucher data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidFormat”	`presetId` is not a string. `data` is not an object. Further fields have the wrong type.
400 Bad Request	”missing”	`presetId` is missing. `data` is missing.
400 Bad Request	”invalidCombination”	`newCustomersOnly` and `existingCustomersOnly` are set.
400 Bad Request	”readonlyField”	Updating `disabledFields` is not allowed.
400 Bad Request	”duplicateEntry”	`presetId` is already in use.
400 Bad Request	”notFound”	The preset was not found.
400 Bad Request	”internalError”	Old data could not be read as JSON.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.

POST vouchers/presets

This method creates a new voucher preset based on the submitted configuration data. The request body must contain a unique presetId and a data object with the relevant voucher settings. On successful creation, the new preset is returned. Create permissions for voucher data are required.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/presets

Request body

{
    "presetId": "cvcv89",
    "systemPreset": "",
    "data": {
        "count": 1,
        "data": {
            "active": true,
            "name": "cvcv89",
            "chargeId": "",
            "maxUseCount": 1,
            "values": [
                {
                    "value": 55,
                    "currency": "GBP",
                    "minOrderValue": 55,
                    "taxId": ""
                }
            ],
            "types": {
                "keepSurplus": false,
                "discount": true,
                "freeShipping": false,
                "maxUseCountPerUser": 1,
                "maxUseCountSet": true,
                "multipleCustomer": true,
                "appOnly": false
            },
            "basketProducts": [],
            "labels": []
        }
    }
}

Response

{
    "createdAt": "2025-04-11T13:25:53.000Z",
    "data": {
        "count": 1,
        "data": {
            "active": true,
            "name": "cvcv89",
            "chargeId": "",
            "maxUseCount": 1,
            "values": [
                {
                    "value": 55,
                    "currency": "GBP",
                    "minOrderValue": 55,
                    "taxId": ""
                }
            ],
            "types": {
                "keepSurplus": false,
                "discount": true,
                "freeShipping": false,
                "maxUseCountPerUser": 1,
                "maxUseCountSet": true,
                "multipleCustomer": true,
                "appOnly": false
            },
            "basketProducts": [],
            "labels": []
        }
    },
    "presetId": "cvcv89",
    "system": false,
    "updatedAt": "2025-04-11T13:25:53.000Z"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create voucher data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidFormat”	`presetId` is not a string. `data` is not an object. `validFrom` or `validUntil` contains invalid time values. Further fields have the wrong type.
400 Bad Request	”missing”	`presetId` is missing. `data` is missing.
400 Bad Request	”invalidValue”	`presetId` is empty.
400 Bad Request	”invalidCombination”	`newCustomersOnly` and `existingCustomersOnly` are set at the same time.
400 Bad Request	”readonlyField”	Setting `disabledFields` is not allowed.
400 Bad Request	”duplicateEntry”	`presetId` is already in use.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.

DELETE vouchers/presets/{presetid}

This method deletes an existing voucher preset by its unique ID, where the ID corresponds to the name of the preset. On successful deletion, the ID of the removed preset is returned as confirmation. Delete permissions for voucher data are required for execution.

Example

https://www.<your-shop>.de/admin/api/v1/vouchers/presets/myPreset

Response

{
    "presetId": "myPreset"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete voucher data.
400 Bad Request	”notFound”	The preset was not found.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

​Supported methods

​Data fields

​Data fields of a voucher

​Example

​Data fields of a voucher charge

​Example

​Data fields of a voucher blueprint

​Example

​Data fields of a voucher preset

​Example

​Methods for managing vouchers

​GET vouchers

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​PUT vouchers/{id} - Coming soon

​Example

​Response

​Error codes

​POST vouchers

​Example

​Request body

​Response

​Error codes

​DELETE vouchers/{id}

​Example

​Response

​Error codes

​POST vouchers/bulk

​Example

​Query parameters

​Request body

​Response

​Response with skipped lines

​Error codes

​DELETE vouchers/bulk

​Example

​Request body

​Data fields per entry

​Response

​Response with skipped entries

​Error codes

​Methods for voucher charges

​GET vouchers/charges

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET vouchers/charges/creators

​Example

​Response

​Error codes

​GET vouchers/charges/labels

​Example

​Response

​Error codes

​PUT vouchers/charges/{chargeid} - Coming soon

​Example

​Response

​Error codes

​DELETE vouchers/charges/{chargeid}

​Example

​Response

​Error codes

​Methods for voucher blueprints

​GET vouchers/templates

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET vouchers/templates/labels

​Example

​Response

​Error codes

​PUT vouchers/templates/{templateId}

​Example

Supported methods

Data fields

Data fields of a voucher

Example

Data fields of a voucher charge

Example

Data fields of a voucher blueprint

Example

Data fields of a voucher preset

Example

Methods for managing vouchers

GET vouchers

Example

Response

Filter fields

Sort fields

Error codes

PUT vouchers/{id} - Coming soon

Example

Response

Error codes

POST vouchers

Example

Request body

Response

Error codes

DELETE vouchers/{id}

Example

Response

Error codes

POST vouchers/bulk

Example

Query parameters

Request body

Response

Response with skipped lines

Error codes

DELETE vouchers/bulk

Example

Request body

Data fields per entry

Response

Response with skipped entries

Error codes

Methods for voucher charges

GET vouchers/charges

Example

Response

Filter fields

Sort fields

Error codes

GET vouchers/charges/creators

Example

Response

Error codes

GET vouchers/charges/labels

Example

Response

Error codes

PUT vouchers/charges/{chargeid} - Coming soon

Example

Response

Error codes

DELETE vouchers/charges/{chargeid}

Example

Response

Error codes

Methods for voucher blueprints

GET vouchers/templates

Example

Response

Filter fields

Sort fields

Error codes

GET vouchers/templates/labels

Example

Response

Error codes

PUT vouchers/templates/{templateId}

Example