# Subscriptions API

# Overview {% #overview %}

* **Version:** 2.0
* **Servers**: `https://api.xsolla.com/merchant/v2/`

This API reference describes endpoints for managing subscriptions, coupons, and promotions.
To get more information about Subscriptions, see the [product guide](https://developers.xsolla.com/ru/doc/subscriptions) and the [glossary](https://developers.xsolla.com/ru/doc/subscriptions/integration-guide/get-started/#general_glossary).

Version: 2.0

## Security

### basicAuth

Xsolla API uses basic access authentication. All requests to API must contain the `Authorization: Basic <your_authorization_basic_key>` header, where `<your_authorization_basic_key>` is the `merchant_id:api_key` pair encoded according to the Base64 standard.
Go to **[Xsolla Publisher Account](https://publisher.xsolla.com/) > Company settings** to find <ul><li> `merchant_id` on the Company tab</li><li> `api_key` on the API key tab.</li></ul><br>

Type: http
Scheme: basic

### managementJwtAuth

Type: http
Scheme: bearer

### projectUserJwtAuth

Type: http
Scheme: bearer

## Download OpenAPI description

[Subscriptions API](https://xsolla.redocly.app/_bundle/@l10n/ru/api/subscriptions/index.yaml)

## Токен

### Создание токена

 - [POST /merchants/{merchant_id}/token](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_token/create-token.md): Вы можете создать токен с произвольными пользовательскими параметрами. Вы отправляете эти параметры при получении токена и получаете их обратно после успешной оплаты. Токен может содержать только параметры, описанные в этом документе или предварительно определенные вами. 

Если какой-либо параметр отправлен в неправильном формате или имеет неправильный тип, токен выдан не будет. Вы получите HTTP-код 422 с описанием ошибки в JSON-формате. В extended_message вы получите информацию о том, какие именно параметры были отправлены неправильно. 

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

## Планы

### List plans

 - [GET /projects/{project_id}/subscriptions/plans](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_plans/get-plans.md): Список рекуррентных планов.

### Create plan

 - [POST /projects/{project_id}/subscriptions/plans](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_plans/create-plan.md): Создание рекуррентного плана.

### Disable plan

 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_plans/disable-plan.md): Отключение рекуррентного плана.

### Enable plan

 - [PATCH /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_plans/enable-plan.md): Включить рекуррентный план.

### Update plan

 - [PUT /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_plans/update-plan-parameters.md): Изменение параметров рекуррентного плана.

### Delete plan

 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}/delete](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_plans/delete-plan.md): Удаление рекуррентного плана.

## Продукты

### List products

 - [GET /projects/{project_id}/subscriptions/products](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_products/get-products.md): Lists all subscription-based products.

### Create product

 - [POST /projects/{project_id}/subscriptions/products](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_products/create-product.md): Creates a subscription-based product.

### Delete product

 - [DELETE /projects/{project_id}/subscriptions/products/{product_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_products/delete-product.md): Deletes a subscription-based product.

### Update product

 - [PUT /projects/{project_id}/subscriptions/products/{product_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_products/update-product.md): Updates a subscription-based product.

## Подписки

### Get user account link

 - [POST /api/v1/projects/{projectId}/subscriptions/user_account](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_subscriptions/post-subscriptions-get-user-account-link.md)

### List subscriptions

 - [GET /merchants/{merchant_id}/subscriptions](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_subscriptions/get-subscriptions.md): Выводит список всех повторяющихся подписок.ВниманиеЭтот метод API нельзя использовать при высокой нагрузке. Максимальная нагрузка составляет 20 запросов в минуту. 

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

### Get subscription

 - [GET /projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_subscriptions/get-subscription.md): Информация о конкретной подписке по ID.

### Update subscription

 - [PUT /projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_subscriptions/update-subscription.md): Изменение рекуррентной подписки. Можно изменить статус подписки (active, canceled или non_renewing) и отложить дату следующего списания для данной подписки.

## Платежи

### List currencies

 - [GET /projects/{project_id}/subscriptions/currencies](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_payments/get-currencies.md): Список валют.

### List payments

 - [GET /projects/{project_id}/subscriptions/payments](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_payments/get-payments.md): Список рекуррентных платежей.

### List user payments

 - [GET /projects/{project_id}/users/{user_id}/subscriptions/payments](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_payments/get-user-payments.md): Список рекуррентных платежей пользователя.

## Акции

### List promotions

 - [GET /merchants/{merchant_id}/promotions](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/get-promotions-list.md): Список всех рекламных акций. 

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

### Create promotion

 - [POST /merchants/{merchant_id}/promotions](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/create-promotion.md): Создаёт новую акцию.

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

### Delete promotion

 - [DELETE /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/delete-promotion.md): Удаляет акцию. Вы можете удалять акции только с параметром enabled = false. 

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

### Get promotion

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/get-promotion.md): Извлекает акцию. 

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

### Update promotion

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/update-promotion.md): Обновляет акцию. Если акция доступна только для чтения (read_only = true), вам не разрешается изменять параметр project_id.  

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

