Promo codes and coupons

Promo codes

Promo codes and coupon promotions are a marketing tool used to provide users with codes for obtaining bonus items. Users can enter the promo code into a special field in the catalog to redeem it.

Promo codes redeemable at the time of purchase, and coupons — after the user enters a code.

Setting up a personalization is available with any authentication type: through User ID or Xsolla Login.

User flow

The user goes to the landing page with Promocodes block.

The user clicks Log in and authorizes through User ID or Xsolla Login.
The user enters a code in a special field in the interface and clicks a button to the right of the field.

Opens a modal window:
- when activating a promo code – with info about discounts and bonuses;
- coupon redemption – with info about discounts and bonuses that user already received.

If the code is incorrect, under the field for entering the code, the error will be described.
Example: The redemption limit has been reached.

For promo codes promotion:
1. An updated catalog is displayed with discounts and bonus items using a promo code.

Before making a purchase, the user can cancel the promotional code, then the catalog will be updated and displayed without discounts and bonuses for the promo code. In this case, the promo code is not considered redeemed.

User makes a purchase, after it promo code will be considered redeemed.

If bonus items are attached to the promo code, they are credited to the user.

How to get it

To add a code redemption block to your website:

Create promotions with promo codes or coupons in the LiveOps > Promotions section.
Add a code input field to your website created with Xsolla in the Storefronts > Websites section.

Refer to the corresponding tab in the How it works section for detailed information on setting up coupons and 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.

To set up regional restrictions for a campaign, contact us at [email protected].

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 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 or Redeem promo code calls. The user won’t be able to obtain any of the items from the promo code.

You can also set up coupon promotions 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

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:

The price of a virtual item is $10. In Publisher Account, the following promotions have been created for the virtual items:

The price of a virtual item is $10. In your account, the following promotions have been created for the virtual items:

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

If you want to create a promotion with bonus items, you need first configure these items and then proceed to the promotion setup.

To create items manually in your project in Publisher Account, go to the Items catalog > All items section. Detailed information about this and other methods for creating items is available in the Items catalog documentation section.

Set up in Publisher Account

You also can set up the promotion using a canvas.

To create a new campaign with promo codes:

In your project in Publisher Account, go to the LiveOps > Promotions section.
On the Promotions tab, click Create promotion.

Specify Promotion name.
In the Promotion type drop-down list, select Promo code.
In the External ID field, specify a promotion ID used for managing promotions via API calls.
To apply a discount to any item or the entire cart when a promo code is redeemed:

1. Set the Discount on purchase toggle to On.

1. In the Discount amount field, specify the discount percentage.

To apply a discount to specific items when a promo code is redeemed:

1. Set the Discount on selected items toggle to On.

1. In the Discount amount field, specify the discount percentage.

1. In the Item type drop-down list, select the type of item that will be discounted upon promo code redemption.

1. Select the items.

To provide bonus items when a promo code is redeemed:

1. Set the Bonus items toggle to On.

1. In the Select bonus items drop-down list, select the type of an item to be granted to a user upon promo code redemption.

1. Select the items to be provided upon promo code redemption.

1. For virtual items, specify the quantity for each item.

1. 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.

1. Click Next.

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.

Configure promo code redemption limits:

1. 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.

1. 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.

1. 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.

1. Click Next.

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.

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.

Click Next.
Review the campaign settings.
Click Save and exit.

To add promo codes to a campaign:

In your project in Publisher Account, go to the LiveOps > Promotions section.
In the row with promo code promotion, click ••• and choose Edit promotion in the drop-down list.

Go to the Codes tab.
To generate codes automatically:

1. In the Code string format drop-down list, select Auto-generated.

1. Specify the number of codes to generate and click Generate.

To add codes manually:

1. In the Code string format drop-down list, select Manually entered.

1. Enter the promo code and click Create.

1. Repeat the previous step to add the required number of codes.

Download a CSV file with the codes (optional).

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 [email protected].

To make the campaign available to users, you must activate it. To do this:

In your project in Publisher Account, go to the LiveOps > Promotions section.
In the row with promo code promotion, click ••• and choose Edit promotion in the drop-down list.
In the drop-down list in the upper-right corner, select Activate promotion.

Set up via API

When you configure a promotion via API, you can specify a fractional discount amount.

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.
Activate a promotion with promo code.	Activate promo code promotion.
Edit a promotion.	Update promo code promotion with new promotion options. Promotions editing is also available for promotions with Active status.
Deactivate promotion.	Deactivate promo code promotion.
Set up promotion validity periods.	Create promo code promotion or Update promo code promotion. 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.

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

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
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.
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. 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 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. 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).	Redeem promo code. You need to pass the promo code in the `coupon_code` request parameter.

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 server-side API call.

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.

