Regional prices

When setting up an item catalog, you can configure pricing policies for users from different countries (regional pricing) for virtual items and game key packages. The price for each item or game keys package is set in USD by default. You can set regional restrictions and regional prices at the same time.

How it works

Prices in the catalog are based on the user’s country.

During the purchase via Pay Station, the price of an item is converted into the currency of the user’s country and includes taxes, if applicable.

Country determination

• When requesting an item catalog, the user’s country is passed in the country parameter in the methods of the Catalog subsection from the Virtual Items & Currency or Game keys methods group.
  If the country is not specified, it will be determined based on the user’s IP address. Then, prices for the item catalog are selected for the user’s country.
• When purchasing an item:
  • If you use the client methods to obtain a payment token, it is important to use them only from the client side and not from the server side. The country and currency in client methods are determined by the user’s IP address. Using this method from the server side may cause incorrect currency determination and affect payment methods in Pay Station.
  • If you use the Create payment token for purchase server method, you need to pass the country object in the request body or the user’s IP address in the X-User-Ip header.

1. 1. If the country in the country.value parameter and the IP address in the X-User-Ip header are passed, the country value in the country.value parameter takes precedence.

Principles of price display in the item catalog

For all items in the catalog, you should use the same list of currencies in which the prices are specified.

This is necessary so that all items in the catalog are displayed in the same currency. If the price is not specified for one of the items in one of the countries, the prices for the entire catalog in that country is displayed in the default currency.

If the default currency is different for items, then prices are displayed in the default currency of the first item in the catalog. If one of the items does not have a price in this currency, a price value of null will be returned for it in the response. This will lead to an incorrect display of the item price and may affect the display of the catalog as a whole.

Examples:

• 1 item, 1 currency, no regional prices
• 1 item, 2 currencies, no regional prices
• 1 item, regional prices exist
• Multiple items, regional prices exist, one default currency
• Multiple items, regional prices exist, different default currencies

The default currency for the item is USD and the price is 5 USD, there are no settings for countries. In this case, users from all countries will see this price.

Two price options are set for the item: in USD and in EUR, but special prices for countries are not specified. In this case, users from countries where EUR is used will see the price in 7 EUR. Users from all other countries will see the price in 5 USD, as this is the price in the default currency.

The project has prices in the following currencies:

• default price — 7 USD
• price in euro — 6 EUR
• regional prices:
  • Germany — 8 EUR
  • Italy — 5 EUR
  • Malaysia — 20 MYR
  • South Africa — 90 ZAR

Depending on the user’s country, the display of prices in the catalog will be as follows:

User’s country	Catalog price	Comment
USA	7 USD	USA is a country where USD is used. A special price for the USA is not specified.
Japan	7 USD	The currency of Japan is not specified, so the price is displayed in the default currency.
France	6 EUR	France is a country where EUR is used. A special price for France is not specified.
Germany	8 EUR	A regional price is specified for Germany.
Italy	5 EUR	A regional price is specified for Italy.
Malaysia	20 MYR	A regional price is specified for Malaysia.
South Africa	90 ZAR	A regional price is specified for South Africa.

The project has prices in the following currencies:

• the default price for all items is in US dollars (USD)
• in Malaysia, the prices for all items are in Malaysian Ringgit (MYR)
• in South Africa, the prices for all items except one are in South African Rand (ZAR)

In this case, the catalog is displayed in MYR for users from Malaysia but in USD for South Africa. For users from South Africa, it is displayed in USD, as the price in ZAR was not specified for one of the items.

The project has prices in the following currencies:

• the default price for the 1_test_item is in US dollars (USD)
• the default price for the item 2_test_item is in euro (EUR)
• in South Africa, the price for 1_test_item is given in South African rand (ZAR), for 2_test_item it is not specified

In this case, for users from South Africa, the price should be displayed in the default currency of the first item in the catalog — 1_test_item.

The default currency for 1_test_item — USD. It does not match the default currency of the 2_test_item — EUR. Also, there is no price in USD in the price list for it.

Therefore, for 2_test_item the returned price value will be null.

Who can use it

Partners who want to increase sales in countries with low purchasing power by setting the store’s pricing policy for users from different countries.

How to get it