### Get payment systems

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/get-payment-systems.md): Получает доступ к платежным системам, поддерживаемым в рамках акции. Если список пуст, акция будет распространяться на все платежные системы. 

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

### Set payment systems

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/set-payment-systems.md): Определяет платежные системы, поддерживаемые для акции. Если список пуст, акция будет применяться ко всем платежным системам. Если акция доступна только для чтения (read_only = true), вы не сможете использовать этот метод. 

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

### Get validity periods

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/get-validity-periods.md): Получает диапазоны дат и времени, в течение которых действует акция.

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

### Set validity periods

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/set-validity-periods.md): Устанавливает диапазоны дат и времени, в течение которых действует акция. Если акция доступна только для чтения (read_only = true), вы не сможете редактировать существующие периоды, но сможете добавлять новые. 

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

### Review promotion

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/review](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/review-promotion.md): Вам необходимо просмотреть акцию, прежде чем активировать ее. Этот метод возвращает список ошибок, если таковые имеются. 

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

### Get rewards

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/get-rewards.md): Получает список вознаграждений, связанных с акцией. 

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

### Set rewards

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/set-rewards.md): Устанавливает вознаграждения за участие в акции. Если акция доступна только для чтения (read_only = true), вы не сможете обновить вознаграждения. 

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

### Get promotion scope

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/get-subject.md): Получает информацию по теме акции. 

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

### Set promotion scope

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/set-subject.md): Определяет тему рекламной акции. Если рекламная акция доступна только для чтения (read_only = true), вы не сможете обновить тему. Тема может принимать следующие значения: purchase, items или packages. 

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

### Toggle promotion

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/toggle](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_promotions/toggle-promotion.md): Переключает статус акции с enabled на disabled и наоборот. 

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

## Купоны

### Create campaign

 - [POST /merchants/{merchant_id}/coupon_promotions](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_coupons/create-campaign.md): Создайте новую купонную кампанию.

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

### Add coupon to campaign

 - [POST /merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_coupons/add-coupon-to-campaign.md): Добавьте код купона в купонную кампанию. 

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

### Attach campaign to promotion

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/coupons](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_coupons/attach-campaign-to-promotion.md): Прикрепите купонную кампанию к определенной акции.

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

### Get coupon

 - [GET /projects/{project_id}/coupons/{code}/details](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_coupons/get-coupon.md): Информация о купоне по его коду.