Game keys are sent to the user via email or to the entitlement system.

Promo code usage on website created with Xsolla

You can only add the coupon and promo code redemption feature to websites created using the Web Shop template.

To display the code entry field on your website:

Open your project in Publisher Account and go to the Storefronts > Websites section.

Open the project in your account and go to the Web Shop section.
In the Sites section, select your site and click Open Site Builder.

If your site includes multiple pages, select the one you need:
1. Click the current page title at the top of the builder.
2. Select the necessary page from the drop-down list.
In the main area of the builder, choose a place where you want to add a new block and click Add block.
Select the Promo codes block.
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.

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.

To apply changes, publish the website:

1. In the upper-right corner of the site builder, click Publish.

1. Check the boxes next to the pages you want to publish.

1. Click Publish.

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.
The main page is published or selected for publication. You cannot publish child pages before the main page.

How it works

Coupon campaigns are a marketing tool designed to attract potential users to your product and drive sales. When a user redeems a coupon, they receive one or more bonus items. The following items can be used as rewards:

virtual currency packages
game keys
virtual items
bundles

A coupon contains a unique code. To redeem a coupon, the user should enter the code within the game client or a game’s store, including the Web Shop.

Key features:

Setting the total number of redemptions within a campaign.
Setting the number of redemptions per user within a campaign.
Multiple generation of codes for coupons.
Applying regional restrictions for campaigns and items linked to a coupon.

To set up regional restrictions for a campaign, contact us at [email protected].

Limitations:

If game keys are used as a bonus item, the key will be sent to the user via email or to the entitlement system after redemption. If the campaign runs out of keys, the user will not be able to redeem the coupon.
If regional restrictions are applied to a coupon campaign, users from those regions won’t be able to redeem the coupon.
If a coupon includes at least one bonus item with a regional restriction, a user from that region won’t be able to receive the item using this coupon.

Example: A shield and sword are offered as a bonus with the coupon. The shield has a regional restriction and is available for purchase only in the US. If a user outside the US enters the coupon code, an error will be returned in the response to the Verify promotion code or Redeem coupon code calls. The user will not be able to obtain any of the items from the coupon.

You can also set up promo codes promotions 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:

An authorized user goes to the store.
The user enters the coupon code.
Xsolla returns a list of available bonus items for the coupon (optional).
The user selects bonuses (optional).
The user redeems the coupon.
The items linked to the coupon are credited to the user in the same way as a regular purchase.

Set up coupon campaign

Prerequisites

Before setting up a coupon campaign, you must configure the items that will be issued as bonuses.

Set up in Publisher Account

You also can set up the promotion using a canvas.

To create a new coupon campaign:

In your project in Publisher Account, go to the LiveOps > Promotions section.
On the Promotions tab, click Create promotion.

Specify main promotion parameters:

1. Specify Promotion name.

1. In the Promotion type drop-down list, select Coupon.

1. In the External ID field, specify a promotion ID used for managing promotions via API calls.

1. In the Select bonus items drop-down list, select the type of an item to be granted to a user upon coupon redemption.

An item type is available for selection only if at least one item of that type has been created in your project.

1. Select the items to be granted to a user upon coupon redemption.

1. For virtual items, specify the quantity for each item.

1. 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.

You can select different types of items as bonuses. To switch between different item types, use the Select bonus items field. Information about all selected items is displayed in the List of bonus items area.

1. Click Next.

Configure coupon redemption limits:

1. To limit the total number of coupon redemptions across all users within a campaign, set the Limit total number of coupon redemptions toggle to On and specify the maximum number of redemptions.

1. To limit the number of coupons 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.

1. To limit the number of times any unique coupon code can be redeemed across all users, set the Limit number of unique coupon code redemptions toggle to On and specify the maximum number of redemptions for the coupon.

1. Click Next.

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.

Click Next.
Review the campaign settings.
Click Save and exit.

To add coupon codes to a campaign:

In your project in Publisher Account, go to the LiveOps > Promotions section.
In the row with coupon promotion, click ••• and choose Edit promotion in the drop-down list.

Go to the Codes tab.
To generate codes automatically:

1. In the Code string format drop-down list, select Auto-generated.

1. Specify the number of codes to generate and click Generate.

To add codes manually:

