# Apply promo code

Applies a code to a cart. When a promo code is applied, the cart total is recalculated to reflect a discount on the entire cart or on selected items. Bonus items may also be added to the cart. The discount is applied at checkout, while bonus items are granted after successful payment. Before payment, the user can remove the promo code, which cancels the discount and removes the bonus items from the cart.

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

## Path parameters:

  - `project_id` (integer, required)
    프로젝트 ID. 이 매개 변수는 프로젝트 이름 옆의 관리자 페이지에서 또는 프로젝트 작업 시 브라우저 주소 표시줄에서 확인할 수 있습니다. URL 형식은 다음과 같습니다: https://publisher.xsolla.com//projects/.
    Example: 44056

## Request fields (application/json):

  - `coupon_code` (string)
    고유한 프로모션 코드입니다. 문자와 숫자를 포함합니다.
    Example: "SUMMER2021"

  - `cart` (object,null)

  - `cart.id` (string, required)
    장바구니 ID입니다.

  - `selected_unit_items` (object)
    사용자가 보너스로 선택한 플랫폼 전용 게임 키. 키로 [received](/ko/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를 전달학고 값으로 선택된 bonus.item.unit_items.sku를 전달합니다.

## Response 200 fields (application/json):

  - `cart_id` (string)
    장바구니 ID입니다.
    Example: "cart_id"

  - `price` (object,null)
    장바구니 가격입니다.
    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)
    아이템이 무료인지 여부입니다.

  - `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)
    아이템이 무료인지 여부입니다.

  - `items.promotions` (array)
    장바구니의 특정 아이템에 적용된 프로모션. 다음의 경우 배열이 반환됩니다.

* 특정 아이템에 대한 할인 프로모션이 구성된 경우

* 선택한 아이템 할인 설정이 있는 프로모션 코드가 적용된 경우

적용된 아이템 수준 프로모션이 없는 경우 빈 배열이 반환됩니다.

  - `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)
    보너스 아이템 유형입니다.
    Enum: "virtual_good", "virtual_currency", "bundle", "physical_good", "game_key", "nft"

  - `items.promotions.bonus.name` (string)
    보너스 아이템 이름입니다. physical_good 보너스 아이템 유형에는 사용할 수 없습니다.

  - `items.promotions.bonus.image_url` (string)
    보너스 아이템 이미지 URL입니다. physical_good 보너스 아이템 유형에는 사용할 수 없습니다.

  - `items.promotions.bonus.bundle_type` (string)
    보너스 번들 아이템 유형입니다. 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)
    true일 경우 사용자는 아이템을 구매할 수 있습니다.

  - `items.vp_rewards` (array)
    아이템의 가치 포인트 리워드 목록입니다.

  - `items.vp_rewards.item_id` (integer)
    내부 고유 아이템 ID입니다.

  - `items.vp_rewards.sku` (string)
    고유 가치 포인트 ID입니다.

  - `items.vp_rewards.amount` (integer)
    가치 포인트의 금액입니다.

  - `items.vp_rewards.name` (string)
    가치 포인트 이름입니다.

  - `items.vp_rewards.image_url` (string)
    이미지 URL입니다.

  - `items.vp_rewards.is_clan` (boolean)
    값 포인트가 클랜 보상 체인에서 사용되는지 여부입니다.

  - `items.loyalty_rewards` (array)
    사용자가 아이템 구매 보상으로 받는 로열티 포인트입니다.

  - `items.loyalty_rewards.name` (string)
    로열티 포인트 이름입니다.

  - `items.loyalty_rewards.sku` (string)
    로열티 포인트 SKU. 예를 들어 로열티 포인트로 결제하는 주문을 생성할 때 다른 API 호출의 loyalty_point_sku 매개 변수에서 이 값을 전달합니다.

  - `items.loyalty_rewards.description` (string)
    로열티 포인트의 설명입니다.

  - `items.loyalty_rewards.image_url` (string,null)
    이미지 URL입니다.

  - `items.loyalty_rewards.amount` (integer)
    사용자가 아이템 구매 시 받는 로열티 포인트입니다.

  - `items.limits` (object,null)
    아이템 제한 사항입니다.

  - `items.limits.per_user` (object,null)
    사용자 한 명에 대한 아이템 제한 사항입니다.

  - `items.limits.per_user.total` (integer)
    사용자 한 명이 구매할 수 있는 최대 아이템 수량입니다.
    Example: 5

  - `items.limits.per_user.available` (integer)
    현재 사용자가 구매할 수 있는 남은 아이템 수량.
    Example: 3

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

  - `items.limits.per_user.limit_exceeded_visibility` (string)
    구매 한도에 도달한 후 다음 한도 재설정 때까지 카탈로그 내 아이템의 표시 여부를 결정합니다.

recurrent_schedule 배열에서 반복 한도 재설정이 구성된 아이템에 적용됩니다.

구매 한도에 도달한 후, 한도 초기화를 구성하지 않았다면limit_exceeded_visibility 값과 관계없이 해당 아이템은 카탈로그에 표시되지 않습니다.