### Redeem coupon

 - [POST /projects/{project_id}/coupons/{code}/redeem](https://xsolla.redocly.app/ru/api/subscriptions/admin_api_coupons/admin-redeem-coupon.md): Активация купона.

## Подписки

### List active subscriptions

 - [GET /api/user/v1/projects/{project_id}/subscriptions](https://xsolla.redocly.app/ru/api/subscriptions/client_api_subscriptions/get-user-active-subscriptions.md)

### Buy subscription

 - [POST /api/user/v1/projects/{project_id}/subscriptions/buy](https://xsolla.redocly.app/ru/api/subscriptions/client_api_subscriptions/buy-subscription.md)

### Get management link

 - [POST /api/user/v1/projects/{project_id}/subscriptions/manage](https://xsolla.redocly.app/ru/api/subscriptions/client_api_subscriptions/get-manage-subscriptions-link.md)

### Get user account link

 - [GET /api/user/v1/projects/{project_id}/subscriptions/user_account](https://xsolla.redocly.app/ru/api/subscriptions/client_api_subscriptions/get-user-account-link.md)

### Get subscription

 - [GET /api/user/v1/projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/ru/api/subscriptions/client_api_subscriptions/get-user-subscription.md)

### Cancel subscription

 - [PUT /api/user/v1/projects/{project_id}/subscriptions/{subscription_id}/cancel](https://xsolla.redocly.app/ru/api/subscriptions/client_api_subscriptions/cancel-user-subscription.md)

### Renew subscription

 - [POST /api/user/v1/projects/{project_id}/subscriptions/{subscription_id}/renew](https://xsolla.redocly.app/ru/api/subscriptions/client_api_subscriptions/renew-user-subscription.md)

## Catalog

### List products (no auth)

 - [GET /api/public/v1/projects/{project_id}/products](https://xsolla.redocly.app/ru/api/subscriptions/client_api_catalog/list-public-products.md)

### List plans by product (no auth)

 - [GET /api/public/v1/projects/{project_id}/products/{productId}/user_plans](https://xsolla.redocly.app/ru/api/subscriptions/client_api_catalog/list-public-plans-by-product.md)

### List plans (no auth)

 - [GET /api/public/v1/projects/{project_id}/user_plans](https://xsolla.redocly.app/ru/api/subscriptions/client_api_catalog/list-public-plans.md)

### Get catalog

 - [GET /api/user/v1/projects/{project_id}/catalog](https://xsolla.redocly.app/ru/api/subscriptions/client_api_catalog/get-subscriptions-catalog.md)

### List plans

 - [GET /api/user/v1/projects/{project_id}/plans](https://xsolla.redocly.app/ru/api/subscriptions/client_api_catalog/get-subscription-plans.md)

### List products

 - [GET /api/user/v1/projects/{project_id}/products](https://xsolla.redocly.app/ru/api/subscriptions/client_api_catalog/get-subscription-products.md)

### List plans by product

 - [GET /api/user/v1/projects/{project_id}/products/{productId}/plans](https://xsolla.redocly.app/ru/api/subscriptions/client_api_catalog/get-subscription-plans-by-product.md)

## Купоны

### Redeem coupon

 - [POST /api/user/v1/projects/{project_id}/redeem_coupon](https://xsolla.redocly.app/ru/api/subscriptions/client_api_coupons/redeem-coupon.md)

## Подписки

### List subscriptions

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_subscriptions/list-subscriptions.md)

### Get management settings

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/settings](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_subscriptions/get-management-settings.md)

### Get subscription

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_subscriptions/get-management-subscription.md)

### Activate subscription

 - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/activate](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_subscriptions/activate-subscription.md)

### Cancel subscription

 - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/cancel](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_subscriptions/cancel-subscription.md)

### Get change plan link

 - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/change_plan](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_subscriptions/get-change-plan-link.md)

### List plans for change

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_subscriptions/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://xsolla.redocly.app/ru/api/subscriptions/user_management_api_subscriptions/get-plan-for-change.md)

## Payment accounts

### Get payment account

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_payment-accounts/get-payment-account.md)

### Manage payment account

 - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account/manage](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_payment-accounts/manage-payment-account.md)

### List payment accounts

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_payment-accounts/list-payment-accounts.md)

### Link payment account

 - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_payment-accounts/link-payment-account.md)

### Unlink payment account

 - [DELETE /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts/{payment_account_id}](https://xsolla.redocly.app/ru/api/subscriptions/user_management_api_payment-accounts/unlink-payment-account.md)