1. In the Code string format drop-down list, select Manually entered.

1. Enter the coupon code and click Create.

1. Repeat the previous step to add the required number of codes.

Download a CSV file with the codes (optional).

Coupon codes are case-sensitive. For example, winter123 and WINTER123 are treated as different coupons.

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 [email protected].

To make the campaign available to users, you must activate it. To do this:

In your project in Publisher Account, go to the LiveOps > Promotions section.
In the row with coupon promotion, click ••• and choose Edit promotion in the drop-down list.
In the drop-down list in the upper-right corner, select Activate promotion.

Set up via API

the required parameters
the parameters you want to change
all other parameters returned by the promotion retrieval call

To set up and manage coupon campaigns via API, use the following calls:

Task	API call
Create a promotion with a coupon.	Create coupon promotion.
Activate a promotion with a coupon.	Activate coupon promotion.
Edit a promotion.	Update coupon promotion with new promotion options. Promotions editing is also available for promotions with the Active status.
Deactivate a promotion with a coupon.	Deactivate coupon promotion.
Set up promotion validity periods.	Create coupon promotion or Update coupon promotion. 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 coupon promotion.

If you deactivate or delete an active promotion, it will no longer be available to users.

Set up coupon redemption in your application or website

Coupon redemption in your own UI

To allow users to redeem coupons in your application or website:

Implement the following elements in your UI:
- A field to enter the coupon code.
- A form to display coupon rewards.
- A button to redeem the coupon code.
Implement coupon logic using the following client-side API calls:

To call client-side Xsolla API endpoints, you can use ready-made SDK methods. For more information see:

Task API call

Check if the coupon is correct. Verify promotion code.

Redeem coupon. Redeem coupon code.

Get a list of game distribution platforms to display to the user if a game key is provided as a coupon bonus.

Task	API call
Check if the coupon is correct.	Verify promotion code.
Redeem coupon.	Redeem coupon code.
Get a list of game distribution platforms to display to the user if a game key is provided as a coupon bonus.	Get coupon rewards. 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 platform.

Get coupon rewards.

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 platform.

To additionally check how many more times a user can apply a coupon within a campaign, use the Get coupon limit for specified user server-side API call.

Ensure that items are correctly granted to the user upon coupon 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 coupon are granted to the user in the same way as a standard purchase.

Game keys are sent to the user via email or to the entitlement system.

Coupon redemption on website created with Xsolla

You can only add the coupon and promo code redemption feature to websites created using the Web Shop template.

To display the code entry field on your website:

Open your project in Publisher Account and go to the Storefronts > Websites section.

Open the project in your account and go to the Web Shop section.
In the Sites section, select your site and click Open Site Builder.

If your site includes multiple pages, select the one you need:
1. Click the current page title at the top of the builder.
2. Select the necessary page from the drop-down list.
In the main area of the builder, choose a place where you want to add a new block and click Add block.
Select the Promo codes block.
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.

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.

To apply changes, publish the website:

1. In the upper-right corner of the site builder, click Publish.

1. Check the boxes next to the pages you want to publish.

1. Click Publish.

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.
The main page is published or selected for publication. You cannot publish child pages before the main page.

Promo code promotions allow users to purchase items at a discount and receive bonus items configured in the promotion. The field for entering a promo code can be displayed in the catalog or the cart. Only one promo code can be applied to a purchase.

You can set up different types of promotions for an item: discounts, promo codes, and bonuses.

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 does not matter.

For example:

The price of a virtual item is $10. In Publisher Account, the following promotions have been created for the virtual items:

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% and will be $6.84.

Create new promo code promotion

To create a promo code promotion:

In your project in Publisher Account, go to the LiveOps > Canvas section.

In the project in your account for mobile games, go to the Operation > LiveOps section.

Start creating a promotion in one of the following ways:
- Option 1:

1. 1. In the toolbar, click the icon.
  2. In the promotion list area, click the + icon.

1. 1. Select promo codes and click Create.

- Option 2: In the toolbar, click the + icon and select Promo codes.

- Option 3: Open the context menu anywhere on the canvas and select Promo codes.

Specify the basic settings:
- Promotion name.
- External ID — a unique promotion ID used for managing promotions via API calls.
Define when the user can redeem a promo code by selecting one of the options in the Redemption timeframe field:
- Before purchase — the promo code can be redeemed without making a purchase. In this case, the user can only receive bonus items. Discount settings are not available for this option.
- Anytime — the promo code can only be redeemed during a purchase. In this case, the user can receive bonus items, discounts on specific items, and/or a discount on the entire cart.
Add bonus items:
1. Set the Bonus items toggle to active.
2. Click Select items.
3. In the window that opens, check the boxes next to the required items and specify their quantity.
4. Click Add items.

