Перейти к содержимому
/
Обновление акции с промок...

LiveOps API (2.0.0)

Введение

LiveOps is a toolkit for driving ongoing player engagement through promotions and personalized offers.

Use the API to manage the following features:

  • Promotions — create and manage coupons, promo codes, discounts, and bonus campaigns.
  • Personalization — specify the conditions for displaying the item catalog and applying promotions only for certain authorized users.
  • Promotion limits — set a limit on how many times a promotion can be used by a user and configure scheduled resets for these limits.
  • Reward chains & Value points — configure reward progressions tied to value point accumulation.
  • Daily chains — set up recurring daily rewards to motivate regular logins.
  • Offer chains — build sequential purchase offers with per-step pricing and free reward options.
  • Upsell — a sales method in which the user is offered to buy an item with additional value.

Методы API

The API is divided into the following groups:

  • Admin — calls for creating, updating, activating, and deleting campaigns and chain configurations. Authenticated via basic access authentication with your merchant or project credentials.
  • Client — calls for retrieving available promotions, getting active chains, redeeming codes, and claiming rewards on behalf of authenticated end users. Authenticated via user JWT.

Аутентификация

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

Аутентификация с помощью JWT пользователя

Аутентификация с помощью JWT пользователя применяется, когда запрос выполняется из браузера, мобильного приложения или игры. По умолчанию используется XsollaLoginUserJWT. Подробная информация о создании токена приведена в документации Xsolla Login API.

The token is passed in the Authorization header in the following format: Authorization: Bearer <user_JWT>, where <user_JWT> is the user token. The token identifies the user and provides access to personalized data.

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

Базовая HTTP-аутентификация

Базовая HTTP-аутентификация применяется при взаимодействии server-to-server, когда вызов API отправляется напрямую с вашего сервера, а не из браузера пользователя или мобильного приложения. Обычно применяется базовая HTTP-аутентификация с использованием ключа API.

Примечание

Ключ API является конфиденциальным и не должен храниться или использоваться в клиентских приложениях.

При базовой серверной аутентификации все запросы к API должны содержать заголовок:

  • для basicAuth — Authorization: Basic <your_authorization_basic_key>, где your_authorization_basic_key — это пара project_id:api_key, закодированная по стандарту Base64;
  • для basicMerchantAuth — Authorization: Basic <your_authorization_basic_key>, где your_authorization_basic_key — это пара merchant_id:api_key, закодированная по стандарту Base64.

Значения параметров вы можете найти в Личном кабинете:

  • merchant_id отображается:
    • В разделе Настройки компании > Компания.
    • В адресной строке браузера на любой странице Личного кабинета. URL-адрес имеет вид: https://publisher.xsolla.com/<merchant_id>.
  • project_id отображается:
    • В Личном кабинете рядом с названием проекта.
    • В адресной строке браузера при работе с проектом в Личном кабинете. URL-адрес имеет вид: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.
  • api_key отображается в Личном кабинете только при создании и должен храниться на вашей стороне. Создать ключ можно в разделах:
Внимание

Если необходимый метод API не включает в себя path-параметр project_id, используйте для авторизации ключ API, который действует во всех проектах.

Подробная информация о работе с ключами API приведена в справочнике API.

Аутентификация с поддержкой гостевого доступа

Для продажи корзины используется схема аутентификации AuthForCart, которая поддерживает два режима:

  1. Authentication with a user's JWT. The token is passed in the Authorization header in the following format: Authorization: Bearer <user_JWT>, where <user_JWT> is the user token. The token identifies the user and provides access to personalized data. Alternatively, you can use a token for opening the payment UI.

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

    • x-unauthorized-id с ID запроса;
    • x-user с email пользователя, закодированным в формате Base64.

Базовая структура товара

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

Примечание

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

Идентификация

  • merchant_id — ID компании в Личном кабинете;
  • project_id — ID проекта в Личном кабинете;
  • sku — артикул товара, уникальный в рамках проекта.

Отображение в каталоге

  • name — название;
  • description — описание;
  • image_url — ссылка на изображение;
  • is_enabled — доступность товара;
  • is_show_in_store — отображение в каталоге.

Подробнее об управлении доступностью товаров в каталоге – в документации.

Организация

  • type — тип товара, например, виртуальный предмет (virtual_item) или бандл (bundle);
  • groups — группы, к которым относится товар;
  • order — порядок отображения в каталоге.

Условия продажи

  • prices — цены в реальной или виртуальной валюте;
  • limits — ограничения на покупку;
  • periods — период доступности;
  • regions — региональные ограничения.

Пример базовой структуры:

{
  "attributes": [],
  "bundle_type": "virtual_currency_package",
  "content": [
    {
      "description": {
        "en": "Main in-game currency"
      },
      "image_url": "https://.../image.png",
      "name": {
        "en": "Crystals",
        "de": "Kristalle"
      },
      "quantity": 500,
      "sku": "com.xsolla.crystal_2",
      "type": "virtual_currency"
    }
  ],
  "description": {
    "en": "Crystals x500"
  },
  "groups": [],
  "image_url": "https://.../image.png",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": true,
  "limits": {
    "per_item": null,
    "per_user": null,
    "recurrent_schedule": null
  },
  "long_description": null,
  "media_list": [],
  "name": {
    "en": "Medium crystal pack"
  },
  "order": 1,
  "periods": [
    {
      "date_from": null,
      "date_until": "2020-08-11T20:00:00+03:00"
    }
  ],
  "prices": [
    {
      "amount": 20,
      "country_iso": "US",
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "regions": [],
  "sku": "com.xsolla.crystal_pack_2",
  "type": "bundle",
  "vc_prices": []
}

Настройка продажи товаров

Xsolla API позволяет реализовать логику магазина внутриигровых товаров,  включая получение каталога, управление корзиной, создание заказов и отслеживание их статусов. В зависимости от сценария интеграции методы API делятся на подразделы Admin и Catalog, которые используют разные схемы аутентификации.

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

Создание товаров и групп (Admin)

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

Примеры методов:

Настройка акций, цепочек, ограничений (Admin)

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

Примеры методов:

Получение информации о товарах (Client)

Настройте отображение товаров магазина в вашем приложении.

Внимание

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

Примеры методов:

Примечание

По умолчанию в методах получения каталога возвращаются товары, которые отображаются в магазине на момент запроса. Чтобы получить информацию о товарах, период отображения которых еще не наступил или уже истек, передайте параметр "show_inactive_time_limited_items": 1 при запросе каталога.

Продажа товаров

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

  • Быстрая покупка — продажа одного товара, но в любом количестве.
  • Покупка корзины — пользователь наполняет корзину, добавляет и удаляет товары, изменяет количество в одном заказе.

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

Если товар бесплатный, используйте метод Создание заказа с указанным бесплатным товаром или метод Создание заказа с помощью бесплатной корзины. Платежный интерфейс открывать не нужно — заказ сразу переходит в статус done.

Быстрая покупка

Используйте клиентский метод создания заказа с указанным товаром – в ответе вы получите токен, который используется для открытия платежного интерфейса.

Примечание

Информация о скидке доступна пользователю только в платежном интерфейсе. Использование промокодов не предусмотрено.

Покупка корзины

Наполнение и покупка корзины может осуществляться на клиенте или на сервере.

Наполнение и покупка корзины на клиенте

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

Реализуйте следующую логику работы с корзиной:

  1. После наполнения корзины игроком используйте метод Наполнение корзины товарами для наполнения корзины. В ответе вернется текущая информация о выбранных товарах — цены до и после применения скидок, бонусные товары.
  2. Обновите содержимое корзины в соответствии с действиями пользователя:
Примечание

Если вы хотите получить актуальное состояние корзины, используйте метод Получение корзины текущего пользователя.
  1. Используйте метод покупки корзины Создание заказа со всеми товарами из текущей корзины. В ответе вернутся ID заказа и платежный токен. Заказу будет присвоен статус new.

Наполнение и покупка корзины на сервере

Этот вариант наполнения корзины может занимать значительное время на настройку, поскольку каждое изменение корзины может сопровождаться вызовом большего количества методов API.

Реализуйте следующую логику работы с корзиной:

  1. После наполнения корзины игроком используйте методс Наполнение корзины товарамидля наполнения корзины. В ответе вернется текущая информация о выбранных товарах — цены до и после применения скидок, бонусные товары.
  2. Используйте метод покупки корзины Создание заказа со всеми товарами из текущей корзины. В ответе вернутся ID заказа и платежный токен. Заказу будет присвоен статус new.

Открытие платежного интерфейса

Используйте полученный токен для открытия платежного интерфейса в новом окне. Другие способы открытия платежного интерфейса описаны в документации.

ДействиеЭндпоинт
Открыть в боевом окружении.https://secure.xsolla.com/paystation4/?token={token}
Открыть в тестовом окружении.https://sandbox-secure.xsolla.com/paystation4/?token={token}
Примечание

Используйте тестовый режим (sandbox-режим) при разработке и тестировании — при совершении тестовой покупки с реальных счетов не списываются деньги. Для тестирования вы можете использовать тестовые банковские карты.

После проведения первого реального платежа в силу вступает строгая политика платежей в тестовом окружении. Проведение платежа в нем будет доступно только для пользователей, которые указаны в Личном кабинете в разделе Настройки компании > Пользователи.

Покупка виртуальной валюты и виртуальных предметов за реальную валюту возможна после подписания лицензионного договора с Xsolla. Для этого в Личном кабинете перейдите в Договоры и налоги > Договоры, заполните договор и дождитесь подтверждения согласования. Согласование может занять до 3 рабочих дней.

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

Возможные статусы заказа: - new — заказ создан; - paid — оплата получена; - done — товар начислен; - canceled — заказ отменен; - expired — истек срок оплаты.

Отслеживайте статус одним из следующих способов:

Пагинация

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

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

  • limit — количество элементов на странице;
  • offset — номер элемента, с которого выполняется вывод на странице (нумерация ведется с 0);
  • has_more — есть ли следующая страница;
  • total_items_count — общее количество элементов.

Пример запроса:

GET /items?limit=20&offset=40

Пример ответа:

{
  "items": [...],
  "has_more": true,
  "total_items_count": 135
}

Рекомендуется выполнять последовательные запросы до тех пор, пока в ответе не вернется has_more = false.

Формат даты и времени

Дата и время передаются в формате ISO 8601.

Поддерживаются:

  • смещение относительно UTC;
  • значение null, когда нет ограничения времени отображения предмета;
  • в отдельных полях используется Unix timestamp (в секундах).

Формат: YYYY-MM-DDTHH:MM:SS±HH:MM

Пример: 2026-03-16T10:00:00+03:00

Локализация

Xsolla поддерживает локализацию пользовательских полей, таких как название и описание товаров. Локализованные значения передаются в виде объекта, в котором ключом является код языка. Полный список поддерживаемых языков приведен в документации.

Поддерживаемые поля

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

  • name
  • description
  • long_description

Формат локали

Ключ локали может быть указан в одном из следующих форматов:

  • двухбуквенный код языка: en, ru
  • формат язык–страна: en-US, ru-RU, de-DE

Примеры

Пример с двухбуквенным кодом языка:

{
  "name": {
    "en": "Starter Pack",
    "ru": "Стартовый набор"
  }
}

Пример с форматом язык–страна:

{
  "description": {
    "en-US": "Premium bundle",
    "de-DE": "Premium-Paket"
  }
}

Формат ответа при ошибке

При возникновении ошибки API возвращает HTTP-статус и тело ответа в формате JSON. Полный список ошибок в работе магазина приведен в документации.

Пример ответа:

{
  "errorCode": 1102,
  "errorMessage": "Validation error",
  "statusCode": 422,
  "transactionId": "c9e1a..."
}
  • errorCode — код ошибки.
  • errorMessage — краткое описание ошибки.
  • statusCode — HTTP статус ответа.
  • transactionId — ID запроса. Возвращается не во всех случаях.
  • errorMessageExtended — дополнительные данные об ошибке, например параметры запроса. Возвращаются не во всех случаях.

Пример расширенного ответа:

{
  "errorCode": 7001,
  "errorMessage": "Chain not found",
  "errorMessageExtended": {
    "chain_id": "test_chain_id",
    "project_id": "test_project_id",
    "step_number": 2
  },
  "statusCode": 404
}

Частые HTTP-статусы

  • 400 — некорректный запрос
  • 401 — ошибка аутентификации
  • 403 — недостаточно прав доступа
  • 404 — ресурс не найден
  • 422 — ошибка валидации данных
  • 429 — превышено ограничение частоты запросов

Рекомендации

  • Обрабатывайте HTTP-статус и тело ответа совместно.
  • Используйте errorCode для обработки ошибок, связанных с логикой работы приложения.
  • Используйте transactionId, чтобы быстрее идентифицировать запросы при анализе ошибок.
Скачать описание OpenAPI
index.json
index.yaml
Языки
Серверы
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/ru/api/liveops/

Основная информация

Акции — это маркетинговый инструмент для привлечения внимания потенциальных пользователей к товару и повышения уровня продаж. Используя Xsolla API, вы можете настроить следующие акции:

  • Скидки — сниженная цена на выбранные товары.
  • Бонусы — товары, которые начисляются пользователю вместе с покупкой другого товара.
  • Купоны — коды, при вводе которых пользователю начисляется один или несколько бонусных товаров.
  • Промокоды — коды, которые позволяют пользователю получить бонусный товар, скидку на определенный товар или на всю корзину. В отличие от купонов, промокоды погашаются не в момент ввода кода, а при совершения покупки.
  • Уникальные предложения — скрытые товары, которые отображаются в каталоге пользователям, которые ввели код уникального предложения. Если код не введен, товары не отображаются.

Сценарий настройки акции на примере скидочной акции:

  1. Создайте товары с помощью методов подраздела Admin из группы Виртуальные предметы и валюта, Бандлы или Игровые ключи.
  2. Создайте акцию с помощью метода Создание акции со скидками для товара. В массиве items передайте артикулы нужных товаров.
  3. Настройте периоды действия акции. Для этого вызовите метод Создание акции со скидками для товара или Обновление акции со скидками и передайте в нем поле promotion_periods с массивом объектов с датами, где date_from — начало периода действия акции, а date_until — окончание.
  4. Активируйте акцию с помощью метода Обновление акции со скидками. Передайте в нем параметр "is_enabled": true.
  5. Чтобы получать информацию о ценах на товары, включая цены со скидкой, используйте клиентские методы API для получения каталога товаров из подразделов Общие > Catalog, Виртуальные предметы и валюта > Catalog, Бандлы > Catalog.

Пример настройки акции

Подробная информация о работе с каждым видом акций приведена в документации:

Общие методы API

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

Операции

Купоны

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

Примечание

Подробная информация о работе с купонами приведена в документации.

Операции

Промокоды

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

Примечание

Подробная информация о работе с промокодами приведена в документации.

Операции

Получение списка акций с промокодамиServer-sideAdmin

Запрос

Получает список промокодов проекта.

Безопасность
basicAuth
Путь
project_idintegerобязательный

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта, а также в адресной строке браузера при работе с проектом. URL-адрес имеет следующий формат: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.

Пример: 44056
Запрос
limitinteger>= 1

Лимит количества элементов на странице.

Пример: limit=50
offsetinteger>= 0

Номер элемента, с которого выполняется вывод на странице (нумерация ведется с 0).

Пример: offset=0
curl -i -X GET \
  -u <username>:<password> \
  'https://store.xsolla.com/api/v3/project/44056/admin/promocode?limit=50&offset=0'

Ответы

Список промокодов успешно получен.

Телоapplication/json
itemsArray of objects
items[].​external_idstring

Уникальный ID акции. external_id может содержать только строчные и заглавные латинские буквы, цифры, тире и подчеркивания.

items[].​promotion_periodsArray of objects

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

items[].​promotion_periods[].​date_fromstring(date-time)обязательный

Дата начала действия указанной акции.

Пример: "2020-08-11T10:00:00+03:00"
items[].​promotion_periods[].​date_untilstring or null(date-time)

Дата окончания действия указанной акции. Если передано значение null, акция является бессрочной. Может быть null, только если указан один период действия.

Пример: "2020-08-11T20:00:00+03:00"
items[].​nameobject

Название акции. Данный параметр должен содержать пары ключ/значение, где ключ — это локаль в формате "^[a-z]{2}-[A-Z]{2}$", значение — строка.

items[].​name.​property name*stringдополнительное свойство
items[].​bonusArray of objects or null
items[].​bonus[].​skustring

Артикул товара.

По умолчанию "elven_shield"
items[].​bonus[].​quantitynumber

Количество товаров.

По умолчанию 1
items[].​is_enabledboolean
items[].​redeem_total_limitinteger or null

Ограничивает общее количество купонов.

items[].​redeem_user_limitinteger or null

Ограничивает общее количество купонов, погашаемых одним пользователем.

items[].​redeem_code_limitinteger or null

Количество погашений по коду.

items[].​discountobject or null
Пример: {"discount":{"percent":"10.99"}}
items[].​discount.​percentstring or null

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

items[].​discounted_itemsArray of objects or null

Список товаров, на которые действует скидка по промокоду.

items[].​discounted_items[].​skustringобязательный

Артикул товара.

По умолчанию "elven_shield"
items[].​discounted_items[].​discountobjectобязательный
items[].​discounted_items[].​discount.​percentstringобязательный

Процент скидки.

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

items[].​total_limit_stateobject or null

Лимиты для каждого уникального промокода.

items[].​total_limit_state.​availableinteger

Оставшееся количество использований промокода.

Пример: 3
items[].​total_limit_state.​reservedinteger

Зарезервированное количество промокодов.

Пример: 3
items[].​total_limit_state.​usedinteger

Сколько раз использовался промокод.

Пример: 5
items[].​attribute_conditionsArray of objects[ 1 .. 100 ] items

Conditions for validating user attributes. Determine promotion availability based on whether user attributes match all specified conditions.

One of:
items[].​attribute_conditions[].​attributestring[ 1 .. 255 ] characters^[-_.\d\w]+$

Код атрибута пользователя.

items[].​attribute_conditions[].​typestring

Тип атрибута пользователя.

Значение"string"
items[].​attribute_conditions[].​operatorstring

Тип операции, выполняемой по условию. Для типа атрибута string.

Possible values:

  • eq — Equals
  • ne — Not equals
Перечисление"eq""ne"
items[].​attribute_conditions[].​valuestring<= 255 characters

Значение условия, с которым будет сравниваться значение атрибута пользователя. Тип зависит от типа атрибута.

items[].​attribute_conditions[].​can_be_missingboolean

Считается ли условие выполненным, если этот атрибут отсутствует в атрибутах пользователя. Передайте true, чтобы показывать товар пользователям, у которых нет этого атрибута. Пользователи у которых атрибут есть, но значение не совпадает с указанным в условии, не увидят товар. false — пользователи у которых атрибут есть, но значение не совпадает с указанным в условии, или атрибута нет, не увидят товар.

items[].​price_conditionsArray of objects or null

Массив объектов с условиями, задающими ценовой диапазон применения акции для отдельных товаров в корзине.
Стоимость каждого товара в корзине пользователя сравнивается с заданным в условии ценовым диапазоном. Бонусы и скидки применяются только к тем товарам в корзине, цена которых удовлетворяет условию.
Если вы передаете этот массив, в массиве discounted_items передайте значение null.

items[].​price_conditions[].​operatorstringобязательный

Оператор сравнения для задания ценового диапазона применения акции.

Possible values:

  • ge — Greater or equal
  • gt — Greater than
  • le — Less or equal
  • lt — Less than
  • eq — Equals
  • ne — Not equals
Перечисление"ge""gt""le""lt""eq""ne"
items[].​price_conditions[].​valuestring^\d+(\.\d{1,4})?$обязательный

Значение для определения ценового диапазона применения акции.

items[].​item_price_conditionsArray of objects or null

Массив объектов с условиями, задающими ценовой диапазон применения акции для отдельных товаров в корзине.
Стоимость каждого товара в корзине пользователя сравнивается с заданным в условии ценовым диапазоном. Бонусы и скидки применяются только к тем товарам в корзине, цена которых удовлетворяет условию.
Если вы передаете этот массив, в массиве discounted_items передайте значение null.

items[].​item_price_conditions[].​operatorstringобязательный

Оператор сравнения для задания ценового диапазона применения акции.

Possible values:

  • ge — Greater or equal
  • gt — Greater than
  • le — Less or equal
  • lt — Less than
  • eq — Equals
  • ne — Not equals
Перечисление"ge""gt""le""lt""eq""ne"
items[].​item_price_conditions[].​valuestring^\d+(\.\d{1,4})?$обязательный

Значение для определения ценового диапазона применения акции.

items[].​excluded_promotionsArray of integers

Список акций, которые исключаются при применении этой акции.
Example: [12, 789]

total_promotions_countinteger

Общее количество акций.

active_promotions_countinteger

Количество активных акций.

inactive_promotions_countinteger

Количество отключенных акций.

Ответ
application/json
{
  "items": [
    { … },
    { … }
  ],
  "total_promotions_count": 2,
  "active_promotions_count": 2,
  "inactive_promotions_count": 0
}

Обновление акции с промокодамиServer-sideAdmin

Запрос

Обновляет акцию с промокодами.

Безопасность
basicAuth
Путь
project_idintegerобязательный

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта, а также в адресной строке браузера при работе с проектом. URL-адрес имеет следующий формат: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.

Пример: 44056
external_idintegerобязательный

External ID акции. Уникальный идентификатор акции в рамках проекта.

Пример: coupon_44056_1
Телоapplication/json
promotion_periodsArray of objects

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

promotion_periods[].​date_fromstring(date-time)обязательный

Дата начала действия указанной акции.

Пример: "2020-08-11T10:00:00+03:00"
promotion_periods[].​date_untilstring or null(date-time)

Дата окончания действия указанной акции. Если передано значение null, акция является бессрочной. Может быть null, только если указан один период действия.

Пример: "2020-08-11T20:00:00+03:00"
nameobjectобязательный

Название акции. Данный параметр должен содержать пары ключ/значение, где ключ — это локаль в формате "^[a-z]{2}-[A-Z]{2}$", значение — строка.

name.​property name*stringдополнительное свойство
bonusArray of objects or null
bonus[].​skustring

Артикул товара.

По умолчанию "elven_shield"
bonus[].​quantitynumber

Количество товаров.

По умолчанию 1
redeem_total_limitinteger or null

Ограничивает общее количество купонов.

redeem_user_limitinteger or null

Ограничивает общее количество купонов, погашаемых одним пользователем.

redeem_code_limitinteger or null

Количество погашений по коду.

discountobject or null
Пример: {"percent":"10.10"}
discount.​percentstring or null

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

Пример: "10.10"
discounted_itemsArray of objects or null

Список товаров, на которые действует скидка по промокоду.

discounted_items[].​skustringобязательный

Артикул товара.

По умолчанию "elven_shield"
discounted_items[].​discountobjectобязательный
discounted_items[].​discount.​percentstringобязательный

Процент скидки.

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

attribute_conditionsArray of objects[ 1 .. 100 ] items

Conditions for validating user attributes. Determine promotion availability based on whether user attributes match all specified conditions.

One of:
attribute_conditions[].​attributestring[ 1 .. 255 ] characters^[-_.\d\w]+$обязательный

Код атрибута пользователя.

attribute_conditions[].​typestringобязательный

Тип атрибута пользователя.

Значение"string"
attribute_conditions[].​operatorstringобязательный

Тип операции, выполняемой по условию. Для типа атрибута string.

Possible values:

  • eq — Equals
  • ne — Not equals
Перечисление"eq""ne"
attribute_conditions[].​valuestring<= 255 charactersобязательный

Значение условия, с которым будет сравниваться значение атрибута пользователя. Тип зависит от типа атрибута.

attribute_conditions[].​can_be_missingboolean

Считается ли условие выполненным, если этот атрибут отсутствует в атрибутах пользователя. Передайте true, чтобы показывать товар пользователям, у которых нет этого атрибута. Пользователи у которых атрибут есть, но значение не совпадает с указанным в условии, не увидят товар. false — пользователи у которых атрибут есть, но значение не совпадает с указанным в условии, или атрибута нет, не увидят товар.

price_conditionsArray of objects or null

Массив объектов с условиями, задающими ценовой диапазон применения акции для отдельных товаров в корзине.
Стоимость каждого товара в корзине пользователя сравнивается с заданным в условии ценовым диапазоном. Бонусы и скидки применяются только к тем товарам в корзине, цена которых удовлетворяет условию.
Если вы передаете этот массив, в массиве discounted_items передайте значение null.

price_conditions[].​operatorstringобязательный

Оператор сравнения для задания ценового диапазона применения акции.

Possible values:

  • ge — Greater or equal
  • gt — Greater than
  • le — Less or equal
  • lt — Less than
  • eq — Equals
  • ne — Not equals
Перечисление"ge""gt""le""lt""eq""ne"
price_conditions[].​valuestring^\d+(\.\d{1,4})?$обязательный

Значение для определения ценового диапазона применения акции.

item_price_conditionsArray of objects or null

Массив объектов с условиями, задающими ценовой диапазон применения акции для отдельных товаров в корзине.
Стоимость каждого товара в корзине пользователя сравнивается с заданным в условии ценовым диапазоном. Бонусы и скидки применяются только к тем товарам в корзине, цена которых удовлетворяет условию.
Если вы передаете этот массив, в массиве discounted_items передайте значение null.

item_price_conditions[].​operatorstringобязательный

Оператор сравнения для задания ценового диапазона применения акции.

Possible values:

  • ge — Greater or equal
  • gt — Greater than
  • le — Less or equal
  • lt — Less than
  • eq — Equals
  • ne — Not equals
Перечисление"ge""gt""le""lt""eq""ne"
item_price_conditions[].​valuestring^\d+(\.\d{1,4})?$обязательный

Значение для определения ценового диапазона применения акции.

excluded_promotionsArray of integers

Список акций, которые исключаются при применении этой акции.
Example: [12, 789]

curl -i -X PUT \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/promocode/coupon_44056_1 \
  -H 'Content-Type: application/json' \
  -d '{
    "promotion_periods": [
      {
        "date_from": "2020-04-15T18:16:00+05:00",
        "date_until": "2020-04-25T18:16:00+05:00"
      },
      {
        "date_from": "2020-05-15T18:16:00+05:00",
        "date_until": "2020-05-25T18:16:00+05:00"
      }
    ],
    "name": {
      "en-US": "New Year Bonus",
      "de-DE": "Neujahrsbonus"
    },
    "redeem_total_limit": 100,
    "redeem_user_limit": 1,
    "redeem_code_limit": 1,
    "bonus": [
      {
        "sku": "com.xsolla.elven_sword_1",
        "quantity": 1
      },
      {
        "sku": "com.xsolla.elven_shield_1",
        "quantity": 2
      },
      {
        "sku": "com.xsolla.elven_gloves_1",
        "quantity": 2
      }
    ]
  }'

Ответы

Promo code was successfully updated.

Ответ
Нет содержимого

Получение акции с промокодамиServer-sideAdmin

Запрос

Получает указанную акцию с промокодами.

Безопасность
basicAuth
Путь
project_idintegerобязательный

ID проекта. Вы можете найти этот параметр в Личном кабинете рядом с названием проекта, а также в адресной строке браузера при работе с проектом. URL-адрес имеет следующий формат: https://publisher.xsolla.com/<merchant_id>/projects/<project_id>.

Пример: 44056
external_idintegerобязательный

External ID акции. Уникальный идентификатор акции в рамках проекта.

Пример: coupon_44056_1
curl -i -X GET \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/promocode/coupon_44056_1

Ответы

Promo code was successfully received.

Телоapplication/json
external_idstring

Уникальный ID акции. external_id может содержать только строчные и заглавные латинские буквы, цифры, тире и подчеркивания.

promotion_periodsArray of objects

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

promotion_periods[].​date_fromstring(date-time)обязательный

Дата начала действия указанной акции.

Пример: "2020-08-11T10:00:00+03:00"
promotion_periods[].​date_untilstring or null(date-time)

Дата окончания действия указанной акции. Если передано значение null, акция является бессрочной. Может быть null, только если указан один период действия.

Пример: "2020-08-11T20:00:00+03:00"
nameobject

Название акции. Данный параметр должен содержать пары ключ/значение, где ключ — это локаль в формате "^[a-z]{2}-[A-Z]{2}$", значение — строка.

name.​property name*stringдополнительное свойство
bonusArray of objects or null
bonus[].​skustring

Артикул товара.

По умолчанию "elven_shield"
bonus[].​quantitynumber

Количество товаров.

По умолчанию 1
is_enabledboolean
redeem_total_limitinteger or null

Ограничивает общее количество купонов.

redeem_user_limitinteger or null

Ограничивает общее количество купонов, погашаемых одним пользователем.

redeem_code_limitinteger or null

Количество погашений по коду.

discountobject or null
Пример: {"discount":{"percent":"10.99"}}
discount.​percentstring or null

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

discounted_itemsArray of objects or null

Список товаров, на которые действует скидка по промокоду.

discounted_items[].​skustringобязательный

Артикул товара.

По умолчанию "elven_shield"
discounted_items[].​discountobjectобязательный
discounted_items[].​discount.​percentstringобязательный

Процент скидки.

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

total_limit_stateobject or null

Лимиты для каждого уникального промокода.

total_limit_state.​availableinteger

Оставшееся количество использований промокода.

Пример: 3
total_limit_state.​reservedinteger

Зарезервированное количество промокодов.

Пример: 3
total_limit_state.​usedinteger

Сколько раз использовался промокод.

Пример: 5
attribute_conditionsArray of objects[ 1 .. 100 ] items

Conditions for validating user attributes. Determine promotion availability based on whether user attributes match all specified conditions.

One of:
attribute_conditions[].​attributestring[ 1 .. 255 ] characters^[-_.\d\w]+$

Код атрибута пользователя.

attribute_conditions[].​typestring

Тип атрибута пользователя.

Значение"string"
attribute_conditions[].​operatorstring

Тип операции, выполняемой по условию. Для типа атрибута string.

Possible values:

  • eq — Equals
  • ne — Not equals
Перечисление"eq""ne"
attribute_conditions[].​valuestring<= 255 characters

Значение условия, с которым будет сравниваться значение атрибута пользователя. Тип зависит от типа атрибута.

attribute_conditions[].​can_be_missingboolean

Считается ли условие выполненным, если этот атрибут отсутствует в атрибутах пользователя. Передайте true, чтобы показывать товар пользователям, у которых нет этого атрибута. Пользователи у которых атрибут есть, но значение не совпадает с указанным в условии, не увидят товар. false — пользователи у которых атрибут есть, но значение не совпадает с указанным в условии, или атрибута нет, не увидят товар.

price_conditionsArray of objects or null

Массив объектов с условиями, задающими ценовой диапазон применения акции для отдельных товаров в корзине.
Стоимость каждого товара в корзине пользователя сравнивается с заданным в условии ценовым диапазоном. Бонусы и скидки применяются только к тем товарам в корзине, цена которых удовлетворяет условию.
Если вы передаете этот массив, в массиве discounted_items передайте значение null.

price_conditions[].​operatorstringобязательный

Оператор сравнения для задания ценового диапазона применения акции.

Possible values:

  • ge — Greater or equal
  • gt — Greater than
  • le — Less or equal
  • lt — Less than
  • eq — Equals
  • ne — Not equals
Перечисление"ge""gt""le""lt""eq""ne"
price_conditions[].​valuestring^\d+(\.\d{1,4})?$обязательный

Значение для определения ценового диапазона применения акции.

item_price_conditionsArray of objects or null

Массив объектов с условиями, задающими ценовой диапазон применения акции для отдельных товаров в корзине.
Стоимость каждого товара в корзине пользователя сравнивается с заданным в условии ценовым диапазоном. Бонусы и скидки применяются только к тем товарам в корзине, цена которых удовлетворяет условию.
Если вы передаете этот массив, в массиве discounted_items передайте значение null.

item_price_conditions[].​operatorstringобязательный

Оператор сравнения для задания ценового диапазона применения акции.

Possible values:

  • ge — Greater or equal
  • gt — Greater than
  • le — Less or equal
  • lt — Less than
  • eq — Equals
  • ne — Not equals
Перечисление"ge""gt""le""lt""eq""ne"
item_price_conditions[].​valuestring^\d+(\.\d{1,4})?$обязательный

Значение для определения ценового диапазона применения акции.

excluded_promotionsArray of integers

Список акций, которые исключаются при применении этой акции.
Example: [12, 789]

Ответ
application/json
{
  "external_id": "summer20221",
  "promotion_periods": [
    { … },
    { … }
  ],
  "name": {
    "en-US": "Coupon name",
    "ru-RU": "Название купона"
  },
  "is_enabled": true,
  "bonus": [
    { … }
  ],
  "redeem_user_limit": null,
  "redeem_total_limit": 100,
  "redeem_code_limit": 1,
  "discount": {
    "percent": "10.99"
  },
  "discounted_items": null,
  "total_limit_state": {
    "available": 50,
    "reserved": 10,
    "used": 40
  },
  "excluded_promotions": [
    23,
    45
  ]
}

Уникальный каталог предложений

Используйте методы из этого подраздела для настройки и управления уникальными предложениями в каталоге.

Примечание

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

Операции

Скидки

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

Примечание

Подробная информация о работе со скидками приведена в документации.

Операции

Бонусы

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

Примечание

Подробная информация о работе с бонусами приведена в документации.

Операции

Персонализированный каталог

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

Доступны следующие типы персонализации:

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

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

Чтобы настроить персонализацию на стороне Xsolla с помощью Xsolla API:

  1. Создайте товары с помощью методов подраздела Admin из группы Виртуальные предметы и валюта, Бандлы или Игровые ключи.

  2. Настройте атрибуты пользователя, используя Xsolla Login API и поддерживайте значения атрибутов в актуальном состоянии: обновляйте их в Xsolla, когда они меняются у пользователя в игре.

  3. Настройте персонализацию для товаров или акций:

    • Для персонализации каталога товаров задайте правила отображения каталога с помощью метода Создание правила фильтрации каталога:
      • В массиве attribute_conditions укажите условия доступности товаров в каталоге на основе проверки атрибутов пользователя.
      • В массиве items передайте список товаров, которые должен видеть пользователь, если значения его атрибутов соответствуют условиям.
    • Для настройки персонализированных акций используйте методы создания и обновления акции нужного типа и в массиве attribute_conditions передайте условия, которые определяют доступность акции на основе проверки атрибутов пользователя.

  4. Передайте JWT пользователя с его атрибутами в методы получения каталога товаров, чтобы получить персонализированный каталог.

Процесс настройки и применения персонализации на стороне Xsolla для товаров каталога:

Персонализация каталога товаров

Процесс настройки и применения персонализации на стороне Xsolla для акций:

Персонализация акций

Примечание

Подробная информация приведена:
Операции

Основная информация

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

Лимиты хранятся на стороне Xsolla и задаются в настройках каждой акции в Личном кабинете или через объект limits в следующих методах API:

Информация о лимитах возвращается в объекте items.promotions.limits в методах API получения каталога товаров:

Методы подраздела Управление из группы методов Лимиты позволяют получать информацию о текущем состоянии лимитов и изменять их для конкретного пользователя — например, сбрасывать счетчик после выполнения квеста или корректировать остаток вручную.

Примечание

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

Вы можете настроить limits.per_user —  лимит на количество использований акции для одного пользователя.

Для неавторизованного пользователя всегда отображается максимальное количество использований акции.

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

Чтобы настроить период автоматического обновления — ежедневно, еженедельно или ежемесячно, передайте объект limits.recurrent_schedule при создании или обновлении акции.

Limit configuration and enforcement scenario

  1. Вы создаете акцию через методы API Создание акции со скидками для товара или Создание акции с бонусами и передаете объект limits.
  2. Вы запрашиваете каталог для неавторизованного пользователя — в ответе возвращается максимальное количество использований акции в объекте items.promotions.limits.
  3. Пользователь авторизуется.
  4. Вы запрашиваете каталог, передавая авторизационный токен пользователя — в ответе возвращается оставшееся количество использований с учетом действующего лимита.
  5. Пользователь выбирает акционный товар и совершает покупку.
  6. После успешного платежа Xsolla уменьшает значение параметра items.promotions.limits.per_user. Когда значение этого параметра достигает 0, товар возвращается в методах запроса каталога — без скидки или бонуса.
  7. Вы можете обновить лимит через методы подраздела Управление:
  8. Вы получаете обновленное значение лимита в items.promotions.limits при следующем запросе каталога с авторизационным токеном пользователя и отображаете его пользователю.

Лимиты на использование акций

Управление

Операции

Основная информация

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

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

Пример сценария настройки цепочки наград:

  1. Создайте товары с помощью методов API из подраздела Admin групп методов Виртуальные предметы и валюта или Бандлы.
  2. Создайте призовые баллы с помощью метода API Создание призовых баллов.
  3. Привяжите призовые баллы к товарам с помощью метода API Настройка призовых баллов для товаров. Пользователи получат эти баллы после покупки товаров.
  4. Создайте цепочку с помощью метода API Создание цепочки наград. Чтобы активировать цепочку, передайте параметр is_enabled: true.
  5. Реализуйте отображение цепочек наград. Для этого запросите список доступных пользователю цепочек с помощью метода API Получение цепочек наград для текущего пользователя. В ответе содержатся все активные цепочки с шагами и их статусами.
  6. Реализуйте отображение текущего баланса призовых баллов. Для этого вызовите метод API Получение баланса призовых баллов для текущего пользователя.
  7. Реализуйте получение награды пользователем. Для этого вызовите метод API Получение награды на уровне.
  8. Настройте отслеживание статуса заказа, например с помощью вебхуков, чтобы своевременно получать данные о запрошенных наградах и начислять их пользователю.

Пример настройки цепочки наград

Admin

Операции

Клиент

Операции

Клиент кланов

Операции

Admin

Операции

Клиент

Операции

Основная информация

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

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

Пример сценария настройки цепочки предложений:

  1. Создайте товары с помощью методов API из подраздела Admin групп методов Виртуальные предметы и валюта или Бандлы.

  2. Создайте цепочку с помощью метода API Создание цепочки предложений. Чтобы активировать цепочку, передайте параметр is_enabled: true.

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

  4. Реализуйте логику работы с товарами, которые получает пользователь:

  5. Настройте отслеживание статуса заказа, например, с помощью вебхуков, чтобы своевременно получать данные о запрошенных или оплаченных товарах и начислять их пользователю.

Reward chain configuration flow

Admin

Операции

Клиент

Операции

Admin

Операции

Клиент

Операции