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

> Gutscheincodes in der Storefront über die Storefront API prüfen, einlösen und entfernen sowie aktualisierte Warenkorbsummen und Rabatte abrufen.

Die Storefront API Gutscheine ermöglicht es, Gutscheincodes in der Storefront einzulösen und zu entfernen. Die API prüft dabei automatisch, ob ein Code gültig ist, und liefert nach der Einlösung die aktualisierten Warenkorbwerte (z. B. Rabatte und Summen) sowie bei Bedarf Hinweise/Fehlermeldungen zurück.

***

## Unterstützte Methoden

Angabe aller Unterstützten Methoden

| **Befehl**               | **Endpunkte**    | **GET**               | **PUT**             | **POST**              | **DELETE**            |
| ------------------------ | ---------------- | --------------------- | ------------------- | --------------------- | --------------------- |
| Gutschein Daten auslesen | `voucher/get`    | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="ban" />   |
| Gutschein einlösen       | `voucher/redeem` | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" />   |
| Gutschein löschen        | `voucher/delete` | <Icon icon="ban" />   | <Icon icon="ban" /> | <Icon icon="ban" />   | <Icon icon="check" /> |

## Methoden für Gutscheine

Diese Methoden ermöglichen das Prüfen, Einlösen und Entfernen von Gutscheinen direkt im Warenkorb oder im Checkout.

### GET voucher/get

Dieser Aufruf liest Stammdaten zu einem Gutscheincode aus (z.B. Wert, Währung, Mindestbestellwert). Diese Informationen können im Warenkorb und Checkout verwendet werden, um einen Gutschein vor dem Einlösen zu prüfen und Infos wie Betrag und Bedingungen anzuzeigen.

Beispiel-Aufruf für den Gutschein mit der Gutscheinnummer `7G3M-L2UU-CK1B-A2J2`:

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

#### **Parameterübersicht**

#### **Body-Parameter**

| **Parameter** | **Typ** | **Beschreibung**                                               |
| ------------- | ------- | -------------------------------------------------------------- |
| `id`          | String  | **Pflichtfeld**<br />Gutscheincode, der abgefragt werden soll. |

#### **Beispiel-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

Dieser Aufruf löst einen Gutscheincode für den aktuellen Warenkorb ein und liefert Informationen zum eingelösten Gutschein und zum verbleibenden Wert. Dieser Befehl kann verwendet werden, um im Warenkorb oder Checkout den Gutschein zu verrechnen oder den eingelösten Betrag und ggf. den Restwert anzuzeigen.

Beispiel-Aufruf für die Einlösung des Gutscheins `7G3M-L2UU-CK1B-A2J2`:

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

#### **Beispiel-Request**

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

#### **Parameterübersicht**

#### **Header-Parameter**

| **Parameter** | **Beschreibung**                                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](/schnittstellen/storefront-api/storefront-api-basics) |

#### **Body-Parameter**

| **Paramter** | **Typ** | **Beschreibung**                                        |
| ------------ | ------- | ------------------------------------------------------- |
| `id`         | string  | **Pflichtfeld**<br />Gutscheincode, der einzulösen ist. |

#### **Beispiel-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
      }
    ]
  }
}
```

#### **Fehlercodes**

| **Fehlercode**     | **Beschreibung**                                                              |
| ------------------ | ----------------------------------------------------------------------------- |
| `invalidVoucherId` | Die angegebene ID ist kein gültiger Gutscheincode.                            |
| `deactivated`      | Der Gutschein wurde deaktiviert.                                              |
| `expired`          | Der Gutschein ist abgelaufen.                                                 |
| `notYetValid`      | Der Gutschein ist noch nicht gültig.                                          |
| `maxCountExceeded` | Die maximale Anzahl an einlösbaren Gutscheinen pro Bestellung wurde erreicht. |
| `valueSpent`       | Der Gesamtwert des Gutscheins ist bereits verbraucht.                         |
| `currencyMismatch` | Die Gutscheinwährung passt nicht zur Shop-Währung.                            |
| `invalidCustomer`  | Der Gutschein darf von diesem Kunden nicht eingelöst werden.                  |
| `invalidSubshop`   | Der Gutschein darf in diesem Subshop nicht eingelöst werden.                  |

### DELETE voucher/delete

Dieser Aufruf entfernt einen eingelösten Gutscheincode aus dem aktuellen Warenkorb und aktualisiert die Gutscheinübersicht. Dieser Befehl kann verwendet werden, um im Warenkorb oder Checkout eine versehentlich eingelöste oder nicht gewünschte Gutscheinanwendung rückgängig zu machen.

Beispiel-Aufruf für das Entfernen des Gutscheins mit dem Code `7G3M-L2UU-CK1B-A2J2`:

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

#### **Beispiel-Request**

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

#### **Parameterübersicht**

#### **Header-Parameter**

| **Parameter** | **Beschreibung**                                                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-session`   | **Pflichtfeld**<br />ID der aktuellen Session.   <br />Mehr Informationen dazu: [Storefront API Basics](/schnittstellen/storefront-api/storefront-api-basics) |

#### **Body-Parameter**

| **Parameter** | **Typ** | **Beschreibung**                                              |
| ------------- | ------- | ------------------------------------------------------------- |
| `id`          | String  | **Pflichtcode**<br />Gutscheincode, der entfernt werden soll. |

#### **Beispiel-Response**

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

#### **Fehlercodes**

| **Fehlercode**     | **Beschreibung**                                   |
| ------------------ | -------------------------------------------------- |
| `invalidVoucherId` | Die angegebene ID ist kein gültiger Gutscheincode. |