To add a discount to the entire purchase (optional, unavailable for the Before purchase redemption type):
1. Set the Apply discount to entire purchase toggle to active.
2. Specify the discount percentage.
To add a discount to specific items (optional, unavailable for the Before purchase redemption type):
1. Set the Apply discount on selected items only toggle to active.
2. Specify the discount percentage.
3. Click Select items.
4. In the window that opens, check the boxes next to the required items.
5. Click Add items.

Click Next.
Add conditions and limitations (optional):
1. To limit the total number of promo code redemptions, set the Promo code redemptions limit toggle to active and enter the required number.
2. To limit the number of redemptions per user, set the Promo code redemptions limit per user toggle to active and enter the required number.
3. To limit the number of redemptions per unique promo code, set the Unique promo code redemptions toggle to active and enter the required number.
Click Next.
Specify the promotion period.
Click Next.
Review the promotion settings.
To activate the promotion immediately (optional), set the Create in Active status toggle to active.
Click Create.

To add the created promo code promotion to the site (optional):
1. Open the site in the builder by clicking Open or Open in Site Builder on the banner in the editing form.
2. Follow the instructions from the Set up promo code usage in your application or website section.

Promo code promotions are created in the deactivated state by default and don’t contain any promo codes for redemption.

On the canvas, visual links are displayed between the promotion card and the items in the promotion.

To manage their display, click the → or ← icon to the right of any promotional item card, next to the icon. If an item is included in multiple promotions, only one link can be displayed at a time.

When setting up a promotion via the canvas, the following options are not available:

Setting up a promotion with game keys.
Setting a discount with fractional percentages.
Setting up a promotion with no end date.

Advanced options for configuring promo code promotions are available via Publisher Account and API calls.

Add promo codes

To add promo codes to promotion:

Open the promotion for editing.

Click Add promo codes.
Add the required number of promo codes:
- To generate promo codes automatically:
  1. Select Auto-generated and specify the number of promo codes.
  2. Click Generate.
- To add a promo code manually:
  1. Select Manually entered.
  2. Click Create.

Promo codes are case-sensitive. For example, winter2021 and WINTER2021 are different promo codes.

To export a file with the promo code list (optional), click Download CSV.

Activate promotion

You can activate the promotion in following ways:

From the promotion card:

From the promotions list:

While editing the promotion:

Active promotions can’t be edited. To change a promotion’s settings, first deactivate it.

Set up promo code usage in your application or website

Promo code usage on your UI

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
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.
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. 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 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. 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).	Redeem promo code. You need to pass the promo code in the `coupon_code` request parameter.

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 server-side API call.

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.

Game keys are sent to the user via email or to the entitlement system.

Promo code usage on website created with Xsolla

You can only add the coupon and promo code redemption feature to websites created using the Web Shop template.

To display the code entry field on your website:

Open your project in Publisher Account and go to the Storefronts > Websites section.

Open the project in your account and go to the Web Shop section.
In the Sites section, select your site and click Open Site Builder.

If your site includes multiple pages, select the one you need:
1. Click the current page title at the top of the builder.
2. Select the necessary page from the drop-down list.
In the main area of the builder, choose a place where you want to add a new block and click Add block.
Select the Promo codes block.
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.

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.

To apply changes, publish the website:

1. In the upper-right corner of the site builder, click Publish.

1. Check the boxes next to the pages you want to publish.

1. Click Publish.

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.
The main page is published or selected for publication. You cannot publish child pages before the main page.

Thank you for your feedback!

We’ll review your message and use it to help us improve your experience.

Last updated: August 16, 2026

Found a typo or other text error? Select the text and press Ctrl+Enter.

Contents

User flow
How to get it
How it works
General information
User flow
Rules for applying discounts
Set up campaign with promo codes
Set up in Publisher Account
Set up via API
Set up promo code usage in your application or website
Promo code usage on your UI
Promo code usage on website created with Xsolla
How it works
Set up coupon campaign
Prerequisites
Set up in Publisher Account
Set up via API
Set up coupon redemption in your application or website
Coupon redemption in your own UI
Coupon redemption on website created with Xsolla
Create new promo code promotion
Add promo codes
Activate promotion
Set up promo code usage in your application or website
Promo code usage on your UI
Promo code usage on website created with Xsolla