> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.
# API reference vouchers
> Create, list, and remove vouchers, bulk batches, blueprints, presets, and charges through the Admin Interface API vouchers endpoints for shop promotions.
The `vouchers/` endpoint provides you with an interface for managing vouchers in our shop system. With this interface, you can create vouchers, delete them, create templates, and view existing vouchers.
***
## 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. |
| validCustomers\[].id | Integer | ID of a customer authorized to redeem the voucher. |
| validCustomers\[].number | String | Customer number of an authorized customer. |
| 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. |
| 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. |
#### Example
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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](https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3058532517/API-Referenz+Gutscheine#21-datenfelder-eines-gutscheins). |
#### Example
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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](/en/schnittstellen/admin-interface-api/api-referenz-gutscheine).
#### Example
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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](/en/schnittstellen/admin-interface-api/api-referenz-gutscheine). |
#### Example
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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, updated, deleted, and retrieved. The management of voucher charges is handled separately in its own 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers?size=100
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/1CUA-8341-FD8Q-KPJ2
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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.
A maximum of 10,000 vouchers can be created per request. On successful creation, the associated charge ID as well as the number of created vouchers are returned.
Create permissions for voucher data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 `true`, and `chargeId` is missing. |
| 400 Bad Request | "invalidValue" | `count` ∉ \[1;10000] |
| 400 Bad Request | "invalidCombination" | `count` ≠ 1 and `voucherId` 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" | `voucherId` or `chargeId` already exist. |
| 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/ZZ3R-2ZPC-UDGF-S6DG
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
"BULK-0001",
"BULK-0002"
],
"skippedLines": []
}
```
#### Response with skipped lines
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
"BULK-0001"
],
"skippedLines": [
{
"lineNumber": 2,
"errorType": "invalidParameters",
"fieldErrors": {
"data": "invalidFormat"
}
}
]
}
```
#### 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 or is not an array. |
| 400 Bad Request | "invalidFormat" | An element in the array does not contain a valid `data` object. |
| 400 Bad Request | "invalidValue" | The charge ID (`chargeId`) already exists with a different type. |
| 400 Bad Request | "invalidCombination" | `newCustomersOnly` and `existingCustomersOnly` are set at the same time. |
### 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/bulk
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
"BULK-0001",
"BULK-0002"
],
"skippedItems": []
}
```
#### Response with skipped entries
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
"BULK-0001"
],
"skippedItems": [
{
"lineNumber": 2,
"errorType": "invalidParameters",
"fieldErrors": {
"id": "missing"
}
}
]
}
```
#### 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 | | Request body could not be loaded or is not an array. |
| 400 Bad Request | "invalidFormat" | An element in the array is not a valid JSON object. |
| 400 Bad Request | "missing" | The mandatory `id` field is missing in an entry. |
## 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, created, updated, exported, and deleted. In addition, creator information and labels of existing charges can be retrieved.
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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges?size=100
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges/creators
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges/labels
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[ "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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges/123456789
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/charges/123456789
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`, `value`, `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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates/labels
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[ "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. On successful update, the `templateId` of the edited blueprint is returned.
Write permissions for voucher data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates/oldTemplateName
```
#### Request
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 ID of the new blueprint is returned.
Create permissions for voucher data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/templates/myTemplate
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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`, `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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets/labels
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[ "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. |
### 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, including discount types, values, terms of use, and further attributes. On successful update, the ID of the changed preset is returned.
Write permissions for voucher data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets/oldPresetName
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 ID of the new preset is returned.
Create permissions for voucher data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/vouchers/presets/myPreset
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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](https://websale.atlassian.net/servicedesk/customer/portal/6)
Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.