How it works

Coupons 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 or cart to redeem it.

After redeeming a promo code, the user can receive a bonus item:

  • game key
  • virtual currency package
  • virtual item including a bundle or time-limited items

Main features:

  • limiting the total number of redemptions of the coupon within the campaign
  • limiting the number of coupon redemptions for one user within the campaign
  • generating multiple coupon codes
  • applying regional sale restrictions for promotions and items that are linked to a coupon


  • If game keys are attached as bonus items to a coupon, after the coupon is redeemed, the key will be sent to the user’s email address. 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 promotion, users from that region will not be able to redeem the coupon.
  • If the coupon includes an item with regional sale restrictions, a user from a region where these items are unavailable won’t be able to receive these items.
    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 USA. If a user outside the USA enters the coupon code, an error will be returned in the response to the Verify promotion code or Redeem coupon code methods. The user will not be able to obtain any of the items from the coupon.

Integration flow

To redeem the coupon and receive the bonus items, the user must be authorized.
  1. In your store, display a field where the user can enter the coupon code.
  2. Use the Verify promotion code method to validate the entered coupon code.
  3. Use Redeem coupon code method to redeem coupon. If a game key is provided as a bonus, it is delivered to the user's email address.

How to get it


  1. Register in Publisher Account.
  2. Connect the Store and set up Virtual Items and Virtual Currency modules.

Setting up a promotion with a coupon

You can set up coupon promotions in one of the following ways:

In any option for setting up a promotion, it is necessary to implement calls to API methods to check the correctness of the coupon code and redeem the coupon code.

Set up via Publisher Account

If you set up bonus promotions via Publisher Account, you can:

  • set up the promotion’s validity period
  • limit the number of times the promotion can be used by the user
  • set up promotions that apply to any types of items:

Editing coupon promotions with an Active status isn’t currently available in Publisher Account.

You can use API methods to enhance your coupon promotions configuration options.

New promotions are inactive by default. ​​To activate your promotion, edit the promotion, and in the top right corner of the drop-down list, select Activate promotion.
To set up a promotion via Publisher Account:
  1. Open your project in Publisher Account.
  2. In the side menu, click Store.
  3. In the Promotions panel click:
    • Connect – if you don’t have promotions
    • Configure – if you previously connected promotions
  1. Click Create promotion.
  1. Specify the following parameters:
    1. Enter the promotion name.
    2. Choose Coupon as the promotion type.
    3. Create an External ID — a unique promotion identifier used to manage promotions via API methods.
    4. Choose the bonus item that the user receives when they redeem a coupon:
  1. Specify the total number of redemptions and the number of redemptions per user.
  1. Set the campaign start and end dates.
  1. Check the settings and save the promotion.
  1. Go to the promotion editing menu.
  2. In the Codes menu, choose the method for how the coupons are generated.
  3. Generate the coupon code or enter it manually.
  4. Save changes.
  5. Activate the promotion.

Coupon with a virtual currency package

You should specify the currency package for a virtual currency package coupon. To create a virtual currency package:
  1. Go to the Virtual currency module settings and specify the following parameters:
    • Image
    • SKU
    • Currency name
    • Price of one unit of virtual currency
    • Default currency
  2. Create a required number of currency packages and specify the following parameters for every one of them:
    • Image
    • SKU
    • Name
    • Description
    • Used currency
    • Amount of currency in a package
    • Price
    • Default currency
  3. Enable the currency packages display in Store.

Coupon with a game key

You should specify a game key SKU and DRM info for a game key coupon. There are 2 options:
  • Generate coupons for the already set DRM. The parameter is set when generating coupons.
  • Choose a DRM when using a coupon.

Coupon with virtual items

You should specify the virtual item SKU and its quantity for a virtual items coupon. You can choose one or several items with different SKUs for one coupon including bundles and time-limited items.

Generating coupons

A campaign may include one or several coupons. The coupon format has 2 options:
  1. Manually entered string — suitable for a campaign with only one coupon that can be used many times (maximum is 128 characters).
  2. Generated string — line of numerals and Latin symbols (10 characters). Suits the campaign with many coupons.
You can generate coupons in the promotion editor after creating a coupon promotion. You can generate a code multiple times. Uploading the manually entered codes is made on demand via email to Xsolla.
The coupon code is case sensitive. For example, winter2021 and WINTER2021 are 2 different coupons.

Regional restrictions

Regional restrictions apply to the whole promotion campaign. The regional restrictions are applied on demand via email to Xsolla.

Set up via API methods

To work with coupon code promotions, you can use the methods from the Coupons subsection of the Promotions method group.

Promotion setup:

TaskAPI method
Create a promotion with a couponCreate coupon promotion
Activate promotion with couponActivate coupon promotion
Edit promotionUpdate coupon promotion with new promotion options. Promotions editing is also available for promotions with Active status
Deactivate promotionDeactivate coupon promotion
Set up an indefinite promotionCreate coupon promotion or Update coupon promotion. Pass the “date_end”:null parameter to the specified method.
Checking and applying the promotional code:
TaskAPI method
Check if the coupon is correctVerify promotion code
Redeem couponRedeem coupon code
Get a list of game distribution platforms to display to the user if a game key is provided as a bonus for a couponGet coupon rewards
Limits management:
TaskAPI method
Get the remaining number of uses of a coupon for a specific userGet coupon limit for specified user
Increase the remaining number of uses of the coupon for a specific userIncrease coupon limit for specified user
Set a new limit on the use of a coupon code for a specific userSet coupon limit for specified user
Decrease the remaining number of uses of the coupon code for a specific userDecrease coupon limit for specified user
Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!
Last updated: January 22, 2024

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

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!