# Promocode anwenden

Wendet einen Code auf einen Warenkorb an. Wird ein Promocode angewendet, wird der Warenkorb-Gesamtbetrag neu berechnet, damit der Rabatt auf den gesamten Warenkorb oder auf ausgewählte Artikel berücksichtigt wird. Außerdem können dem Warenkorb Bonusartikel hinzugefügt werden. Der Rabatt wird an der Kasse abgezogen, während die Bonusartikel nach erfolgreicher Zahlung gewährt werden. Solange der Nutzer nicht gezahlt hat, kann er den Promocode entfernen. Dadurch wird der Rabatt storniert und die Bonusartikel aus dem Warenkorb entfernt.

Endpoint: POST /v2/project/{project_id}/promocode/redeem
Version: 2.0.0
Security: AuthForCart

## Path parameters:

  - `project_id` (integer, required)
    Projekt-ID. Dieser Parameter wird im Kundenportal neben dem Projektnamen angezeigt sowie in der Adressleiste des Browsers, wenn Sie im Kundenportal ein Projekt geöffnet haben. Die URL hat das folgende Format: https://publisher.xsolla.com//projects/.
    Example: 44056

## Request fields (application/json):

  - `coupon_code` (string)
    Eindeutiger Code des Promocodes. Enthält Buchstaben und Ziffern.
    Example: "SUMMER2021"

  - `cart` (object,null)

  - `cart.id` (string, required)
    Warenkorb-ID.

  - `selected_unit_items` (object)
    Vom Nutzer als Bonus ausgewählter plattformspezifischer Spielschlüssel. Übermitteln Sie die [erhaltene](/de/api/liveops/promotions-coupons/get-coupon-rewards-by-code#promotions-coupons/get-coupon-rewards-by-code/t=response&c=200&path=bonus/item) bonus.item.sku als Schlüssel und die ausgewählte bonus.item.unit_items.sku als Schlüsselwert.

## Response 200 fields (application/json):

  - `cart_id` (string)
    Warenkorb-ID.
    Example: "cart_id"

  - `price` (object,null)
    Warenkorbpreis.
    Example: {"amount":"6150.0000000000000000","amount_without_discount":"6150.0000000000000000","currency":"USD"}

  - `price.amount` (string)
    Example: "6150.0000000000000000"

  - `price.amount_without_discount` (string)
    Example: "6150.0000000000000000"

  - `price.currency` (string)
    Example: "USD"

  - `is_free` (boolean)
    Ob der Artikel kostenlos ist.

  - `items` (array)
    Example: [{"attributes":[],"description":"Take it, take it all! All of Xsolla's riches in one Mega Booster.","groups":[{"external_id":"powerups","name":"Power Ups"}],"image_url":"https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png","is_free":false,"name":"Xsolla Booster Mega","price":{"amount":"50.0000000000000000","amount_without_discount":"100.0000000000000000","currency":"USD"},"quantity":123,"sku":"com.xsolla.booster_mega_1","type":"virtual_good","virtual_item_type":"consumable","virtual_prices":[],"promotions":[{"name":"Bonus promotion","date_start":"2020-04-15T16:16:00+03:00","date_end":"2026-04-15T16:16:00+03:00","discount":{"percent":"50.00"},"bonus":[{"quantity":1,"name":"Xsolla Minigun","image_url":"https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png","sku":"com.xsolla.minigun_1","type":"virtual_good"}]}],"can_be_bought":true,"vp_rewards":[{"item_id":175232,"sku":"com.xsolla.value_point_1","amount":130,"name":"Value point","image_url":"https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg","is_clan":false},{"item_id":186321,"sku":"com.xsolla.clan_value_point_1","amount":50,"name":"Clan Reward VP 1","image_url":"https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg","is_clan":true}],"limits":{"per_user":{"available":3,"recurrent_schedule":{"interval_type":"weekly","reset_next_date":1746057600},"total":5}},"periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}]}]

  - `items.sku` (string)

  - `items.groups` (array)

  - `items.groups.external_id` (string)

  - `items.groups.name` (string)

  - `items.name` (string,null)

  - `items.type` (string)

  - `items.description` (string)

  - `items.image_url` (string)

  - `items.quantity` (integer)

  - `items.is_free` (boolean)
    Ob der Artikel kostenlos ist.

  - `items.promotions` (array)
    Auf bestimmte Artikel im Warenkorb angewandte Werbeaktionen. Das array wird in den folgenden Fällen zurückgegeben:

* Für einen bestimmten Artikel ist eine Rabattaktion konfiguriert.

* Ein Promocode mit der Einstellung Rabatt auf ausgewählte Artikel ist angewandt.

Werden keine Werbeaktionen auf Artikelebene angewandt, wird ein leeres Array zurückgegeben.

  - `items.promotions.name` (string)

  - `items.promotions.date_start` (string,null)

  - `items.promotions.date_end` (string,null)

  - `items.promotions.discount` (object,null)

  - `items.promotions.discount.percent` (string,null)

  - `items.promotions.discount.value` (string,null)

  - `items.promotions.bonus` (array)

  - `items.promotions.bonus.sku` (string)

  - `items.promotions.bonus.quantity` (integer)

  - `items.promotions.bonus.type` (string)
    Typ des Bonusartikels.
    Enum: "virtual_good", "virtual_currency", "bundle", "physical_good", "game_key", "nft"

  - `items.promotions.bonus.name` (string)
    Name des Bonusartikels. Nicht verfügbar für Bonusartikel vom Typ physical_good.

  - `items.promotions.bonus.image_url` (string)
    Bild-URL des Bonusartikels. Nicht verfügbar für Bonusartikel vom Typ physical_good.

  - `items.promotions.bonus.bundle_type` (string)
    Typ des im Bundle enthaltenen Bonusartikels. Nur verfügbar für Bonusartikel vom Typ bundle.
    Enum: "standard", "virtual_currency_package"

  - `items.promotions.limits` (object)

  - `items.promotions.limits.per_user` (object)

  - `items.promotions.limits.per_user.available` (integer)

  - `items.promotions.limits.per_user.total` (integer)

  - `items.can_be_bought` (boolean)
    Sofern true, kann der Nutzer einen Artikel kaufen.

  - `items.vp_rewards` (array)
    Liste Wertpunktbelohnungen für den Artikel.

  - `items.vp_rewards.item_id` (integer)
    Interne eindeutige Artikel-ID.

  - `items.vp_rewards.sku` (string)
    Eindeutige ID des Wertpunkts.

  - `items.vp_rewards.amount` (integer)
    Anzahl der Wertpunkte.

  - `items.vp_rewards.name` (string)
    Wertpunktname.

  - `items.vp_rewards.image_url` (string)
    Bild-URL.

  - `items.vp_rewards.is_clan` (boolean)
    Ob der Wertpunkt in Clan-Belohnungsketten verwendet wird.

  - `items.loyalty_rewards` (array)
    Treuepunkte, die der Nutzer als Belohnung für den Kauf des Artikels erhält.

  - `items.loyalty_rewards.name` (string)
    Treuepunktname.

  - `items.loyalty_rewards.sku` (string)
    Treuepunkte-SKU. Übermittelnn Sie diesen Wert im Parameter loyalty_point_sku anderer API-Aufrufe, beispielsweise beim Anlegen einer mit Treuepunkten bezahlten Bestellung.

  - `items.loyalty_rewards.description` (string)
    Treuepunktbeschreibung.

  - `items.loyalty_rewards.image_url` (string,null)
    Bild-URL.

  - `items.loyalty_rewards.amount` (integer)
    Wie viele Treuepunkte der Nutzer für den Kauf des Artikels erhält.

  - `items.limits` (object,null)
    Artikelbeschränkungen.

  - `items.limits.per_user` (object,null)
    Artikelbeschränkungen für einen Nutzer.

  - `items.limits.per_user.total` (integer)
    Höchstzahl von Artikeln, die ein einzelner Nutzer kaufen kann.
    Example: 5

  - `items.limits.per_user.available` (integer)
    Verbleibende Anzahl von Artikeln, die der aktuelle Nutzer kaufen kann.
    Example: 3

  - `items.limits.per_user.recurrent_schedule` (any)

  - `items.limits.per_user.limit_exceeded_visibility` (string)
    Steuert die Sichtbarkeit des Artikels im Katalog nach Erreichen des Kauflimits, und zwar bis das Limit das nächste Mal zurückgesetzt wird.

Gilt für Artikel, bei denen im Array recurrent_schedule Limits konfiguriert sind, die regelmäßig zurückgesetzt werden.

Wenn festgelegt ist, dass das Kauflimit nicht zurückgesetzt wird, wird der Artikel nach Erreichen des Kauflimits nicht mehr im Katalog angezeigt, unabhängig davon, welcher Wert für limit_exceeded_visibility festgelegt ist.

Mögliche Wert:
- show – Der Artikel wird in API-Aufrufen zur Katalogabfrage zurückgegeben, auch wenn das Kauflimit bereits erreicht wurde.
Bei clientseitigen API-Aufrufen zur Katalogabfrage wird der Artikel nach Erreichen des Limits mit dem Flag can_be_bought: false zurückgegeben.
Das Datum, an dem das Limit das nächste Mal zurückgesetzt wird, wird im Parameter reset_next_date zurückgegeben.
- hide – nachdem das Kauflimit erreicht wurde, wird der Artikel bei API-Aufrufen zur Katalogabfrage nicht mehr zurückgegeben, bis das Limit zurückgesetzt wird.
    Enum: "show", "hide"

  - `items.limits.per_item` (object,null)
    Artikelbeschränkungen für einen Artikel.

  - `items.limits.per_item.total` (integer)
    Höchstzahl von Artikeln, die alle Nutzer kaufen können.
    Example: 5

  - `items.limits.per_item.available` (integer)
    Verbleibende Anzahl von Artikeln, die alle Nutzer kaufen können.
    Example: 3

  - `items.periods` (array,null)
    Artikelangebotszeitraum.

  - `items.periods.date_from` (string)
    Datum, an dem der angegebene Artikel zum Verkauf angeboten wird.
    Example: "2020-08-11T10:00:00+03:00"

  - `items.periods.date_until` (string,null)
    Datum, an dem der angegebene Artikel nicht mehr zum Verkauf angeboten wird. Möglich ist: null.
    Example: "2020-08-11T20:00:00+03:00"

  - `rewards` (object)

  - `rewards.bonus` (array)

  - `rewards.bonus.item` (object)

  - `rewards.bonus.item.sku` (string)
    Eindeutige Artikel-ID. Die SKU darf nur lateinische Klein- und Großbuchstaben, Ziffern, Punkte, Bindestriche und Unterstriche enthalten.
    Example: "game_01"

  - `rewards.bonus.item.name` (string)
    Artikelname.
    Example: "Game name"

  - `rewards.bonus.item.type` (string)
    Artikeltyp. Mögliche Werte:virtual_good – virtuelle Gegenständevirtual_currency – virtuelle Währungbundle – Bundleunit – Spielschlüsselpaket
    Example: "unit"

  - `rewards.bonus.item.description` (string)
    Artikelbeschreibung.
    Example: "Game description"

  - `rewards.bonus.item.image_url` (string)
    Bild-URL.
    Example: "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png"

  - `rewards.bonus.item.unit_items` (array)
    Ein Array plattformspezifischer Spielschlüssel. Wird nur beim Artikeltyp unit (bonus.item.type = 'unit') genutzt. Wenn das Spielschlüsselpaket plattformspezifische Schlüssel enthält, kann der Nutzer eine davon als Bonus auswählen.

  - `rewards.bonus.item.unit_items.sku` (string)
    Eindeutige plattformspezifische Spielschlüsselpaket-ID. Zulässige Zeichen: a–z, A–Z, 0–9, Punkt (.), Bindestrich (-), Unterstrich (_). Setzt sich aus den beiden Werten bonus.item.​sku und bonus.item.unit_items.drm_sku zusammen. Wenn beispielsweisebonus.item.​sku = 'cool_game' und bonus.item.unit_items.drm_sku = 'steam' festgelegt sind, lautet der Wert cool_game_steam.
    Example: "cool_game_steam"

  - `rewards.bonus.item.unit_items.is_free` (boolean)

  - `rewards.bonus.item.unit_items.type` (string)
    Gibt an, dass es sich bei dem Artikel um einen Spielschlüssel handelt.
    Enum: "game_key"

  - `rewards.bonus.item.unit_items.name` (string)
    Spieltitel.
    Example: "Awesome Game"

  - `rewards.bonus.item.unit_items.drm_name` (string)
    DRM-Name.
    Example: "Steam"

  - `rewards.bonus.item.unit_items.drm_sku` (string)
    Eindeutige DRM-ID, die als Suffix verwendet wird, um einen plattformspezifischen Spielschlüssel zu kennzeichnen. Zulässige Zeichen: a–z, A–Z, 0–9, Punkt (.), Bindestrich (-), Unterstrich (_).
    Example: "steam"

  - `rewards.bonus.quantity` (number)
    Artikelmenge.

  - `rewards.discount` (object,null)
    Prozentualer Rabatt.
Der Preis des Warenkorbs wird um einen Wert verringert, der anhand dieses Prozentsatzes berechnet und dann auf zwei Dezimalstellen gerundet wird.

  - `rewards.discount.percent` (string)
    Example: "10.00"

  - `rewards.discounted_items` (array,null)
    Liste der Artikel, die durch einen Promocode rabattiert werden.

  - `rewards.discounted_items.sku` (string, required)
    Artikel-SKU.

  - `rewards.discounted_items.discount` (object, required)

  - `rewards.discounted_items.discount.percent` (string, required)
    Prozentualer Rabatt.

Der Preis des Artikels im Warenkorb wird um einen Wert verringert,
der anhand dieses Prozentsatzes berechnet und dann
auf zwei Dezimalstellen gerundet wird.

  - `rewards.is_selectable` (boolean)
    Ist true eingestellt, sollte der Nutzer vor dem Einlösen eines Promocodes den Bonus auswählen.

## Response 401 fields (application/json):

  - `statusCode` (integer)
    Example: 401

  - `errorCode` (integer)
    Example: 1501

  - `errorMessage` (string)
    Example: "[0401-1501]: Authorization failed: Provide authorization"

## Response 403 fields (application/json):

  - `statusCode` (integer)
    Example: 403

  - `errorCode` (integer)

  - `errorMessage` (string)
    Example: "Authorization header not sent."

  - `transactionId` (string)
    Example: "x-x-x-x-transactionId-mock-x-x-x"

## Response 404 fields (application/json):

  - `statusCode` (integer)
    Example: 404

  - `errorCode` (integer)
    Example: 4001

  - `errorMessage` (string)
    Example: "[0401-9807]: Enter valid promo code."

## Response 422 fields (application/json):

  - `statusCode` (integer)
    Example: 422

  - `errorCode` (integer)
    Example: 1102

  - `errorMessage` (string)
    Example: "[0401-1102]: Unprocessable Entity. The property `coupon_code` is required"

  - `transactionId` (string)
    Example: "x-x-x-x-transactionId-mock-x-x-x"