# 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/doc/subscriptions) and the [glossary](https://developers.xsolla.com/doc/subscriptions/integration-guide/get-started/#general_glossary).


Version: 2.0

## Security

### basicAuth

[object Object]

Type: http
Scheme: basic

### projectUserJwtAuth

Type: http
Scheme: bearer

### managementJwtAuth

Type: http
Scheme: bearer

## Download OpenAPI description

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

## Token

 - [POST /merchants/{merchant_id}/token](https://xsolla.redocly.app/api/subscriptions/admin_api_token/create-token.md): You can create a token with arbitrary user parameters. You send these parameters when obtaining the token and receive them back after a successful payment. A token can only contain parameters either d
## Plans

 - [POST /projects/{project_id}/subscriptions/plans](https://xsolla.redocly.app/api/subscriptions/admin_api_plans/create-plan.md): Creates a subscription plan.
 - [GET /projects/{project_id}/subscriptions/plans](https://xsolla.redocly.app/api/subscriptions/admin_api_plans/get-plans.md): Lists all subscription plans.
 - [PUT /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_plans/update-plan-parameters.md): Updates subscription plan parameters.
 - [PATCH /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_plans/enable-plan.md): Enables a subscription plan.
 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_plans/disable-plan.md): Disables a subscription plan.
 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}/delete](https://xsolla.redocly.app/api/subscriptions/admin_api_plans/delete-plan.md): Deletes a subscription plan.
## Products

 - [POST /projects/{project_id}/subscriptions/products](https://xsolla.redocly.app/api/subscriptions/admin_api_products/create-product.md): Creates a subscription-based product.
 - [GET /projects/{project_id}/subscriptions/products](https://xsolla.redocly.app/api/subscriptions/admin_api_products/get-products.md): Lists all subscription-based products.
 - [PUT /projects/{project_id}/subscriptions/products/{product_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_products/update-product.md): Updates a subscription-based product.
 - [DELETE /projects/{project_id}/subscriptions/products/{product_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_products/delete-product.md): Deletes a subscription-based product.
## Subscriptions

 - [GET /projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_subscriptions/get-subscription.md): Gets a specific subscription details by ID.
 - [PUT /projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_subscriptions/update-subscription.md): Updates a subscription by either changing its status (`active`, `canceled`, or `non_renewing`) or postponing the next billing date.
 - [GET /merchants/{merchant_id}/subscriptions](https://xsolla.redocly.app/api/subscriptions/admin_api_subscriptions/get-subscriptions.md): Lists all recurrent subscriptions.<div class="notice"><strong>Notice</strong><br><br>This API method can’t be used under a high load. The maximum load is 20 requests per minute.</div> <div class="noti
 - [POST /api/v1/projects/{projectId}/subscriptions/user_account](https://xsolla.redocly.app/api/subscriptions/admin_api_subscriptions/post-subscriptions-get-user-account-link.md)
## Payments

 - [GET /projects/{project_id}/subscriptions/payments](https://xsolla.redocly.app/api/subscriptions/admin_api_payments/get-payments.md): Lists all subscription payments.
 - [GET /projects/{project_id}/users/{user_id}/subscriptions/payments](https://xsolla.redocly.app/api/subscriptions/admin_api_payments/get-user-payments.md): Lists all payments made by a specific user.
 - [GET /projects/{project_id}/subscriptions/currencies](https://xsolla.redocly.app/api/subscriptions/admin_api_payments/get-currencies.md): Lists all supported subscription currencies.
## Promotions

 - [POST /merchants/{merchant_id}/promotions](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/create-promotion.md): Create a new promotion. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-parameter, so you need to use the API key that is valid in
 - [GET /merchants/{merchant_id}/promotions](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/get-promotions-list.md): List of all promotions. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-parameter, so you need to use the API key that is valid in
 - [GET /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/get-promotion.md): Retrieves a promotion. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-parameter, so you need to use the API key that is valid in
 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/update-promotion.md): Updates a promotion. If the promotion is read-only (`read_only` = `true`), you are not allowed to change `project_id` parameter. <div class="notice"> <p><strong>Notice</strong></p><p>This API call doe
 - [DELETE /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/delete-promotion.md): Deletes a promotion. You can only delete promotions with `enabled` = `false`. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-para
 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/review](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/review-promotion.md): You need to review a promotion before activating it. This method returns the list of errors, if any. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>proj
 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/set-rewards.md): Sets the rewards for a promotion. If the promotion is read-only (`read_only` = `true`), you cannot update the rewards. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not cont
 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/get-rewards.md): Gets the list of rewards associated with a promotion. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-parameter, so you need to us
 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/toggle](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/toggle-promotion.md): Toggles the status of a promotion from `enabled` to `disabled` and vice versa. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-par
 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/set-subject.md): Sets the subject of a promotion. If the promotion is read-only (`read_only` = `true`), you cannot update the subject. The subject can take the following values: `purchase`, or `items`, or `packages`.
 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/get-subject.md): Gets information on the subject of a promotion. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-parameter, so you need to use the
 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/set-payment-systems.md): Sets payment systems supported for a promotion. If the list is empty, the promotion will apply to all payment systems. If the promotion is read-only (`read_only` = `true`), you cannot call this method
 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/get-payment-systems.md): Gets payment systems supported for a promotion. If the list is empty, the promotion will apply to all payment systems. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not cont
 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/set-validity-periods.md): Sets date/time ranges when a promotion is valid. If the promotion is read-only (`read_only` = `true`), you cannot edit existing periods, but you can add new ones. <div class="notice"> <p><strong>Notic
 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://xsolla.redocly.app/api/subscriptions/admin_api_promotions/get-validity-periods.md): Gets date/time ranges when a promotion is valid. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-parameter, so you need to use the
