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

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

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

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

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

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

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

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

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

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

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

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

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

Примеры:

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

Для товара задана валюта по умолчанию — USD и цена в этой валюте — 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.

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

1. В проекте в Личном кабинете перейдите в раздел Каталог товаров > Все товары > Виртуальные предметы.
2. Нажмите Добавить и выберите Виртуальные предметы.

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

6. В открывшемся окне укажите валюту и цену по умолчанию. Вы можете заменить доллары США на другую валюту по умолчанию.

7. Настройте региональные цены. Вы можете сделать это двумя способами, вручную и автоматически:

• Чтобы задать цены вручную:

1. Нажмите Добавить цену и добавьте страны и цены построчно.

2. Нажмите Применить.

• Чтобы настроить цены автоматически:

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

2. Чтобы удалить страны, для которых вам не нужно настраивать региональные цены, нажмите крестик справа от цены.

3. Чтобы изменить автоматически рассчитанную цену, измените значение в соответствующей строке.

4. Нажмите Применить изменения.

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

1. Установите переключатель Ограничивать покупку предметов пользователем в положение Вкл.

2. Укажите количество, доступное для покупки.

3. Выберите интервал:

• Без регулярного обновления;

• Каждый день;

• Каждую неделю;

• Каждый месяц;

• Настроить интервал. Интервал рассчитывается от даты начала периода показа предмета в магазине.

10. Вы можете установить ограничение времени отображения предмета в магазине, для этого в поле Показать предмет в магазине выберите, когда он будет отображаться:
    • Всегда — предмет будет доступен в магазине без ограничений по времени.
    • Ограниченное время — вы можете указать один или несколько периодов, в которые предмет будет отображаться. Для этого задайте часовой пояс и период отображения. При необходимости установите флажок Без даты окончания, чтобы предмет отображался с указанной даты без даты окончания.

11. Нажмите Создать предмет.

1. В проекте в Личном кабинете перейдите в раздел Каталог товаров > Все товары > Виртуальные предметы.
2. Нажмите ⋮ напротив необходимого предмета и в раскрывающемся списке выберите Редактировать.
3. В разделе Настройки цен под ценой по умолчанию нажмите Редактировать.

Настройка через Личный кабинет при импорте цен из файла

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

Возможности

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

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

Файл может быть только в формате CSV и должен содержать следующие столбцы:

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

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

Примеры правильного заполнения CSV файла для импорта:

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

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

• Несколько игровых ключей, 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. В боковом меню нажмите Каталог товаров и перейдите в раздел с любым типом товара.
3. Нажмите Импортировать цены.

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

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

Example:

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

Дополнительно вы можете задать региональные цены при импорте товаров через метод API Импорт из JSON-файла.

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

Чтобы настроить региональные цены через методы API, передайте массив объектов с настройками цен для стран в:

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

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

 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]