Региональные цены

При настройке каталога товаров существует возможность настроить ценовую политику для пользователей из разных стран (региональные цены) для виртуальных товаров и пакетов игровых ключей. По умолчанию цена для каждого товара или пакета ключей задается в USD. Также вы можете задавать региональные ограничения и устанавливать региональные цены одновременно.

Как это работает

Для страны пользователя происходит подбор цен для каталога товаров.

На этапе оплаты в платежном интерфейсе пользователь видит цену товара, конвертированную в валюту его страны, и размер налогов, если они предусмотрены.

Определение страны

• При запросе каталога товаров страна пользователя передается в параметре country в методах подраздела Catalog из группы методов Виртуальные предметы и валюта или группы методов Игровые ключи.
  Если страна не указана, она будет определена на основе IP-адреса пользователя. Затем для страны пользователя происходит подбор цен для каталога товаров.
• При покупке товара:
  • Если вы используете клиентские методы получения токена оплаты, важно использовать эти методы на стороне клиента, а не сервера. Страна и валюта в клиентских методах определяется по IP-адресу пользователя. Использование клиентских методов на стороне сервера может привести к неправильному определению валюты и повлиять на способы оплаты в платежном интерфейсе.
  • Если вы используете серверный метод Создание платежного токена для покупки, передайте страну в объекте country в теле запроса или IP-адрес пользователя в заголовке X-User-Ip.

1. 1. Если передана страна в параметре country.value и IP-адрес пользователя в заголовке X-User-Ip, приоритетным будет значение страны в параметре country.value.

Правила отображения цены в каталоге товаров

Для всех товаров в каталоге должен использоваться одинаковый перечень валют, в которых указаны цены.

Это необходимо, чтобы все товары в каталоге отображались в одной валюте. Если для одного из товаров в одной из стран не будет указана цена, цены всего каталога в этой стране отобразятся в валюте по умолчанию.

Если у товаров разная валюта по умолчанию, то цены отображаются в валюте по умолчанию первого товара в каталоге. Если у одного из товаров отсутствует цена в этой валюте, в ответе для него вернется значение цены null. Это приведет к некорректному отображению цены товара и может повлиять на отображение каталога в целом.

Примеры:

• 1 товар, 1 валюта, региональных цен нет
• 1 товар, 2 валюты, региональных цен нет
• 1 товар, региональные цены есть
• Несколько товаров, региональные цены есть, одна валюта по умолчанию
• Несколько товаров, региональные цены есть, разная валюта по умолчанию

Для товара задана валюта по умолчанию — USD и цена в этой валюте — 5 USD, настройки для стран отсутствуют. В этом случае пользователи из всех стран будут видеть эту цену.

Для товара задано два варианта цены: в USD и в EUR, но специальные цены для стран не указаны. В этом случае пользователи из стран, где используется EUR, будут видеть цену в 7 EUR. Пользователи из всех остальных стран будут видеть цену в 5 USD, так как это цена в валюте по умолчанию.

В проекте заданы цены в следующих валютах:

• цена по умолчанию — 7 USD;
• цена в евро — 6 EUR;
• региональные цены:
  • Германия — 8 EUR;
  • Италия — 5 EUR;
  • Малайзия — 20 MYR;
  • Южно-Африканская Республика — 90 ZAR.

В зависимости от страны пользователя отображение цен в каталоге будет следующим:

Страна пользователя	Цена в каталоге	Комментарий
США	7 USD	США — страна, где используется USD. Специальная цена для США не указана.
Япония	7 USD	Валюта Японии не указана, поэтому отображается цена в валюте по умолчанию.
Франция	6 EUR	Франция — страна, где используется EUR. Специальная цена для Франции не указана.
Германия	8 EUR	Для Германии указана региональная цена.
Италия	5 EUR	Для Италии указана региональная цена.
Малайзия	20 MYR	Для Малайзии указана региональная цена.
Южно-Африканская Республика	90 ZAR	Для ЮАР указана региональная цена.

В проекте заданы цены в следующих валютах:

• цена по умолчанию для всех товаров — в долларах США (USD);
• в Малайзии для всех товаров указана цена в малайских ринггитах (MYR);
• в Южно-Африканской Республике для всех товаров, кроме одного, указана цена в южноафриканских рэндах (ZAR).

В этом случае для пользователей из Малайзии каталог отобразится в MYR. Для пользователей из Южно-Африканской Республики — в USD, так как цена в ZAR не была указана для одного из товаров.

