Promo codes
How it works
Promotions with promo codes allow users to purchase items at discounted prices and receive bonus items according to campaign settings. The promo code entry field can be displayed in the catalog or the cart.
Main difference is that promo codes are redeemed during a purchase, coupons are redeemed independently with no purchase requirement.
- 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
The scenarios described 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.
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
- Register in Publisher Account.
- 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:
- via Publisher Account
- via API methods
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:
- virtual currency packages
- virtual items (including time-limited items)
- game keys
- bundles
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.
- Open your project in Publisher Account.
- In the side menu, click Store and open the Promotions and rewards section.
- Click Create promotion.
- Specify the following parameters:
- Enter the promotion name.
- Choose Promo codes as the promotion type.
- Create an External ID — a unique promotion identifier used to manage promotions via API methods.
- Specify the discount percentage for the promo code. The discount can be applied to the entire purchase or to specific items.
- Choose the bonus items that the user receives when they redeem a promo code:
- no reward
- virtual currency package
- virtual item (one or more, including bundles and time-limited items)
- game key
- Specify the total number of redemptions and number of redemptions per user.
- Specify the duration of the campaign.
- Check the settings and save the promotion.
- Go to the promotion editing menu.
- In the Codes tab, choose how the promo codes are generated.
- Generate the promo code or enter it manually.
- Save changes.
- Activate the promotion.
Promo code with a virtual currency package
To create a promo code with a virtual currency package:- Create a virtual currency package.
- Specify a virtual currency package as a bonus item.
Promo code with a virtual item
To create a promo code with a virtual item:
- Create a virtual item.
- 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:- Create a game key package.
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.
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.
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:
| Task | API method |
|---|---|
| Create a promotion with a promo code | Create promo code promotion |
| Activate promotion with promo code | Activate promo code promotion |
| Edit 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 an indefinite promotion | Create promo code promotion or Update promo code promotion. Pass the “date_end”:null parameter to the specified method. |
| Task | API method |
|---|---|
| Check if the promo code is correct | Verify promotion code |
| Redeem promo code | Redeem 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 code | Get promo code reward |
| Task | API method |
|---|---|
| Get the remaining number of uses of a promo code for a specific user | Get promo code limit for specified user |
| Increase the remaining number of uses of the promo code for a specific user | Increase promo code limit for specified user |
| Set a new limit on the use of a promo code for a specific user | Set promo code limit for specified user |
| Decrease the remaining number of uses of the promo code for a specific user | Decrease 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.
Found a typo or other text error? Select the text and press Ctrl+Enter.