You can add, edit, and delete regional prices:

• through Publisher Account when creating/editing an item
• through Publisher Account when importing prices via a file
• using API methods

Setting up through the Publisher Account when creating and editing item

1. Open your project in Publisher Account.
2. Click Store in the side menu.
3. In the Virtual Items pane, click Configure.
4. Click + and select Create item from the drop-down list.

5. Specify:
   • image
   • SKU
   • one or several groups the item should belong to
   • name
   • description
   • item property — consumable, non-consumable, or time-limited items
6. In the Price settings block, choose Paid item.
7. Switch the Pricing in real currency toggle to On and specify the price. If you do not set regional prices, the price of an item will be the same for all countries and in US dollars.

8. Set up prices:
   • If you want to set up the price of an item in different currencies, click + and specify the currency and price.
   • If you want to set special prices for countries, click Add pricing and specify the country, currency, and quantity. You can set the number of regional prices you need.
9. If you want to add the price in virtual currency, switch the Pricing in virtual currency toggle to On and specify the price.
10. If you want to limit the availability of items to specific users, switch the Limit number of times one user can buy this item toggle to On and specify the number.
11. If you want to show an item in the store, set the Show item in store toggle to On.
12. Click Create item.

Import from file in the Publisher Account

You can import regional prices from a file for pre-created items.

Features

• Upload or update regional prices for multiple items at once.
• Support for items of all types:
  • virtual items
  • virtual currency
  • virtual currency packages
  • bundles
  • packages of game keys on a specific platform

• Validation of uploaded data. If the file’s structure or data format does not meet the requirements, you will see a list of errors during the import.

File structure

• SKU — the item SKU for which regional prices need to be set.
• Country — the country code in ISO 3166-1 alpha-2 format. Check the list of countries supported by Xsolla before uploading the CSV file. Filling in cells in this column is optional. You can see examples of price display if the country is not specified.
• Currency — the currency code is in ISO 4217 format.
• Amount — the price of the item. Use a period for decimal points.

• IsDefault — whether this is the default price. Specify:

  • 1 — this is for the row with the default price. It is displayed in all countries with no regional prices.
  • 0 — for all other rows. You can also leave the cell in the IsDefault column empty.

Note

The default price should not be regional - leave the cell in the Country column empty.

EXAMPLE

Correctly filled file (several items, 3 currencies, regional prices are available).

Incorrectly filled file (several items, 3 currencies, regional prices are available).
Error: In virtual-item-1 and bundle-1 the groups cells in the Country column aren’t empty.

When adding each new item, you must set the price in the default currency. If not specified, an error will be displayed when importing the file.

EXAMPLE

Correctly filled file (several items, 3 currencies, regional prices are available).

Incorrectly filled file (several items, 3 currencies, regional prices are available).
Error: There isn’t any default currency for virtual-item-1 and bundle-1 groups.

• Platform — the platform SKU. It is used when setting regional prices for game keys but is not used for other items.

  Available platforms.

  Platform SKU	Platform name
  steam	Steam
  playstation	PlayStation
  xbox	Xbox
  uplay	Uplay
  origin	Origin
  drmfree	DRM Free
  gog	GOG
  epicgames	Epic Games Store
  nintendo_eshop	Nintendo Switch eShop
  discord_game_store	Discord Game Store
  oculus	Oculus
  viveport	Viveport
  stadia	Google Stadia

Note

Game keys with the same SKU but different platforms are considered different entities. Each entity must have a price specified in the default currency.

EXAMPLE

Correctly filled file (several game keys, 3 currencies, regional prices are available, 2 platforms).

Incorrectly filled file (several game keys, 3 currencies, regional prices are available, 2 platforms).
Error 1: Incorrect grouping of game keys by SKU and Platform, resulting in nine entities being found instead of three.
Error 2: Groups 3, 4, 5, and 6 do not have a default price due to incorrect grouping.
Error 3: Group 9 will overwrite the data of group 7 because they have a full set of prices for the same entity. As a result, the game-key-2 for the playstation platform will only have a price in MYR after import.

Examples of file completion and possible errors

• Several items, 3 currencies, no regional prices.
• Several items, 1 currency, no regional prices.
• Several game keys, 3 currencies, regional prices are available,1 platform.
• Several game keys, 3 currencies, no regional prices, 2 platforms.