В проекте заданы цены в следующих валютах:

• цена по умолчанию для товара 1_test_item указана в долларах США (USD);
• цена по умолчанию для товара 2_test_item указана в евро (EUR);
• в Южно-Африканской Республике для 1_test_item указана цена в южноафриканских рэндах (ZAR), для 2_test_item — не указана.

В этом случае для пользователей из Южно-Африканской Республики для всех товаров должна отобразиться цена в валюте по умолчанию первого в каталоге товара — 1_test_item.

Валюта по умолчанию 1_test_item — USD. Она не совпадает с валютой по умолчанию товара 2_test_item — EUR. Также в списке цен для него нет цены в USD.

Поэтому для 2_test_item в ответе вернется значение цены null.

Для кого подходит

Для партнеров, которые хотят повышать продажи в странах с низкой покупательной способностью, определяя ценовую политику магазина в отношении пользователей из разных стран.

Как настроить

Вы можете добавлять, редактировать, удалять региональные цены:

• через Личный кабинет при создании/редактировании товара;
• Личный кабинет при импорте цен через файл;
• методы API.

Настройка через Личный кабинет при создании и редактировании товара

1. Откройте проект в Личном кабинете.
2. В боковом меню нажмите Store.
3. В панели Виртуальные предметы нажмите Настроить.
4. Нажмите + и в раскрывающемся списке выберите пункт Создать предмет.

5. Укажите:
   • изображение;
   • артикул;
   • одну или несколько групп, которым должен принадлежать предмет;
   • название предмета;
   • описание предмета;
   • свойство предмета — расходуемый, нерасходуемый, с ограниченным сроком действия.
6. В блоке Настройки цен выберите Платный предмет.
7. Установите переключатель Цены в реальной валюте в положение Вкл и укажите цену в реальной валюте. Без настройки региональных цен стоимость предмета будет отображаться для всех стран в долларах США по умолчанию.

8. Настройте цены:
   • Если вы хотите, чтобы цена предмета была задана в разных валютах — нажмите + и укажите валюту и цену.
   • Если вы хотите задать специальные цены для стран — нажмите Добавить цену и укажите страну, валюту и количество. Вы можете задать необходимое вам количество региональных цен.
9. Если вы хотите добавить цену в виртуальной валюте, установите переключатель Цены в виртуальной валюте в положение Вкл и укажите значения.
10. Если вы хотите, чтобы пользователь мог купить предмет ограниченное количество раз, установите переключатель Ограничивать покупку предметов пользователем в положение Вкл и укажите количество, доступное для покупки.
11. Если вы хотите, чтобы предмет отображался в каталоге, установите переключатель Показать предмет в магазине в положение Вкл.
12. Нажмите Создать предмет.

Импорт из файла в Личном кабинете

Вы можете импортировать региональные цены из файла для предварительно созданных товаров.

Возможности

• Загрузка или обновление региональных цен для множества товаров одновременно.
• Поддержка товаров всех типов:
  • виртуальные предметы;
  • виртуальная валюта;
  • пакеты виртуальной валюты;
  • бандлы;
  • пакеты игровых ключей на конкретной платформе.

• Валидация загружаемых данных. Если структура файла или формат данных не соответствуют требованиям, вы увидите список ошибок при импорте.

Структура файла

• SKU — артикул товара, для которого необходимо задать региональные цены.
• Country — код страны в формате ISO 3166-1 alpha-2. Перед загрузкой CSV-файла проверьте список поддерживаемых Xsolla стран. Заполнение ячеек в столбце опционально. Вы можете изучить примеры отображения цены, если страна не указана.
• Currency — код валюты в формате ISO 4217.
• Amount — цена товара. Используйте точку в качестве разделителя для десятичных знаков.

• IsDefault — является ли ценой в валюте по умолчанию. Укажите:

  • 1 — в строке цены, которая является ценой в валюте по умолчанию. Отображается во всех странах, для которых нет отдельных региональных цен.
  • 0 — во всех остальных строках. Вы также можете оставить ячейку в столбце IsDefault пустой.

Примечание

Цена в валюте по умолчанию не должна быть региональной — ячейку в столбце Country следует оставить пустой.

ПРИМЕР

Пример правильного заполнения (несколько товаров, 3 валюты, региональные цены есть).

Пример неправильного заполнения: несколько товаров, 3 валюты, региональные цены есть.
Ошибка: Группы virtual-item-1 и bundle-1 имеют цены по умолчанию с привязкой к стране US.

