# Subscriptions API # Введение * **Версия:** 2.0 * **Серверы**: `https://api.xsolla.com/merchant/v2/` Этот справочник API описывает методы для управления подписками, купонами и акциями. Подробная информация о продукте Subscriptions приведена в [руководстве по продукту](https://developers.xsolla.com/ru/doc/subscriptions) и [глоссарии](https://developers.xsolla.com/ru/doc/subscriptions/integration-guide/get-started/#general_glossary). Version: 2.0 ## Security ### basicAuth Xsolla API использует базовую HTTP-аутентификацию. Все запросы к API должны содержать заголовок `Authorization: Basic `, где `` — пара `merchant_id:api_key`, закодированная по стандарту Base64. Значения параметров вы можете найти в [Личном кабинете](https://publisher.xsolla.com/):
Подробная информация о работе с ключами API приведена в [справочнике API](https://developers.xsolla.com/ru/api/getting-started/#api_keys_overview). Type: http Scheme: basic ### subscriptionsManagementJwtAuth Type: http Scheme: bearer ## Download OpenAPI description [Subscriptions API](https://developers.xsolla.com/_bundle/@l10n/ru/api/subscriptions/index.yaml) ## Токен ### Создание токена - [POST /merchants/{merchant_id}/token](https://developers.xsolla.com/ru/api/subscriptions/token/create-token.md): Вы можете создать токен с произвольными пользовательскими параметрами. Вы отправляете эти параметры при получении токена и получаете их обратно после успешной оплаты. Токен может содержать только параметры, описанные в этом документе или предварительно определенные вами. Если какой-либо параметр отправлен в неправильном формате или имеет неправильный тип, токен выдан не будет. Вы получите HTTP-код 422 с описанием ошибки в JSON-формате. В extended_message вы получите информацию о том, какие именно параметры были отправлены неправильно. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ## Планы ### Список планов - [GET /projects/{project_id}/subscriptions/plans](https://developers.xsolla.com/ru/api/subscriptions/plans/get-plans.md): Список рекуррентных планов. ### Создание плана - [POST /projects/{project_id}/subscriptions/plans](https://developers.xsolla.com/ru/api/subscriptions/plans/create-plan.md): Создание рекуррентного плана. ### Отключение плана - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}](https://developers.xsolla.com/ru/api/subscriptions/plans/disable-plan.md): Отключение рекуррентного плана. ### Включение плана - [PATCH /projects/{project_id}/subscriptions/plans/{plan_id}](https://developers.xsolla.com/ru/api/subscriptions/plans/enable-plan.md): Включить рекуррентный план. ### Обновление плана - [PUT /projects/{project_id}/subscriptions/plans/{plan_id}](https://developers.xsolla.com/ru/api/subscriptions/plans/update-plan-parameters.md): Изменение параметров рекуррентного плана. ### Удаление плана - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}/delete](https://developers.xsolla.com/ru/api/subscriptions/plans/delete-plan.md): Удаление рекуррентного плана. ## Продукты ### Список продуктов - [GET /projects/{project_id}/subscriptions/products](https://developers.xsolla.com/ru/api/subscriptions/products/get-products.md): Lists all subscription-based products. ### Создание продукта - [POST /projects/{project_id}/subscriptions/products](https://developers.xsolla.com/ru/api/subscriptions/products/create-product.md): Creates a subscription-based product. ### Удаление продукта - [DELETE /projects/{project_id}/subscriptions/products/{product_id}](https://developers.xsolla.com/ru/api/subscriptions/products/delete-product.md): Deletes a subscription-based product. ### Изменение продукта - [PUT /projects/{project_id}/subscriptions/products/{product_id}](https://developers.xsolla.com/ru/api/subscriptions/products/update-product.md): Updates a subscription-based product. ## Subscription management ### Список подписок - [GET /merchants/{merchant_id}/subscriptions](https://developers.xsolla.com/ru/api/subscriptions/subscriptions/get-subscriptions.md): Выводит список всех повторяющихся подписок.ВниманиеЭтот метод API нельзя использовать при высокой нагрузке. Максимальная нагрузка составляет 20 запросов в минуту. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Информация о подписке - [GET /projects/{project_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/ru/api/subscriptions/subscriptions/get-subscription.md): Информация о конкретной подписке по ID. ### Изменение подписки - [PUT /projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/ru/api/subscriptions/subscriptions/update-subscription.md): Изменение рекуррентной подписки. Можно изменить статус подписки (active, canceled или non_renewing) и отложить дату следующего списания для данной подписки. ## Платежи ### Список валют - [GET /projects/{project_id}/subscriptions/currencies](https://developers.xsolla.com/ru/api/subscriptions/payments/get-currencies.md): Список валют. ### Список платежей - [GET /projects/{project_id}/subscriptions/payments](https://developers.xsolla.com/ru/api/subscriptions/payments/get-payments.md): Список рекуррентных платежей. ### Список платежей пользователя - [GET /projects/{project_id}/users/{user_id}/subscriptions/payments](https://developers.xsolla.com/ru/api/subscriptions/payments/get-user-payments.md): Список рекуррентных платежей пользователя. ## Акции ### Список акций - [GET /merchants/{merchant_id}/promotions](https://developers.xsolla.com/ru/api/subscriptions/promotions/get-promotions-list.md): Список всех рекламных акций. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Создание акции - [POST /merchants/{merchant_id}/promotions](https://developers.xsolla.com/ru/api/subscriptions/promotions/create-promotion.md): Создаёт новую акцию. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Удаление акции - [DELETE /merchants/{merchant_id}/promotions/{promotion_id}](https://developers.xsolla.com/ru/api/subscriptions/promotions/delete-promotion.md): Удаляет акцию. Вы можете удалять акции только с параметром enabled = false. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Информация об акции - [GET /merchants/{merchant_id}/promotions/{promotion_id}](https://developers.xsolla.com/ru/api/subscriptions/promotions/get-promotion.md): Извлекает акцию. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Изменение акции - [PUT /merchants/{merchant_id}/promotions/{promotion_id}](https://developers.xsolla.com/ru/api/subscriptions/promotions/update-promotion.md): Обновляет акцию. Если акция доступна только для чтения (read_only = true), вам не разрешается изменять параметр project_id. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Список платежных систем - [GET /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://developers.xsolla.com/ru/api/subscriptions/promotions/get-payment-systems.md): Получает доступ к платежным системам, поддерживаемым в рамках акции. Если список пуст, акция будет распространяться на все платежные системы. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Настройка способов оплаты - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://developers.xsolla.com/ru/api/subscriptions/promotions/set-payment-systems.md): Определяет платежные системы, поддерживаемые для акции. Если список пуст, акция будет применяться ко всем платежным системам. Если акция доступна только для чтения (read_only = true), вы не сможете использовать этот метод. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Информация о периодах - [GET /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://developers.xsolla.com/ru/api/subscriptions/promotions/get-validity-periods.md): Получает диапазоны дат и времени, в течение которых действует акция. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Настройка периодов - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://developers.xsolla.com/ru/api/subscriptions/promotions/set-validity-periods.md): Устанавливает диапазоны дат и времени, в течение которых действует акция. Если акция доступна только для чтения (read_only = true), вы не сможете редактировать существующие периоды, но сможете добавлять новые. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Проверка акции - [GET /merchants/{merchant_id}/promotions/{promotion_id}/review](https://developers.xsolla.com/ru/api/subscriptions/promotions/review-promotion.md): Вам необходимо просмотреть акцию, прежде чем активировать ее. Этот метод возвращает список ошибок, если таковые имеются. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Список вознаграждений - [GET /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://developers.xsolla.com/ru/api/subscriptions/promotions/get-rewards.md): Получает список вознаграждений, связанных с акцией. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Настройка вознаграждений - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://developers.xsolla.com/ru/api/subscriptions/promotions/set-rewards.md): Устанавливает вознаграждения за участие в акции. Если акция доступна только для чтения (read_only = true), вы не сможете обновить вознаграждения. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Информация о предмете акции - [GET /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://developers.xsolla.com/ru/api/subscriptions/promotions/get-subject.md): Получает информацию по теме акции. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Настройка предмета акции - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://developers.xsolla.com/ru/api/subscriptions/promotions/set-subject.md): Определяет тему рекламной акции. Если рекламная акция доступна только для чтения (read_only = true), вы не сможете обновить тему. Тема может принимать следующие значения: purchase, items или packages. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Переключатель акции - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/toggle](https://developers.xsolla.com/ru/api/subscriptions/promotions/toggle-promotion.md): Переключает статус акции с enabled на disabled и наоборот. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ## Купоны ### Создание кампании - [POST /merchants/{merchant_id}/coupon_promotions](https://developers.xsolla.com/ru/api/subscriptions/coupons/create-campaign.md): Создайте новую купонную кампанию. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Добавление купона в кампанию - [POST /merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons](https://developers.xsolla.com/ru/api/subscriptions/coupons/add-coupon-to-campaign.md): Добавьте код купона в купонную кампанию. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Привязка кампании к акции - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/coupons](https://developers.xsolla.com/ru/api/subscriptions/coupons/attach-campaign-to-promotion.md): Прикрепите купонную кампанию к определенной акции. Внимание Этот метод API не включает в себя path-параметр project_id, поэтому для авторизации вам необходимо использовать ключ API, который действует во всех проектах. ### Информация о купоне - [GET /projects/{project_id}/coupons/{code}/details](https://developers.xsolla.com/ru/api/subscriptions/coupons/get-coupon.md): Информация о купоне по его коду. ### Активация купона - [POST /projects/{project_id}/coupons/{code}/redeem](https://developers.xsolla.com/ru/api/subscriptions/coupons/redeem-coupon.md): Активация купона. ## Subscription management ### List subscriptions - [GET /api/user/v1/management/projects/{project_id}/subscriptions](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/list-subscriptions.md) ### Get management settings - [GET /api/user/v1/management/projects/{project_id}/subscriptions/settings](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/get-management-settings.md) ### Get subscription - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/get-management-subscription.md) ### Activate subscription - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/activate](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/activate-subscription.md) ### Cancel subscription - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/cancel](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/cancel-subscription.md) ### Get change plan link - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/change_plan](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/get-change-plan-link.md) ### Get payment account - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/get-payment-account.md) ### Manage payment account - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account/manage](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/manage-payment-account.md) ### List payment accounts - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/list-payment-accounts.md) ### Link payment account - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/link-payment-account.md) ### Unlink payment account - [DELETE /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts/{payment_account_id}](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/unlink-payment-account.md) ### List plans for change - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/list-plans-for-change.md) ### Get plan for change - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change/{plan_id}](https://developers.xsolla.com/ru/api/subscriptions/subscription-management/get-plan-for-change.md)