Set up promotional campaigns

After you integrate the store into the game, you can set up coupons, promo codes, bonuses, or discount promotions to attract new users and increase sales.

You can also run personalized promotions, that is, set up campaigns for the specific users. You can set the number of items available to the user for the promotion. This is only possible for promotional campaigns with discounts and promotional campaigns with bonuses.

If you have been integrated with the Login product already, do these before setting up personalized promotions for users:

1. Set up user attributes for your project.
2. Set user attributes schema in the Login section.

Attributes are user features that are stored as key-value pairs. With the help of the attributes you can:

• segment users
• prepare personal storefronts for each group of users in your Web Shop.

To ensure the integrity of transmitted data, you can set attribute validation rules in JSON Schema format in Publisher Account, and manage user attributes using Login API methods or webhooks. You can also edit the attributes values in your Publisher Account. For more information, refer to How-to set up user attributes.

Coupons have codes that grant free items without any purchase or shopping cart. To use a coupon, a user should enter the code in the game, website, or mobile application. The linked reward is then delivered to the user’s inventory. Rewards can include:

• virtual currency package
• virtual item

Promo codes apply a discount to the shopping cart or add free items to the cart during checkout. After activating the promo code and paying for the items in the cart, the user can receive one of the following rewards:

• a discount that applies to the user’s cart
• bonus items:
• virtual currency package
• virtual item including a bundle or time-limited items

Users can also receive a bonus when buying promotional items. Bonuses can include:

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

A discount promotion allows you to set up a discount on one or more products. An unlimited number of promotions can be applied to one product. Discounts are not cumulative, but are applied to the cost of individual item. Discounts can apply to one or several of the following items:

• virtual currency package
• virtual item including time-limited items

Promotional campaign with coupons

To start a promotional campaign with coupons:

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

Set up a promotional campaign with coupons

1. Open your project in Publisher Account.
2. Click Store in the side menu and go to Promotions and rewards.

3. Click Create promotion.

4. Specify the following parameters:
   1. Enter the promotion title.
   2. Choose Coupons as the promotion type.
5. Choose the reward that the user receives when they redeem a coupon. Available options:
   • Virtual currency package
   • Virtual item (one or several, including bundles and time-limited items).
6. Add:
   1. Promotional identifier in External ID.
   2. Bonus items that the user receives when they redeem a coupon.
   3. Item’s type and amount.
7. Click Next.

8. Specify the total number of redemptions and the number of redemptions per user.

9. Set the campaign start and end dates.
10. Click Next.

11. Check the settings and click Save and exit.

12. Click Store in the side menu and go to Promotions and rewards.
13. Select the promotion, click the ••• menu button to open a menu and click Edit promotion.

14. Go to the Codes tab.
15. Specify how coupons are generated.

16. Generate the coupon code or enter it manually.
17. Activate the promotion.

Redeem a coupon by code

Implement the call of the Redeem coupon code method to use a coupon. Depending on the is_selectable parameter value in the Get coupon rewards method response, there are 2 possible flows:

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.

Get coupon rewards

Implement the call of the Get coupon rewards method to get the list of items that the user receives after redeeming a coupon. Depending on the is_selectable parameter value in the response, there are 2 possible flows:

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.

Promotional campaign with promo codes

To start a promotional campaign with promo codes:

1. Set up a promotional campaign with promo codes.
2. Implement the methods of promo code redemption.
3. Implement the method of getting a promo code reward.

Set up a promotional campaign with promo codes

1. Open your project in Publisher Account.
2. Click Store in the side menu and go to Promotions and rewards.

3. Click Create promotion.

4. Specify the following parameters:
   1. Enter the promotion title.
   2. Choose Promo code as the promotion type.
5. Choose what the user receives when they redeem a promo code: no reward, discount on all items in the cart, discount on specific items, bonus items, or a combination.
6. Set the discount amount.
7. Click Next.

8. Specify the total number of redemptions and the number of redemptions per user.
9. Click Next.

10. Set the campaign start and end dates.
11. Click Next.

12. Check the settings and click Save and exit.

13. Click Store in the side menu and go to Promotions and rewards.
14. Select the promotion, click the ••• menu button to open a menu and click Edit promotion.

15. Go to the Codes tab.
16. Specify how promo codes are generated.
17. Generate the promo code or enter it manually.

18. Activate the promotion.

Redeem a promo code

Implement the call of the Redeem promo code method to use a promo code. Depending on the is_selectable parameter value, there are 2 possible flows in the Get promo code reward method response:

1. If is_selectable=true, you should pass the selected_unit_items object in the following format when calling the Redeem promo 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.

Get promo code rewards

