Promo codes

How it works

Promo codes are a marketing tool used to provide users with codes for obtaining additional benefits. Users can enter the promo code into a special field in the catalog or cart to activate it.

After activating a promo code, the user can receive:

  • a discount that is applied to the entire purchase or to specific items
  • a bonus item:

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

Main features:

  • providing as a reward for a promo code either a discount, bonus item, or both
  • limiting the total number of redemptions of the promo code within the campaign
  • limiting the number of promo code redemptions for one user within the campaign
  • generating multiple promo codes
  • setting regional restrictions on request
  • adding a bonus item to the cart after applying the promo code
  • applying a discount to the items after using a promo code

Restrictions:

  • Only one promo code can be applied to the cart.
  • To get a discount or bonus, the user should pay for the items in the cart
  • If a promo code 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 promo code. The shield has a regional restriction and is available for purchase only in the USA. If a user outside the USA enters the promo code, an error will be returned in the response to the Verify promotion code or Redeem promo code methods. The user will not be able to obtain any of the items from the promo code.

Integration flow

Note

The scenarios decribed below are for an authorized user.

For unauthorized users, the maximum number of times a promotion can be used is always displayed. To display the remaining number of times a promotion can be used to the user (subject to the current limit), pass user authorization data when you request the item catalog using the methods of the Catalog subsection from the Virtual Items & Currency method group.

Notice

You can set up different types of promotions for an item: discounts, coupons, 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.

How to get it

Prerequisites

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

Setting up a promotion with a promo code

You can set up promo code 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 promo code and redeem the promo code.

Set up via Publisher Account

If you set up promo code 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 promo code promotions with an Active status isn’t currently available in Publisher Account.

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

Note
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 and open the Promotions section.
  1. Click Create promotion.
  1. Specify the following parameters:
    • Enter the promotion name.
    • Choose Promo codes as the promotion type.
  2. Create an External ID — a unique promotion identifier used to manage promotions via API methods.
  3. Specify the discount percentage for the promo code. The discount can be applied to the entire purchase or to specific items.
  4. Choose the bonus items that the user receives when they redeem a promo code:
  1. Specify the total number of redemptions and number of redemptions per user.
  1. Specify the duration of the campaign.
  1. Check the settings and save the promotion.
  2. Go to the promotion editing menu.
  3. In the Codes tab, choose how the promo codes are generated.
  4. Generate the promo code or enter it manually.
  5. Save changes.
  6. Activate the promotion.

Promo code with a virtual currency package

To create a promo code with a virtual currency package:
  1. Create a virtual currency package.
  2. Specify a virtual currency package as a bonus item.

Promo code with a virtual item

To create a promo code with a virtual item:

  1. Create a virtual item.
  2. Specify a virtual item as a bonus item.

You can choose one or several items with different SKUs for one promo code including bundles and time-limited items.

Promo code with a game key

To create a promo code with a game key:
  1. Create a game key package.
  2. Specify the SKU of the created game key package as a bonus and the method of choosing the platform for which the game is purchased:

    • The promo code is generated for the already set specific platform.
    • The user selects a specific platform when using promo codes.

You can choose several keys with different SKUs for one promo code.

Generating promo codes

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

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 promo codes promotions, you can use the methods from the Promo Codes subsection of the Promotions method group.

Promotion setup:

TaskAPI method
Create a promotion with a promo codeCreate promo code promotion
Activate promotion with promo codeActivate promo code promotion
Edit promotionUpdate promo code promotion with new promotion options. Promotions editing is also available for promotions with Active status
Deactivate promotionDeactivate promo code promotion
Set up an indefinite promotionCreate promo code promotion or Update promo code promotion. Pass the “date_end”:null parameter to the specified method.
Checking and applying the promo code:
TaskAPI method
Check if the promo code is correctVerify promotion code
Redeem promo codeRedeem promo code
Get a list of game distribution platforms to display to the user if a game key is provided as a bonus for a promo codeGet promo code rewards
Limits management:
TaskAPI method
Get the remaining number of uses of a promo code for a specific userGet promo code limit for specified user
Increase the remaining number of uses of the promo code for a specific userIncrease promo code limit for specified user
Set a new limit on the use of a promo code for a specific userSet promo code limit for specified user
Decrease the remaining number of uses of the promo code for a specific userDecrease promo code limit for specified user

If the promo code input field is placed in the catalog, after entering the promo code, request the item catalog for the user again by passing the promo code in the promo_code parameter in the methods for building the catalog from the Catalog subsection.

If you are implementing a quick purchase of one item using the Create order with specified item method, pass information about the promo code in the promo_code parameter. This allows the purchase to be made with the promo code applied.

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!