Local prices

You can set regional prices for all items in your catalog to increase sales in countries with low purchasing power. By default, prices are set in USD. Additionally, you can configure regional restrictions.

You can add, edit, and delete regional prices in the following ways:

• using API methods

How it works

The item price is determined when the catalog is requested, depending 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

The user’s country is determined at different stages of working with the catalog and payment, as follows:

• When requesting the item catalog, the user’s country is passed in the country parameter of the methods in the Virtual items and currency or Game keys groups.

  If the country is not specified, it is determined based on the user’s IP address. Prices for the item catalog are selected based on the user’s country.

• When purchasing an item:

  • If you use the client methods to obtain a payment token, use them on the client side, not the server side. The country and currency in client methods are determined by the user’s IP address. Using client methods on the server side may cause incorrect currency determination and affect payment methods in the payment UI.

  • If you use the Create payment token for purchase server method, pass the country in the user.country.value parameter in the request body or the user’s IPv4 address in the X-User-Ip header. If both values are passed, user.country.value takes priority. IPv6 addresses are not supported: passing one may result in incorrect country and currency detection.

  Note

  You can pass the currency in the settings.currency parameter. This value takes precedence over the country value and affects how the payment currency is displayed. The payment methods in the payment UI are still determined by the country value in the user.country.value parameter.

Principles of price display in the item catalog

Use the same list of currencies for all items in the catalog. Prices are processed according to the following logic:

• If at least one item has no price set for the selected country, prices for the entire item catalog in that country switch to the default currency.
• If items have different default currencies, prices are displayed in the default currency of the first item in the catalog. If one of the items has no price in that currency, the price value null is returned for it in the catalog request response. This results in an incorrect display of the item’s price and may affect the display of the catalog as a whole.

Examples:

• 1 item, 1 currency, 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.

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 2_test_item is in euro (EUR)
• in South Africa, the price for the 1_test_item is given in South African rand (ZAR), for the 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 the 1_test_item is 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 the 2_test_item the returned price value will be null.

To create a virtual item with a regional price:

2. Click Create manually and select Virtual item from the drop-down list.

3. In the General settings section, specify the following:
   • SKU
   • One or several groups the item should belong to (optional)
   • Name
   • Short description
   • Extended description — to add it, turn on the corresponding toggle (optional)

4. In the Media section, upload one or more images or videos (optional) — from your device or via a link. In the store created with the Xsolla site editor, all item cards display the file marked as Main, while the remaining files are available only in item cards with a media gallery. The file marked as Main is also returned in the responses of the catalog retrieval API calls.

5. In the Price settings section, select Paid item.

6. Turn on the Real currency prices toggle and click Set up prices.

7. In the window that opens, specify the currency and default price. You can replace USD with another default currency.

8. Set up regional prices. You can do this in two ways, manually or automatically:

• To set prices manually:

1. Click Add local price and add prices line by line.

2. Click Apply.

• To set prices automatically:

1. Click Calculate using default price. A list of countries will be generated in alphabetical order, and the price in the regional currency will be calculated for each country based on exchange rates and taxes.

2. To remove countries for which you don’t need to set regional prices, click the minus icon to the right of the price.

3. To modify an automatically calculated price, change the value in the corresponding row.

4. Click Apply.

9. If you want to add a price in virtual currency, turn on the Virtual currency prices toggle and specify the values.

10. To limit the number of items available for purchase:

    1. Turn on the toggle in the Limits section and specify the quantity.
    2. Configure the limit reset frequency. To do this, select a period from the drop-down list:
       • Daily.
       • Weekly.
       • Monthly.
       • Custom interval. The interval is calculated from the item’s display start date in the store.
       • No regular refresh.
    3. Set up the reset schedule by specifying the parameters that correspond to the selected period.

11. To configure a display time limit for the item (optional):

    1. Turn on the toggle in the Add specific display period section.
    2. Specify the time zone and the beginning and the end of the period.

    To leave the end of the item’s display period unspecified, turn on the No end date toggle.

12. Configure attributes using one of the following options (optional):
    1. Add attributes and their values in JSON format.
    2. Manually create attributes and their values, and link them to items.

13. If the paid item will be used in any mechanics with a random reward (e.g., loot boxes or gacha), enable the Mark as paid randomized reward toggle.

14. Click Create.

15. In the window that opens, select the item status and click Continue.

The created item will appear in the All items section.

To edit prices:

2. Click ⋮ next to the desired item and select Edit from the drop-down list.

3. In the Price settings section, click the edit icon under the default price.

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

Required file columns:

• 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 — 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 price in the default currency must 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

Examples of the correct filling of the CSV file for import:

• 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

 1SKU,Currency,Amount,Country,IsDefault
 2virtual-item-1,EUR,9.09,,0
 3virtual-item-1,USD,10.1,,1
 4virtual-item-1,MYR,47,,0
 5virtual-currency-1-pack-100,EUR,2.09,,0
 6virtual-currency-1-pack-100,USD,2.3,,1
 7virtual-currency-1-pack-100,MYR,24,,0
 8bundle-1,EUR,15,,0
 9bundle-1,USD,17,,1
10bundle-1,MYR,82,,0

Copy

Full screen

Small screen

• csv

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

Copy

Full screen

Small screen

• csv

 1SKU,Currency,Amount,Country,IsDefault,Platform
 2game-key-1,EUR,9.09,,1,steam
 3game-key-1,EUR,9.2,DE,0,steam
 4game-key-1,EUR,8.09,IT,0,steam
 5game-key-1,USD,10.1,US,0,steam
 6game-key-1,MYR,47,MY,0,steam
 7game-key-2,EUR,2.09,,1,steam
 8game-key-2,EUR,2.2,DE,0,steam
 9game-key-2,EUR,1.79,IT,0,steam
10game-key-2,USD,2.3,US,0,steam
11game-key-2,MYR,24,MY,0,steam

Copy

Full screen

Small screen

• csv

 1SKU,Currency,Amount,Country,IsDefault,Platform
 2game-key-1,USD,10.1,,1,steam
 3game-key-1,EUR,9.09,,0,steam
 4game-key-1,MYR,47,,0,steam
 5game-key-1,USD,17,,1,playstation
 6game-key-1,EUR,15,,0,playstation
 7game-key-1,MYR,82,,0,playstation
 8game-key-2,USD,2.3,,1,steam
 9game-key-2,EUR,2.09,,0,steam
10game-key-2,MYR,24,,0,steam

Examples of incorrect filling of the CSV file for import:

• 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 currencies.

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

To import prices from a file:

3. Click Import/Export and in the drop-down list in the Import block, select Prices from CSV.

4. Upload the file to the corresponding field in the import window.

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:

Additionally, you can set regional prices when importing items using the Import items via JSON file API call.

Setting up using API methods

To set up regional prices through API methods, pass an array of objects with price settings for countries:

• 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

Example of the array:

 1"prices": [
 2  {
 3    "amount": 100,
 4    "currency": "USD",
 5    "is_enabled": true,
 6    "is_default": true
 7  },
 8  {
 9    "amount": 200,
10    "currency": "CZK",
11    "country_iso": "CZ",
12    "is_enabled": false,
13    "is_default": false
14  }
15]