Coupons

How it works

Coupon promotions are a marketing tool for getting new users and increasing sales. A player who uses a coupon gets a reward that is linked to it. The reward can include:

• virtual currency package
• game key
• virtual item

Every coupon has a code. To use a coupon, the user enters its code in the game, on the website, or in the mobile application.

Main features:

• Decide the general number of coupon redemptions for one campaign.
• Determine the number of coupon redemptions for one user in one campaign.
• Generate codes for coupons multiple times.
• Apply regional sale restrictions for promotions and items that are linked to a coupon.

Restrictions:

• If you link game keys to a coupon, one of them will be emailed to a player who redeems the coupon. If there are no keys left in the campaign, the player’s request to use a coupon will be declined.
• If the coupon includes a promotion with regional restrictions, the user from a restricted region can’t redeem it.
• If the coupon includes an item with regional sale restrictions, the user from a restricted region can’t get the items linked to this coupon.

User flow:

1. A user redeems a coupon.
2. The reward that is linked to a coupon is delivered to a user in one of the following ways:
   • directly to the inventory (virtual item or a virtual currency package)
   • via email (a game key)
   • directly to the entitlement system (a game key)

How to get it

Prerequisites

1. Create your Xsolla Publisher Account.
2. Connect Store to your project.

Integration flow

1. Set up a promotional campaign with coupons.
2. Use the methods of getting a coupon reward.
3. Use the methods of coupon redemption by code.

Set up campaign with coupons

1. Go to Store > Promotions and rewards in Publisher Account and create a promotion.
2. Specify necessary parameters:
   1. Enter the promotion title.
   2. Choose Coupons as a promotion type.
3. Choose the bonus item that the user receives when they redeem a coupon:
   1. Virtual currency package.
   2. Game key.
   3. Virtual item (one or several, including bundles and time-limited items).
4. Specify the total number of redemptions and the number of redemptions per user.
5. Set the campaign start and end dates.
6. Check the settings and save the promotion.
7. Go to the promotion editing menu.
8. In the Codes menu, choose the method for how the coupons are generated.
9. Generate the coupon code or enter it manually.
10. Save changes.
11. Activate the promotion.

Coupon with 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

• 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

Generating coupons

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.

Regional restrictions

Get coupon rewards

1. If the is_selectable=true value, you should show the form for choosing elements from the unit_items object for every item with type=unit element. In this form, the user chooses only one element for each unit type.

{
	"bonus": [{
		"item": {
			"sku": "xsollus_gold_edition",
			"name": "Xsollus: Gold Edition",
			"type": "unit",
			"description": null,
			"image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/9541470622d96a821a9a11ea7763ea4c.png",
			"unit_items": [{
				"sku": "xsollus_gold_edition_steam",
				"name": "Xsollus: Gold Edition (steam)",
				"type": "game_key",
				"drm_name": "Steam",
				"drm_sku": "steam"
			}, {
				"sku": "xsollus_gold_edition_playstation",
				"name": "Xsollus: Gold Edition (playstation)",
				"type": "game_key",
				"drm_name": "Playstation",
				"drm_sku": "playstation"
			}, {
				"sku": "xsollus_gold_edition_xbox",
				"name": "Xsollus: Gold Edition (xbox)",
				"type": "game_key",
				"drm_name": "XBox",
				"drm_sku": "xbox"
			}, {
				"sku": "xsollus_gold_edition_rockstar",
				"name": "Xsollus: Gold Edition (rockstar)",
				"type": "game_key",
				"drm_name": "Rockstar Games Launcher",
				"drm_sku": "rockstar"
			}]
		},
		"quantity": 1
	}, {
		"item": {
			"sku": "xsollus_bonus_pack_edition",
			"name": "Xsollus: Bonus Pack",
			"type": "unit",
			"description": null,
			"image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/aa2efd78dfd4e5dda5293f8c8e49af6d.png",
			"unit_items": [{
				"sku": "xsollus_bonus_pack_edition_steam",
				"name": "Xsollus: Bonus Pack (steam)",
				"type": "game_key",
				"drm_name": "Steam",
				"drm_sku": "steam"
			}, {
				"sku": "xsollus_bonus_pack_edition_playstation",
				"name": "Xsollus: Bonus Pack (playstation)",
				"type": "game_key",
				"drm_name": "Playstation",
				"drm_sku": "playstation"
			}, {
				"sku": "xsollus_bonus_pack_edition_xbox",
				"name": "Xsollus: Bonus Pack (xbox)",
				"type": "game_key",
				"drm_name": "XBox",
				"drm_sku": "xbox"

			}]
		},
		"quantity": 3
	}],
	"is_selectable": true

2. If is_selectable=false, you shouldn’t pass additional parameters in the request.

Redeem a coupon by code

1. If is_selectable=true, you should pass the selected_unit_items object in the following format when calling the Redeem coupon code method:

selected_unit_items:{
      unit_1_sku: "selected_unit_item_sku",
      unit_2_sku: "selected_unit_item_sku"
}

Example of the response:

{
  {
    "items": [
    {
      "sku": "xsollus_gold_edition_steam",
      "name": "Xsollus: Gold Edition (steam)",
      "type": "game_key",
      "description": null,
      "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/9541470622d96a821a9a11ea7763ea4c.png",
      "attributes": [],
      "is_free": true,
      "groups": [],
      "price": null,
      "virtual_prices": [],
      "drm_name": "Steam",
      "drm_sku": "steam",
      "has_keys": false,
      "is_pre_order": true,
      "release_date": null,
      "quantity": 1
    },
    {
      "sku": "xsollus_bonus_pack_edition_origin",
      "name": "Xsollus: Bonus Pack (origin)",
      "type": "game_key",
      "description": null,
      "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/aa2efd78dfd4e5dda5293f8c8e49af6d.png",
      "attributes": [],
      "is_free": true,
      "groups": [],
      "price": null,
      "virtual_prices": [],
      "drm_name": "Origin",
      "drm_sku": "origin",
      "has_keys": false,
      "is_pre_order": true,
      "release_date": null,
      "quantity": 3
  }
  ]
}

2. If is_selectable=false, you shouldn’t pass additional parameters in the request.