# Redeem promo code

Redeems a code of promo code promotion.
After redeeming a promo code, the user will get free items and/or the price of the cart and/or particular items will be decreased.

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

## Path parameters:

  - `project_id` (integer, required)
    Project ID. You can find this parameter in your Publisher Account next to the name of the project.
    Example: 44056

## Request fields (application/json):

  - `coupon_code` (string)
    Unique code of promo code. Contains letters and numbers.
    Example: "SUMMER2021"

  - `cart` (object,null)

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

  - `selected_unit_items` (object)
    The reward that is selected by a user.
Object key is an SKU of a unit, and value is an SKU of one of the items in a unit.
    Example: {"game_1":"game_1_steam","game_2":"game_2_playstation"}

## Response 200 fields (application/json):

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

  - `price` (object,null)
    Cart price.
    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)
    If true, the item is free.

  - `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":{"$ref":"../schemas/Catalog_item_promotions.yaml"},"can_be_bought":{"$ref":"../schemas/Can_be_bought.yaml"},"vp_rewards":{"$ref":"../schemas/reward-chain-client/client-item-value-point-reward.yaml"},"limits":{"$ref":"../schemas/Catalog_item_limits.yaml"},"periods":{"$ref":"../schemas/item-periods.yaml"}}]

  - `items.sku` (string)

  - `items.groups` (array)

  - `items.groups.external_id` (string)

  - `items.groups.name` (string)

  - `items.type` (string)

  - `items.description` (string)

  - `items.image_url` (string)

  - `items.quantity` (integer)

  - `items.promotions` (array)
    Applied promotions for specific items in the cart. The array is returned in the following cases:

* A discount promotion is configured for a specific item.

* A promo code with the Discount on selected items setting is applied.

If no item-level promotions are applied, an empty array is returned.

  - `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.type` (string)
    Bonus item type.
    Enum: "virtual_good", "virtual_currency", "bundle", "physical_good", "game_key", "nft"

  - `items.promotions.bonus.name` (string)
    Bonus item name. Not available for physical_good bonus item type.

  - `items.promotions.bonus.image_url` (string)
    Bonus item image URL. Not available for physical_good bonus item type.

  - `items.promotions.bonus.bundle_type` (string)
    Bonus bundle item type. Available only for bundle bonus item type.
    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)
    If true, the user can buy an item.
    Example: true

  - `items.vp_rewards` (array)
    Value point item reward.

  - `items.vp_rewards.item_id` (integer)
    Internal unique item ID.
    Example: 1

  - `items.vp_rewards.sku` (string)
    Unique value point ID.

  - `items.vp_rewards.amount` (integer)
    Amount of value points.

  - `items.vp_rewards.name` (string)
    Value point name.

  - `items.vp_rewards.image_url` (string)
    Image URL.
    Example: "https://image.example.com"

  - `items.vp_rewards.is_clan` (boolean)
    Whether the value point is used in clan reward chains.
    Example: true

  - `items.limits` (object,null)
    Item limits.

  - `items.limits.per_user` (object,null)
    Item limits for a user.

  - `items.limits.per_user.total` (integer)
    Maximum number of items a single user can purchase.
    Example: 5

  - `items.limits.per_user.available` (integer)
    Remaining number of items the current user can purchase.
    Example: 3

  - `items.limits.per_user.recurrent_schedule` (object)
    Item limits recurrent refresh period for a user.

  - `items.limits.per_user.recurrent_schedule.interval_type` (string)
    Recurrent refresh period type.
    Enum: "daily", "weekly", "monthly", "hourly"

  - `items.limits.per_user.recurrent_schedule.reset_next_date` (integer)
    Date and time when limits reset (Unix Timestamp).
    Example: 1677553200

  - `items.limits.per_user.limit_exceeded_visibility` (string)
    Determines the visibility of the item in the catalog after the purchase limit is reached, until the next limit reset.

Applies to items for which recurring limit resets are configured in the recurrent_schedule array.

If limit resets are not configured, the item doesn't appear in the catalog after the purchase limit is reached, regardless of the limit_exceeded_visibility value.
    Enum: "show", "hide"

  - `items.limits.per_item` (object,null)
    Item limits for an item.

  - `items.limits.per_item.total` (integer)
    Maximum number of items all users can purchase.
    Example: 5

  - `items.limits.per_item.available` (integer)
    Remaining number of items all users can purchase.
    Example: 3

  - `items.periods` (array,null)
    Item sales period.

  - `items.periods.date_from` (string)
    Date when the specified item will be available for sale.
    Example: "2020-08-11T10:00:00+03:00"

  - `items.periods.date_until` (string,null)
    Date when the specified item will become unavailable for sale. Can be null.
    Example: "2020-08-11T20:00:00+03:00"

  - `rewards` (object)

  - `rewards.discount` (object,null)
    Percent discount.
The price of cart will be decreased using a value calculated by using this percent and then rounded to 2 decimal places.

  - `rewards.discounted_items` (array,null)
    List of items that are discounted by a promo code.

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

  - `rewards.is_selectable` (boolean)
    If true, the user should choose the bonus before redeeming a promo code.

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