Implement the call of the Get promo code reward method to get the list of items that the user receives after redeeming a promo code. Depending on the is_selectable parameter value in the response, there are 2 possible flows:

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_nintendo_eshop",
				"name": "Xsollus: Gold Edition (nintendo_eshop)",
				"type": "game_key",
				"drm_name": "Nintendo Switch eShop",
				"drm_sku": "nintendo_eshop"
			}]
		},
		"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_origin",
				"name": "Xsollus: Bonus Pack (origin)",
				"type": "game_key",
				"drm_name": "Origin",
				"drm_sku": "origin"
			}, {
				"sku": "xsollus_bonus_pack_edition_drmfree",
				"name": "Xsollus: Bonus Pack (drmfree)",
				"type": "game_key",
				"drm_name": "DRM Free",
				"drm_sku": "drmfree"
			}, {
				"sku": "xsollus_bonus_pack_edition_gog",
				"name": "Xsollus: Bonus Pack (gog)",
				"type": "game_key",
				"drm_name": "GOG",
				"drm_sku": "gog"
			}, {
				"sku": "xsollus_bonus_pack_edition_rockstar",
				"name": "Xsollus: Bonus Pack (rockstar)",
				"type": "game_key",
				"drm_name": "Rockstar Games Launcher",
				"drm_sku": "rockstar"
			}]
		},
		"quantity": 3
	}],
	"discount": {
		"percent": null
	},
	"is_selectable": true

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

Promotional campaign with bonuses

To start a promotional campaign with a bonus:

1. Open your project in Publisher Account.
2. Click Store in the side menu and go to Promotions and rewards.

3. Click Create promotion.

4. Specify the following parameters:
   1. Enter the promotion title.
   2. Choose Bonus as a promotion type.
5. Choose promotional items.

6. Choose items granted to users when they purchase promotional items.
7. Click Next.

8. If you want the promotion to apply only to users who make their first purchase, set the Trigger promotion only for first-time buyers toggle to On. The Limit number of times one user can use promotion and Promotion for only specific users toggles will be enabled automatically, and a set of conditions for triggering the promotion will be created. Add additional conditions if it is necessary.
9. Click Next.

10. Set the campaign start and end dates.
11. Click Next.

12. Check the settings and click Save and exit.

13. Click Store in the side menu and go to Promotions and rewards.
14. Select the promotion, click the ••• menu button to open a menu and click Edit promotion.

15. Activate the promotion.

Promotional campaign with discounts

Set up a promotional campaign with discounts via Publisher Account

1. Open your project in Publisher Account.
2. In the side bar click Store.

3. Click Promotions and rewards > Create promotion.

4. Specify the following parameters:
   1. Enter the promotion title.
   2. Choose Discount as a promotion type.
5. Set up discounts that apply to one or several items.
6. Set the discount amount.
7. Click Next.

8. If you want the promotion to apply only to users who make their first purchase, set the Trigger promotion only for first-time buyers toggle to On. The Limit number of times one user can use promotion and Promotion for only specific users toggles will be enabled automatically, and a set of conditions for triggering the promotion will be created. Add additional conditions if it is necessary.
9. Click Next.

10. Set the campaign start and end dates.
11. Click Next.

12. Check the settings and click Save and exit.

13. Click Store in the side menu and go to Promotions and rewards.
14. Select the promotion, click the ••• menu button to open a menu and click Edit promotion.

15. Activate the promotion.

Set up via API methods

To work with discount promotions, you can use the methods from the Discount subsection from the Promotions method group.

To create the promotion via API methods:

1. Call the Create discount promotion for item method with required parameters.
2. Call the Update item promotion method with the “is_enabled”:true parameter to activate the promotion.

To edit the promotion via an API, call the Update item promotion method with new promotion parameters. You can also edit the promotion that has the Active status.

When creating or editing a discount promotion via API methods, you can also:

• Configure a discount to all items in the project. Pass the “items”:null parameter to Create discount promotion for item or Update item promotion methods.

"items": null

• Configure a discount for physical goods. Pass an array with SKUs of physical goods to Create discount promotion for item or Update item promotion methods.

"items": [{
     “sku”: “strw2030”
  }, {
     “sku”: “strw4060”
  }, {
     “sku”: “cupred200”
  }
]

• Configure a discount with the fraction percentage value. Pass the discount.percent parameter with a fraction discount to Create discount promotion for item or Update item promotion methods.

"discount": {
    “percent”: ”49.9”
}

• Configure a discount for items of different types. Pass an array with SKUs of required items to Create discount promotion for item or Update item promotion methods.

"items": [{
     “sku”: “storm_shield”
  }, {
     “sku”: “heaven_crystals_pack_x500”
  },{
     “sku”: “strw2030”
  }
]

• Configure a discount for definite DRMs of the game. Pass an array with SKUs of required DRMs to Create discount promotion for item or Update item promotion methods.

"items": [{
     “sku”: “brilliant_game_sku_steam”
  }
  ]

• Configure discount promotion that doesn’t have a specified time period. Pass the “date_end”:null parameter to Create discount promotion for item or Update item promotion methods.

“date_end”: null

• Set up promotion for first-time buyers. For this, pass in the Create discount promotion for item for item API or in the Update item promotion API an object in array attribute_conditions:

"attribute_conditions": [
{
"attribute": "has_purchase",
"operator": "eq",
"value": "0",
"type": "number"
}
],
"limits": {
"per_user": 1
}