При добавлении каждого нового артикула товара необходимо задать цену в валюте по умолчанию. Если ее не указать, при импорте цен из файла отобразится ошибка.

ПРИМЕР

Пример правильного заполнения (несколько товаров, 3 валюты, региональные цены есть).

Пример неправильного заполнения (несколько товаров, 3 валюты, региональные цены есть).
Ошибка: Группы virtual-item-1 и bundle-1 не имеют цены по умолчанию.

• Platform — артикул платформы. Используется, если вы задаете региональные цены игровых ключей. Не используется для других товаров.

  Доступные платформы.

  Артикул платформы	Название платформы
  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

Примечание

Игровые ключи с одинаковыми артикулами, но с разными платформами – это разные товары. Необходимо, чтобы у каждого такого товара была указана цена в валюте по умолчанию.

ПРИМЕР

Пример правильного заполнения (несколько игровых ключей, 3 валюты, региональные цены есть, 2 платформы).

Пример неправильного заполнения (несколько игровых ключей, 3 валюты, региональные цены есть, 2 платформы). Ошибка 1: некорректный порядок сгруппированных по SKU и Platform сущностей, из-за чего вместо трех сущностей, будет найдено девять.
Ошибка 2: группы 3,4,5,6 не имеют цены по умолчанию из-за неправильной группировки.
Ошибка 3: группа 9 перезапишет данные группы 7, поскольку они передают полный набор цен по одной и той же сущности. В итоге игровой ключ game-key-2 для платформы playstation после импорта будет иметь только цену в валюте MYR.

Примеры заполнения файла и возможные ошибки

• Несколько товаров, 3 валюты, региональных цен нет.
• Несколько товаров, 1 валюта, региональных цен нет.
• Несколько игровых ключей, 3 валюты, региональные цены есть, 1 платформа.
• Несколько игровых ключей, 3 валюты, региональных цен нет, 2 платформы.

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

• Несколько игровых ключей, 3 валюты, региональных цен нет, 2 платформы.
• Несколько игровых ключей, 3 валюты, региональные цены есть, 2 платформы.
• Несколько товаров, 3 валюты, региональные цены есть.
• Несколько товаров, 3 валюты, региональные цены есть.
• Несколько товаров, 3 валюты, региональных цен нет.

Ошибка: Группы game-key-1 + steam и game-key-2 + steam не имеют цены по умолчанию.

Ошибка: Группы game-key-1 + steam и game-key-2 + steam имеют цены по умолчанию с привязкой к стране US.

Ошибка: Группы virtual-item-1 и bundle-1 не имеют цены по умолчанию.

Ошибка: Группы virtual-item-1 и bundle-1 имеют цены по умолчанию с привязкой к стране US.

Ошибка 1: Некорректный порядок сгруппированных по SKU сущностей, из-за чего вместо трех сущностей, будет найдено пять.
Ошибка 2: Группа 3 не имеет цены по умолчанию из-за неправильной группировки.
Ошибка 3: Группа 4 перезапишет данные группы 2, поскольку они передают полный набор цен по одной и той же сущности. В итоге SKU для virtual-currency-1-pack-100 после импорта будет иметь только цену в валюте MYR.

Импорт из файла

1. Откройте проект в Личном кабинете.
2. В боковом меню нажмите Store и перейдите в раздел с любым типом товара.
3. Нажмите Импортировать цены.

4. В окне импорта вы можете скачать шаблон файла и заполнить его.
5. Загрузите заполненный файл в соответствующее поле в окне импорта.
6. Если при импорте возникнут ошибки, в окне импорта отобразится список этих ошибок и рекомендаций по исправлению. Внесите необходимые изменения в файл и загрузите его снова.

После успешной загрузки для товаров с указанными артикулами будут обновлены региональные цены в соответствии с ценами в файле. При этом цены, указанные ранее, будут удалены.

Пример:

Для товара в Личном кабинете указано несколько цен в разных валютах и несколько региональных цен. В импортируемом файле — только одна цена в EUR. После импорта файла для этого товара в Личном кабинете будет указана только одна цена в EUR.

Настройка через методы API

• в методы создания и обновления виртуальных предметов;
• методы создания и обновления виртуальной валюты;
• методы создания и обновления пакетов виртуальной валюты;
• методы создания и обновления бандлов;

• методы создания и обновления пакетов игровых ключей.

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