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

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

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

• через методы API.

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

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

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

Страна пользователя определяется на разных этапах работы с каталогом и оплатой следующим образом:

• При запросе каталога товаров страна пользователя передается в параметре country методов группы Виртуальные предметы и валюта или Игровые ключи.

  Если страна не указана, она будет определена на основе IP-адреса пользователя. На основе страны пользователя выполняется подбор цен для каталога товаров.

• При покупке товара:

  • Если вы используете клиентские методы получения токена оплаты, используйте эти методы на стороне клиента, а не сервера. Страна и валюта в клиентских методах определяются по IP-адресу пользователя. Использование клиентских методов на стороне сервера может привести к неправильному определению валюты и повлиять на способы оплаты в платежном интерфейсе.

  • Если вы используете серверный метод Создание платежного токена для покупки, передайте страну в параметре user.country.value в теле запроса или IPv4-адрес пользователя в заголовке X-User-Ip. Если передать оба значения, приоритетным будет user.country.value. IPv6-адреса не поддерживаются: их передача может привести к некорректному определению страны и валюты.

  Примечание

  Вы можете передать валюту в параметре settings.currency. Это значение будет приоритетнее, чем значение страны, и повлияет на отображение валюты платежа. При этом способы оплаты в платежном интерфейсе будут определяться значением страны в параметре user.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.

Чтобы создать виртуальный предмет с региональной ценой:

2. Нажмите Создать вручную и выберите Виртуальный предмет из раскрывающегося списка.

3. В разделе Общие настройки укажите следующее:
   • артикул;
   • одну или несколько групп, к которым должен относиться предмет (опционально);
   • название;
   • краткое описание;
   • расширенное описание — чтобы добавить его, активируйте соответствующий переключатель (опционально).

4. В разделе Медиа загрузите одно или несколько изображений или видео (опционально) — с вашего устройства или по ссылке. В магазине, созданном с помощью редактора сайтов Xsolla, все карточки товаров отображают файл, помеченный как Main, а остальные файлы доступны только в карточках с медиагалереей. Файл, помеченный как Main, также возвращается в ответах методов API получения каталога.

5. В разделе Настройки цен выберите тип товара — Платный предмет.

6. Активируйте переключатель Цены в реальной валюте и нажмите Настроить цены.

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

8. Настройте региональные цены. Вы можете сделать это следующими способами:

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

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

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

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

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

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

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

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

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

10. Чтобы ограничить количество доступных к покупке товаров:

    1. Активируйте переключатель в разделе Лимиты покупок и укажите количество.
    2. Настройте частоту сброса лимита. Для этого выберите период из раскрывающегося списка:
       • Каждый день.
       • Каждую неделю.
       • Каждый месяц.
       • Настроить интервал. Интервал рассчитывается от даты начала отображения предмета в магазине.
       • Без регулярного обновления.
    3. Настройте расписание сброса, указав параметры, которые соответствуют выбранному периоду.

11. Чтобы настроить лимит времени отображения товара (опционально):

    1. Активируйте переключатель в разделе Добавить период отображения.
    2. Укажите часовой пояс, начало и конец периода.

    Чтобы не указывать конец периода отображения товара, активируйте переключатель Без даты окончания.

12. Настройте атрибуты одним из способов (опционально):
    1. Добавьте атрибуты и их значения в формате JSON.
    2. Создайте атрибуты и их значения вручную и привяжите их к товарам.

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

14. Нажмите Создать.

15. В открывшемся окне выберите статус предмета и нажмите Продолжить.

Созданный предмет появится в разделе Все товары.

Чтобы отредактировать цены:

2. Нажмите ⋮ напротив необходимого предмета и в раскрывающемся списке выберите Редактировать.

3. В разделе Настройки цен под ценой по умолчанию нажмите значок редактирования.

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

Возможности:

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

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

Обязательные столбцы файла:

• 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: некорректный порядок сгруппированных по Артикул и Платформа сущностей, из-за чего вместо трех сущностей будет найдено девять.
Ошибка 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

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

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

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

Чтобы выполнить импорт цен из файла:

3. Нажмите Импорт/Экспорт и в раскрывающемся списке в блоке Импортировать выберите пункт Цены из CSV.

4. Загрузите заполненный файл в соответствующее поле в окне импорта.

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

Пример:

Дополнительно вы можете задать региональные цены при импорте товаров через метод 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]