Copy

Full screen

Small screen

• csv

SKU,Currency,Amount,Country,IsDefault
virtual-item-1,EUR,9.09,,0
virtual-item-1,USD,10.1,,1
virtual-item-1,MYR,47,,0
virtual-currency-1-pack-100,EUR,2.09,,0
virtual-currency-1-pack-100,USD,2.3,,1
virtual-currency-1-pack-100,MYR,24,,0
bundle-1,EUR,15,,0
bundle-1,USD,17,,1
bundle-1,MYR,82,,0

Copy

Full screen

Small screen

• csv

SKU,Currency,Amount,Country,IsDefault
virtual-item-1,USD,10.1,,1
virtual-currency-1-pack-100,USD,2.3,,1
bundle-1,USD,17,,1

Copy

Full screen

Small screen

• csv

SKU,Currency,Amount,Country,IsDefault,Platform
game-key-1,EUR,9.09,,1,steam
game-key-1,EUR,9.2,DE,0,steam
game-key-1,EUR,8.09,IT,0,steam
game-key-1,USD,10.1,US,0,steam
game-key-1,MYR,47,MY,0,steam
game-key-2,EUR,2.09,,1,steam
game-key-2,EUR,2.2,DE,0,steam
game-key-2,EUR,1.79,IT,0,steam
game-key-2,USD,2.3,US,0,steam
game-key-2,MYR,24,MY,0,steam

Copy

Full screen

Small screen

• csv

SKU,Currency,Amount,Country,IsDefault,Platform
game-key-1,USD,10.1,,1,steam
game-key-1,EUR,9.09,,0,steam
game-key-1,MYR,47,,0,steam
game-key-1,USD,17,,1,playstation
game-key-1,EUR,15,,0,playstation
game-key-1,MYR,82,,0,playstation
game-key-2,USD,2.3,,1,steam
game-key-2,EUR,2.09,,0,steam
game-key-2,MYR,24,,0,steam

• Several game keys, 3 currencies, no regional prices, 2 platforms.
• Several game keys, 3 currencies, regional prices are available, 2 platforms.
• Several items, 3 currencies, regional prices are available.
• Several items, 3 currencies, regional prices are available.
• Several items, 3 currencies, no regional prices.

Error: Groups game-key-1 + steam and game-key-2 + steam do not have default prices.

Error: Groups game-key-1 + steam and game-key-2 + steam have US mentioned as the country for default prices.

Error: Groups virtual-item-1 and bundle-1 do not have default prices.

Error: Groups virtual-item-1 and bundle-1 have US mentioned as the country for default prices.

Error 1: Incorrect grouping of items by SKU, resulting in five entities being found instead of three.
Error 2: Group 3 does not have a default price due to the incorrect grouping.
Error 3: Group 4 will overwrite the data of group 2, because they have a full set of prices for the same item. As a result, SKU for virtual-currency-1-pack-100 will only have a price in MYR after import.

File import

1. Open your project in Publisher Account.
2. Click Store in the side menu and go to the section with any type of product.
3. Click Import prices.

4. In the import window, you can download the file template and add the values.
5. Upload the file to the corresponding field in the import window.
6. If there are any errors during the import, the import window displays a list of these errors and recommendations for correction. Make the necessary changes to the file and upload it again.

After successful upload, regional prices for items with the specified SKUs will be updated according to the prices in the file. Previously specified prices will be deleted.

Example:

There are several prices in different currencies and several regional prices for the item in the Publisher Account. In the imported file, there is only one price in EUR. After importing the file, only one price in EUR will be specified for this item in the Publisher Account.

Setting up using API methods

• in the methods for creating and updating virtual items
• in the methods for creating and updating virtual currency
• in the methods for creating and updating virtual currency packages
• in the methods for creating and updating bundles

• in the methods for creating and updating game key packages

"prices": [
      {
        "amount": 100,
        "currency": "USD",
        "is_enabled": true,
        "is_default": true
      },
      {
        "amount": 200,
        "currency": "CZK",
        "country_iso": "CZ",
        "is_enabled": false,
        "is_default": false
      }
    ]