## Coupons

 - [GET /projects/{project_id}/coupons/{code}/details](https://xsolla.redocly.app/api/subscriptions/admin_api_coupons/get-coupon.md): Get coupon details by its code.
 - [POST /projects/{project_id}/coupons/{code}/redeem](https://xsolla.redocly.app/api/subscriptions/admin_api_coupons/admin-redeem-coupon.md): Redeem a coupon by its code.
 - [POST /merchants/{merchant_id}/coupon_promotions](https://xsolla.redocly.app/api/subscriptions/admin_api_coupons/create-campaign.md): Create a new coupon campaign. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-parameter, so you need to use the API key that is va
 - [POST /merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons](https://xsolla.redocly.app/api/subscriptions/admin_api_coupons/add-coupon-to-campaign.md): Add a coupon code to a coupon campaign. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-parameter, so you need to use the API key
 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/coupons](https://xsolla.redocly.app/api/subscriptions/admin_api_coupons/attach-campaign-to-promotion.md): Attach a coupon campaign to a specific promotion. <div class="notice"> <p><strong>Notice</strong></p><p>This API call does not contain the <code>project_id</code> path-parameter, so you need to use th
## Subscriptions

 - [GET /api/user/v1/projects/{project_id}/subscriptions](https://xsolla.redocly.app/api/subscriptions/client_api_subscriptions/get-user-active-subscriptions.md)
 - [GET /api/user/v1/projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/api/subscriptions/client_api_subscriptions/get-user-subscription.md)
 - [PUT /api/user/v1/projects/{project_id}/subscriptions/{subscription_id}/cancel](https://xsolla.redocly.app/api/subscriptions/client_api_subscriptions/cancel-user-subscription.md)
 - [POST /api/user/v1/projects/{project_id}/subscriptions/{subscription_id}/renew](https://xsolla.redocly.app/api/subscriptions/client_api_subscriptions/renew-user-subscription.md)
 - [POST /api/user/v1/projects/{project_id}/subscriptions/buy](https://xsolla.redocly.app/api/subscriptions/client_api_subscriptions/buy-subscription.md)
 - [POST /api/user/v1/projects/{project_id}/subscriptions/manage](https://xsolla.redocly.app/api/subscriptions/client_api_subscriptions/get-manage-subscriptions-link.md)
 - [GET /api/user/v1/projects/{project_id}/subscriptions/user_account](https://xsolla.redocly.app/api/subscriptions/client_api_subscriptions/get-user-account-link.md)
## Catalog

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

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

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions](https://xsolla.redocly.app/api/subscriptions/user_management_api_subscriptions/list-subscriptions.md)
 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/api/subscriptions/user_management_api_subscriptions/get-management-subscription.md)
 - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/cancel](https://xsolla.redocly.app/api/subscriptions/user_management_api_subscriptions/cancel-subscription.md)
 - [PUT /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/activate](https://xsolla.redocly.app/api/subscriptions/user_management_api_subscriptions/activate-subscription.md)
 - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/change_plan](https://xsolla.redocly.app/api/subscriptions/user_management_api_subscriptions/get-change-plan-link.md)
 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change](https://xsolla.redocly.app/api/subscriptions/user_management_api_subscriptions/list-plans-for-change.md)
 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/plans_for_change/{plan_id}](https://xsolla.redocly.app/api/subscriptions/user_management_api_subscriptions/get-plan-for-change.md)
 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/settings](https://xsolla.redocly.app/api/subscriptions/user_management_api_subscriptions/get-management-settings.md)
## Payment accounts

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account](https://xsolla.redocly.app/api/subscriptions/user_management_api_payment-accounts/get-payment-account.md)
 - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_account/manage](https://xsolla.redocly.app/api/subscriptions/user_management_api_payment-accounts/manage-payment-account.md)
 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://xsolla.redocly.app/api/subscriptions/user_management_api_payment-accounts/list-payment-accounts.md)
 - [POST /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts](https://xsolla.redocly.app/api/subscriptions/user_management_api_payment-accounts/link-payment-account.md)
 - [DELETE /api/user/v1/management/projects/{project_id}/subscriptions/{subscription_id}/payment_accounts/{payment_account_id}](https://xsolla.redocly.app/api/subscriptions/user_management_api_payment-accounts/unlink-payment-account.md)