# Promo codes ## How it works ### General information Promotions with promo codes are a marketing tool designed to boost purchase conversion rates and increase the average check. Once a promo code is applied to an order, the user can receive: * a discount applied to the entire purchase or specific items * bonus items, including: * virtual currency packages * game keys * virtual items * bundles Key features: * Flexible bonus configuration. You can set up a single bonus type (discount on purchase, discount on selected items, or a bonus item) or any combination of them. * Setting the total number of redemptions within a campaign. * Setting the number of redemptions per user within a campaign. * Multiple generation of promo codes. * Applying regional restrictions for campaigns and items linked to a promo code. > [!NOTE] > To set up regional restrictions for a campaign, contact us at [igs@xsolla.com](mailto:igs@xsolla.com). Limitations: * Only one promo code can be applied to the purchase. * To receive a discount or bonus item, the user must pay for the purchase. * Discounts are not applied to prices specified in virtual currency. For items with both real and virtual currency prices, discounts apply only to the real currency price. * If game keys are used as a bonus item, the key will be sent to the user via email or to the [entitlement system](/sell-games/how-to/entitlement-system/) after redemption. If the campaign runs out of keys, the user will not be able to redeem the promo code. * If regional restrictions are applied to a promo code campaign, users from those regions won’t be able to redeem the promo code. * If a promo code includes at least one bonus item with a regional restriction, a user from that region won’t be able to redeem this promo code. **Example:** A shield and sword are offered as a bonus with the promo code. The shield has a regional restriction and is available for purchase only in the US. If a user outside the US enters the promo code, an error will be returned in the response to the [Verify promotion code](/api/liveops/promotions-common/verify-promotion-code/) or [Apply promo code](/api/liveops/promotions-promo-codes/redeem-promo-code/) calls. The user won’t be able to obtain any of the items from the promo code. > [!NOTE] > You can also set up [coupon promotions](/liveops/promotion-tools/coupons/) for your store. > > Key differences: > > * A coupon allows a user to receive only bonus items. A promo code can provide bonus items, a discount on a specific item, or a discount on the entire cart. > * Promo codes are redeemed during a purchase (at checkout), whereas coupons are redeemed after the user enters and applies the code. ### User flow **Tab: Using a promo code in the catalog UI** 1. A user goes to the store. 2. The user enters and applies the promo code. 3. Xsolla validates the promo code and checks for any redemption limits within the promotion. > [!NOTE] > If an unauthorized user enters a promo code, Xsolla won’t be able to validate per-user redemption limits. In this case, the catalog will display items based on the total campaign usage limits. > > To display the catalog considering active limits for a specific user, you must pass user authorization data when requesting the item catalog. To do that, use endpoints from the **Catalog** subsection in the [Virtual items & currency](/api/catalog/virtual-items-currency-catalog/get-virtual-items/) group. 4. The user sees the updated catalog, including discounts and bonus items that can be granted by the promo code. 5. The user adds items to the cart or proceeds to purchase a selected item directly. 6. The user completes the payment, after which the promo code is considered redeemed. 7. If the promo code includes linked items, they are granted to the user in the same way as a regular purchase. **Tab: Using a promo code in the cart UI** 1. An authorized user goes to the store. 2. The user adds items to the cart. 3. In the cart UI, the user enters and applies the promo code. 4. Xsolla validates the promo code and checks for any redemption limits within the promotion. 5. The total cost of the items in the cart is recalculated, and bonus items are added. 6. The user completes the payment, after which the promo code is considered redeemed. 7. If the promo code includes linked items, they are granted to the user in the same way as a regular purchase. > [!NOTE] > The user can cancel the promo code application before completing the payment. ### Rules for applying discounts If several promotions are valid for an item at the time of purchase, discounts are applied to the item one by one. The order in which discounts are applied doesn’t matter. **Example:** **Audience: all other audiences** The price of a virtual item is $10. In Publisher Account, the following promotions have been created for the virtual items: **End of audience: all other audiences** **Audience: Mobile games, Free-to-play PC games, Premium PC games, Web games** The price of a virtual item is $10. In your account, the following promotions have been created for the virtual items: **End of audience: Mobile games, Free-to-play PC games, Premium PC games, Web games** * **Black Friday** discount promotion with a discount of 10% from November 4–30 * **Sale** discount promotion with a discount of 20% from November 15 – December 15 * promotion with a promo code for a 5% discount from November 4–30 If the item is purchased on November 20, both discount promotions and a promotion with a promo code are valid. The total cost of the virtual item is then calculated as (($10 - 10%) - 20%) - 5% = $10 × (100%-10%) × (100%-20%) × (100%-5%) = $10 × 0.9 × 0.8 × 0.95 and will be $6.84. ## Set up campaign with promo codes > [!NOTE] > If you want to create a promotion with bonus items, you need first configure these items and then proceed to the promotion setup. > > **Audience: all other audiences** > > To create items manually in your project in Publisher Account, go to the [Items catalog > All items](https://publisher.xsolla.com/0/projects/0/storefront/virtual-items) section. Detailed information about this and other methods for creating items is available in the [Items catalog](/items-catalog/) documentation section. > > **End of audience: all other audiences** > > **Audience: Free-to-play PC games** > > To create items manually in your project in the account, go to the [Item catalog > All items](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/virtual-items) section. Detailed information about this and other methods for creating items is available in the [Items catalog](/items-catalog/) documentation section. > > **End of audience: Free-to-play PC games** > > **Audience: Premium PC games** > > To create items manually in your project in the account, go to the [Item catalog > All items](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/virtual-items) section. Detailed information about this and other methods for creating items is available in the [Items catalog](/items-catalog/) documentation section. > > **End of audience: Premium PC games** > > **Audience: Web games** > > To create items manually in your project in the account, go to the [Item catalog > All items](https://xsolla.com/for/web-games/account/0/projects/0/storefront/virtual-items) section. Detailed information about this and other methods for creating items is available in the [Items catalog](/items-catalog/) documentation section. > > **End of audience: Web games** > **Audience: all other audiences** ### Set up in Publisher Account **End of audience: all other audiences** **Audience: Free-to-play PC games, Premium PC games, Web games** ### Set up in account **End of audience: Free-to-play PC games, Premium PC games, Web games** > [!NOTE] > You also can set up the promotion using a [canvas](/liveops/xlms/liveops-management/create-promo-code-promotion/). To create a new campaign with promo codes: **Audience: all other audiences** 1. In your project in Publisher Account, go to the [LiveOps > Promotions](https://publisher.xsolla.com/0/projects/0/storefront/promotions) section. **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. Open your project in the account and go to the [LiveOps > Promotions](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/promotions) section. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open your project in the account and go to the [LiveOps > Promotions](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/promotions) section. **End of audience: Premium PC games** **Audience: Web games** 1. Open your project in the account and go to the [LiveOps > Promotions](https://xsolla.com/for/web-games/account/0/projects/0/storefront/promotions) section. **End of audience: Web games** 2. On the **Promotions** tab, click **Create promotion**. ![create promotion](https://cdn.xsolla.net/developers/current/images/general/live-ops/create-promotion.svg) 3. Specify **Promotion name**. 4. In the **Promotion type** drop-down list, select **Promo code**. 5. In the **External ID** field, specify a promotion ID used for managing promotions via API calls. 6. To apply a discount to any item or the entire cart when a promo code is redeemed: a. Set the **Discount on purchase** toggle to **On**. b. In the **Discount amount** field, specify the discount percentage. 7. To apply a discount to specific items when a promo code is redeemed: a. Set the **Discount on selected items** toggle to **On**. b. In the **Discount amount** field, specify the discount percentage. c. In the **Item type** drop-down list, select the type of item that will be discounted upon promo code redemption. d. Select the items. 8. To provide bonus items when a promo code is redeemed: a. Set the **Bonus items** toggle to **On**. b. In the **Select bonus items** drop-down list, select the type of an item to be granted to a user upon promo code redemption. c. Select the items to be provided upon promo code redemption. For virtual items, specify the quantity for each item. For game keys, specify when the platform will be determined: - To pre-assign a specific platform (e.g., Steam), select **Select DRM during code generation** from the **Type of DRM selection** drop-down list. Then, select the platform from the **DRM** drop-down list. - To let the user choose, select **Player selects DRM at redemption** from the **Type of DRM selection** drop-down list. d. Click **Next**. > [!NOTE] > The discount for an order or specific items must be an integer and cannot exceed 99%. > When configuring discounts for specific items or bonus items, consider the following: > * An item type is available for selection only if at least one item of that type has been created in your project. > * You can configure items of different types. To switch between item types, use the item type selection field. 9. Configure promo code redemption limits: a. To limit the total number of promo code redemptions across all users within a campaign, set the **Limit total number of redemptions** toggle to **On** and specify the maximum number of redemptions. b. To limit the number of promo codes a single user can redeem within a campaign, set the **Limit total number of redemptions per user** toggle to **On** and specify the maximum number of redemptions per user. c. To limit the number of times any unique promo code can be redeemed across all users, set the **Limit number of unique promo code redemptions** toggle to **On** and specify the maximum number of redemptions for the promo code. d. Click **Next**. 10. Specify the promotion validity period: a time zone, start date, and end date. To create a promotion without an end date, check the **No end date** box. > [!NOTE] > To add another promotion validity period, click **+**. If a promotion has multiple validity periods, each must have an end date. The promotion ends at the last second of the specified minute. For example, if an end time is set to 12:00, the promotion runs until 12:00:59. > ![promotion validity period](https://cdn.xsolla.net/developers/current/images/general/live-ops/promotion-validity-period.svg) 11. Click **Next**. 12. Review the campaign settings. 13. Click **Save and exit**. To add promo codes to a campaign: **Audience: all other audiences** 1. In your project in Publisher Account, go to the [LiveOps > Promotions](https://publisher.xsolla.com/0/projects/0/storefront/promotions) section. **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. Open your project in the account and go to the [LiveOps > Promotions](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/promotions) section. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open your project in the account and go to the [LiveOps > Promotions](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/promotions) section. **End of audience: Premium PC games** **Audience: Web games** 1. Open your project in the account and go to the [LiveOps > Promotions](https://xsolla.com/for/web-games/account/0/projects/0/storefront/promotions) section. **End of audience: Web games** 2. In the row with promo code promotion, click **•••** and choose **Edit promotion** in the drop-down list. ![edit promotion](https://cdn.xsolla.net/developers/current/images/general/live-ops/promo-codes/edit-promotion.svg) 3. Go to the **Codes** tab. 4. To generate codes automatically: a. In the **Code string format** drop-down list, select **Auto-generated**. b. Specify the number of codes to generate and click **Generate**. 5. To add codes manually: a. In the **Code string format** drop-down list, select **Manually entered**. b. Enter the promo code and click **Create**. c. Repeat the previous step to add the required number of codes. 6. Download a CSV file with the codes (optional). > [!NOTE] > Promo codes are case-sensitive. For example, `winter123` and `WINTER123` are treated as different promo codes. > > You can add new codes to a campaign an unlimited number of times. However, the total number of added codes must not exceed 50,000. > > If you need to upload a large number of self-generated codes, contact us at [igs@xsolla.com](mailto:igs@xsolla.com). To make the campaign available to users, you must activate it. To do this: **Audience: all other audiences** 1. In your project in Publisher Account, go to the [LiveOps > Promotions](https://publisher.xsolla.com/0/projects/0/storefront/promotions) section. **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. Open your project in the account and go to the [LiveOps > Promotions](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/promotions) section. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open your project in the account and go to the [LiveOps > Promotions](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/promotions) section. **End of audience: Premium PC games** **Audience: Web games** 1. Open your project in the account and go to the [LiveOps > Promotions](https://xsolla.com/for/web-games/account/0/projects/0/storefront/promotions) section. **End of audience: Web games** 2. In the row with promo code promotion, click **•••** and choose **Edit promotion** in the drop-down list. 3. In the drop-down list in the upper-right corner, select **Activate promotion**. ![activate promotion](https://cdn.xsolla.net/developers/current/images/general/live-ops/promo-codes/activate-promotion.svg) ### Set up via API > [!NOTE] > When you configure a promotion via API, you can specify a fractional discount amount. > [!NOTE] > The list of parameters required when using the API calls for updating promotions doesn’t match the list of parameters returned by the API calls for retrieving promotions. When calling the API methods for updating promotions, you must pass: > - the required parameters > - the parameters you want to change > - all other parameters returned by the promotion retrieval call To set up and manage campaigns with promo codes via API, use the following calls: | Task | API call | |:------------------------------|:-------------------------------| | Create a promotion with a promo code. |[Create promo code promotion](/api/liveops/promotions-promo-codes/create-promo-code/). | | Activate a promotion with promo code. | [Activate promo code promotion](/api/liveops/promotions-promo-codes/activate-promo-code/).| | Edit a promotion. | [Update promo code promotion](/api/liveops/promotions-promo-codes/update-promo-code/) with new promotion options. Promotions editing is also available for promotions with **Active** status. | | Deactivate promotion. | [Deactivate promo code promotion](/api/liveops/promotions-common/deactivate-promotion/). | | Set up promotion validity periods. | [Create promo code promotion](/api/liveops/promotions-promo-codes/create-promo-code/) or [Update promo code promotion](/api/liveops/promotions-promo-codes/update-promo-code/). Pass the `promotion_periods` field as an array of objects where `date_from` defines the start, and `date_until` defines the end date of the validity period. To make the promotion indefinite, specify only one period and pass `“promotion_periods[0].date_until": null`. | | Delete a promotion. | [Delete promo code promotion](/api/liveops/promotions-promo-codes/delete-promo-code/). | > [!NOTE] > If you deactivate or delete an active promotion, it will no longer be available to users. ## Set up promo code usage in your application or website ### Promo code usage on your UI 1. In your application UI (in the catalog or cart), implement the following elements: * a promo code input field * UI elements to display promo code rewards and discounts * a selection form for promo code rewards (if applicable) * a button to apply the promo code 2. Implement the promo code logic using the following client-side API calls: | Task | API call | |:------------------------------|:-------------------------------| | Check if the promo code is valid. | [Verify promotion code](/api/liveops/promotions-common/verify-promotion-code/). | | Get a list of game distribution platforms to display to the user if a game key is provided as a promo code bonus. | [Get promo code rewards](/api/liveops/promotions-promo-codes/get-promo-code-rewards-by-code/).If the response returns `is_selectable=true`, for each item with `type=unit`, you must display a selection form for the elements in the `unit_items` object. In this form, the user can select only one element for each `unit` type.The `type=unit` parameter is passed for game keys. In this case, the user will need to select a game platform. | | Display the updated catalog considering discounts and bonus items from a promo code. | Use calls from the [Catalog](/api/catalog/virtual-items-currency-catalog/get-virtual-items/) subsection. You need to pass the promo code in the `promo_code` request parameter. | | Purchase a specific item directly (without adding it to the cart) and redeem a promo code. | [Create order with specified item](/api/catalog/payment-client-side/create-order-with-item/).You need to pass the promo code in the `promo_code` request parameter. | | Apply a promo code and update the cart content and total cost (apply discounts and add bonus items). | [Apply promo code](/api/liveops/promotions-promo-codes/redeem-promo-code/).You need to pass the promo code in the `coupon_code` request parameter. | > [!NOTE] > To additionally check how many more times a user can apply a promo code within a campaign, use the [Get promo code limit for specified user](/api/liveops/promotions-promo-codes/get-promo-code-user-limit/) server-side API call. 3. Ensure that items are correctly granted to the user upon promo code redemption. If you have already implemented an in-game store in your application or on your website, no additional setup is required. Items linked to a promo code are granted to the user [in the same way as a standard purchase](/virtual-goods/own-ui/client-side-token-generation/set-up-order-tracking/). > [!NOTE] > Game keys are sent to the user via email or to the [entitlement system](/sell-games/how-to/entitlement-system/). ### Promo code usage on website created with Xsolla > [!NOTE] > You can only add the coupon and promo code redemption feature to websites created using the [Web Shop](/solutions/web-shop/) template. To display the code entry field on your website: **Audience: all other audiences** 1. Open your project in Publisher Account and go to the [Storefronts > Websites](https://publisher.xsolla.com/0/projects/0/site-builder) section. 2. Click the pane of your site. **End of audience: all other audiences** **Audience: Mobile games** 1. Open the project in your account and go to the [Web Shop](https://xsolla.com/for/mobile-games/account/0/projects/0/site-builder) section. 2. Click the pane of your site. **End of audience: Mobile games** **Audience: Free-to-play PC games** 1. Open the project in your account and go to the [Storefronts > Website](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/site-builder) section. 2. Click the pane of your site. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open the project in your account and go to the [Storefronts > Website](https://xsolla.com/for/premium-pc-games/account/0/projects/0/site-builder) section. 2. Click the pane of your site. **End of audience: Premium PC games** **Audience: Web games** 1. Open the project in your account and go to the [Storefronts > Website](https://xsolla.com/for/web-games/account/0/projects/0/site-builder) section. 2. Click the pane of your site. **End of audience: Web games** 3. If your site includes multiple pages, select the one you need: a. Click the current page title at the top of the builder. b. Select the necessary page from the drop-down list. 4. In the main area of the builder, choose a place where you want to add a new block and click **Add block**. 5. Select the **Promo codes** block. 6. Customize the block appearance (optional): * Edit the block’s header and description text. * Set a custom background for the block. * Change the button style. * Edit the text for the coupon redemption button. > [!NOTE] > The default text for the coupon redemption or promo code activation button is **Redeem**. To change this text, double-click on it and enter the text that should be displayed on the site. 7. To apply changes, publish the website: a. In the upper-right corner of the site builder, click **Publish**. b. Check the boxes next to the pages you want to publish. c. Click **Publish**. > [!NOTE] > If site publication is not available, make sure all the conditions are met: > * There are no empty sections in builder (marked with a red indicator). > * [The licensing agreement with Xsolla has been signed](/get-started/work-in-pa/legal-aspects/). > * The main page is published or selected for publication. You cannot publish child pages before the main page.