> ## 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.

# Storefront API Vouchers

> Redeem and remove voucher codes in the storefront via the Storefront API and receive updated cart totals, discounts, and validation messages.

The Storefront API Vouchers allows voucher codes to be redeemed and removed in the storefront. The API automatically checks whether a code is valid and, after redemption, returns the updated shopping cart values (e.g. discounts and totals) as well as notices/error messages if needed.

***

## Supported methods

List of all supported methods.

| **Command**       | **Endpoints**    | **GET**               | **PUT**             | **POST**              | **DELETE**            |
| ----------------- | ---------------- | --------------------- | ------------------- | --------------------- | --------------------- |
| Read voucher data | `voucher/get`    | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Redeem voucher    | `voucher/redeem` | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" />   |
| Delete voucher    | `voucher/delete` | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="check" /> |

## Methods for vouchers

These methods allow you to check, redeem, and remove vouchers directly in the shopping cart or checkout.

### GET voucher/get

This call reads master data for a voucher code (e.g. value, currency, minimum order value). This information can be used in the shopping cart and checkout to check a voucher before redeeming it and to display info such as amount and conditions.

Example call for the voucher with the voucher number `7G3M-L2UU-CK1B-A2J2`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/voucher/get?id=7G3M-L2UU-CK1B-A2J2
```

#### **Parameter overview**

#### **Body parameters**

| **Parameter** | **Type** | **Description**                                     |
| ------------- | -------- | --------------------------------------------------- |
| `id`          | String   | **Required field**<br />Voucher code to be queried. |

#### **Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "currency": "EUR",
  "id": "7G3M-L2UU-CK1B-A2J2",
  "minOrderValue": 0,
  "taxId": "19",
  "value": 10.5
}
```

### POST voucher/redeem

This call redeems a voucher code for the current shopping cart and returns information about the redeemed voucher and the remaining value. This command can be used in the shopping cart or checkout to offset the voucher or to display the redeemed amount and, if applicable, the remaining value.

Example call for redeeming the voucher `7G3M-L2UU-CK1B-A2J2`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://<your-shop>.de/api/v1/voucher/redeem
```

#### **Example request**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "id": "7G3M-L2UU-CK1B-A2J2"
}
```

#### **Parameter overview**

#### **Header parameters**

| **Parameter** | **Description**                                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Required field**<br />ID of the current session.   <br />More information: [Storefront API Basics](/en/schnittstellen/storefront-api/storefront-api-basics) |

#### **Body parameters**

| **Parameter** | **Type** | **Description**                                      |
| ------------- | -------- | ---------------------------------------------------- |
| `id`          | string   | **Required field**<br />Voucher code to be redeemed. |

#### **Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "info": {
    "totalUsedValue": 0,
    "totalValue": 10.5,
    "vouchers": [
      {
        "currency": "EUR",
        "id": "7G3M-L2UU-CK1B-A2J2",
        "taxId": "19",
        "usedValue": 0,
        "value": 10.5
      }
    ]
  }
}
```

#### **Error codes**

| **Error code**     | **Description**                                                       |
| ------------------ | --------------------------------------------------------------------- |
| `invalidVoucherId` | The specified ID is not a valid voucher code.                         |
| `deactivated`      | The voucher has been deactivated.                                     |
| `expired`          | The voucher has expired.                                              |
| `notYetValid`      | The voucher is not yet valid.                                         |
| `maxCountExceeded` | The maximum number of redeemable vouchers per order has been reached. |
| `valueSpent`       | The total value of the voucher has already been spent.                |
| `currencyMismatch` | The voucher currency does not match the shop currency.                |
| `invalidCustomer`  | The voucher may not be redeemed by this customer.                     |
| `invalidSubshop`   | The voucher may not be redeemed in this subshop.                      |

### DELETE voucher/delete

This call removes a redeemed voucher code from the current shopping cart and updates the voucher overview. This command can be used in the shopping cart or checkout to undo an accidentally redeemed or unwanted voucher application.

Example call for removing the voucher with the code `7G3M-L2UU-CK1B-A2J2`:

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
DELETE https://<your-shop>.de/api/v1/voucher/delete
```

#### **Example request**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "id": "7G3M-L2UU-CK1B-A2J2"
}
```

#### **Parameter overview**

#### **Header parameters**

| **Parameter** | **Description**                                                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Required field**<br />ID of the current session.   <br />More information: [Storefront API Basics](/en/schnittstellen/storefront-api/storefront-api-basics) |

#### **Body parameters**

| **Parameter** | **Type** | **Description**                                     |
| ------------- | -------- | --------------------------------------------------- |
| `id`          | String   | **Required field**<br />Voucher code to be removed. |

#### **Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "info": {
    "totalUsedValue": 0,
    "totalValue": 0,
    "vouchers": []
  }
}
```

#### **Error codes**

| **Error code**     | **Description**                               |
| ------------------ | --------------------------------------------- |
| `invalidVoucherId` | The specified ID is not a valid voucher code. |