사용 가능한 값: - show - 구매 한도에 도달한 이후에도 카탈로그 검색 API 호출 시 해당 아이템이 반환됩니다. 클라이언트 측 카탈로그 검색 API 호출에서 한도에 도달하면, 해당 아이템은 can_be_bought: false 플래그와 함께 반환됩니다. 다음 재설정 날짜는 reset_next_date에 반환됩니다. - hide - 구매 한도에 도달한 후, 한도가 재설정될 때까지 해당 아이템은 카탈로그 검색 API 호출에서 반환되지 않습니다.
    Enum: "show", "hide"

  - `items.limits.per_item` (object,null)
    한 개 아이템에 대한 아이템 제한 사항입니다.

  - `items.limits.per_item.total` (integer)
    모든 사용자가 구매할 수 있는 최대 아이템 수량.
    Example: 5

  - `items.limits.per_item.available` (integer)
    모든 사용자가 구매할 수 있는 남은 아이템 수량.
    Example: 3

  - `items.periods` (array,null)
    아이템 판매 기간입니다.

  - `items.periods.date_from` (string)
    지정된 아이템을 판매할 수 있는 날짜입니다.
    Example: "2020-08-11T10:00:00+03:00"

  - `items.periods.date_until` (string,null)
    지정된 아이템을 판매할 수 없게 되는 날짜입니다. null일 수 있습니다.
    Example: "2020-08-11T20:00:00+03:00"

  - `rewards` (object)

  - `rewards.bonus` (array)

  - `rewards.bonus.item` (object)

  - `rewards.bonus.item.sku` (string)
    고유 아이템 ID입니다. SKU는 소문자 및 대문자 라틴 영숫자, 마침표, 대시 및 밑줄만 포함할 수 있습니다.
    Example: "game_01"

  - `rewards.bonus.item.name` (string)
    아이템 이름입니다.
    Example: "Game name"

  - `rewards.bonus.item.type` (string)
    아이템 유형. 가능한 값:virtual_good - 가상 아이템virtual_currency - 가상 통화bundle - 번들unit - 게임 키 패키지
    Example: "unit"

  - `rewards.bonus.item.description` (string)
    아이템 설명입니다.
    Example: "Game description"

  - `rewards.bonus.item.image_url` (string)
    이미지 URL입니다.
    Example: "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png"

  - `rewards.bonus.item.unit_items` (array)
    플랫폼별 게임 키 모음. 아이템 유형이 unit(bonus.item.type = 'unit')인 경우에만 사용됩니다. 게임 키 패키지에 플랫폼별 키가 포함되어 있는 경우, 사용자는 그중 하나를 보너스로 선택할 수 있습니다.

  - `rewards.bonus.item.unit_items.sku` (string)
    고유한 플랫폼별 게임 키 패키지 ID. 허용된 문자: a–z, A–Z, 0–9, 맞침표(.), 하이픈(-), 밑줄(_). bonus.item.​sku 및 bonus.item.unit_items.drm_sku 값을 결합합니다. 예를 들어, bonus.item.​sku = 'cool_game' 및 bonus.item.unit_items.drm_sku = 'steam'인 경우, 값은 cool_game_steam이 됩니다.
    Example: "cool_game_steam"

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

  - `rewards.bonus.item.unit_items.type` (string)
    아이템이 게임 키인지 여부를 나타냅니다.
    Enum: "game_key"

  - `rewards.bonus.item.unit_items.name` (string)
    게임 타이틀입니다.
    Example: "Awesome Game"

  - `rewards.bonus.item.unit_items.drm_name` (string)
    DRM 이름입니다.
    Example: "Steam"

  - `rewards.bonus.item.unit_items.drm_sku` (string)
    플랫폼별 게임 키를 나타내기 위해 접미사로 사용되는 고유한 DRM ID. 허용되는 문자: a–z, A–Z, 0–9, 맞침표(.), 하이픈(-), 밑줄(_).
    Example: "steam"

  - `rewards.bonus.quantity` (number)
    아이템 수량입니다.

  - `rewards.discount` (object,null)
    퍼센트 할인입니다.
이 퍼센트를 사용하여 계산한 값을 사용하여 장바구니 항목의 가격을 낮추어 계산한 다음 소수점 이하 2자리로 반올림합니다.

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

  - `rewards.discounted_items` (array,null)
    프로모션 코드로 할인한 아이템의 목록입니다.

  - `rewards.discounted_items.sku` (string, required)
    아이템 SKU입니다.

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

  - `rewards.discounted_items.discount.percent` (string, required)
    퍼센트 할인입니다.

이 퍼센트를 사용하여 계산한 값을 사용하여
장바구니 아이템의 가격이 낮아지게 한 다음
소수점 이하 2자리로 반올림합니다.

  - `rewards.is_selectable` (boolean)
    true인 경우 사용자는 프로모션 코드를 사용하기 전에 보너스를 선택해야 합니다.

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