# 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/zh/doc/subscriptions) and the [glossary](https://developers.xsolla.com/zh/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/zh/api/subscriptions/index.yaml)

## 令牌

### 创建令牌

 - [POST /merchants/{merchant_id}/token](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_token/create-token.md): 您可以使用任意用户参数创建令牌。 您在获取令牌时发送这些参数，并在成功付款后接收它们。 令牌只能包含本文档中描述的或由您预定义的参数。

If任何参数以错误的格式发送或具有错误的类型，都不会发出令牌。 您将收到一个422HTTP代码，其中包含JSON正文中的错误描述。 在extended_message中，您将收到错误发送的确切参数的信息。 

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

## 计划

### List plans

 - [GET /projects/{project_id}/subscriptions/plans](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_plans/get-plans.md): 列示所有重复性计划。

### Create plan

 - [POST /projects/{project_id}/subscriptions/plans](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_plans/create-plan.md): 创建重复性计划

### Disable plan

 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_plans/disable-plan.md): 禁用重复性计划。

### Enable plan

 - [PATCH /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_plans/enable-plan.md): 启用重复性计划。

### Update plan

 - [PUT /projects/{project_id}/subscriptions/plans/{plan_id}](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_plans/update-plan-parameters.md): 更新订阅计划参数。

### Delete plan

 - [DELETE /projects/{project_id}/subscriptions/plans/{plan_id}/delete](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_plans/delete-plan.md): 删除重复性计划。

## 产品

### List products

 - [GET /projects/{project_id}/subscriptions/products](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_products/get-products.md): 列示所有重复性产品。

### Create product

 - [POST /projects/{project_id}/subscriptions/products](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_products/create-product.md): 创建产品。

### Delete product

 - [DELETE /projects/{project_id}/subscriptions/products/{product_id}](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_products/delete-product.md): 删除产品。

### Update product

 - [PUT /projects/{project_id}/subscriptions/products/{product_id}](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_products/update-product.md): 更新产品。

## 订阅

### Get user account link

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

### List subscriptions

 - [GET /merchants/{merchant_id}/subscriptions](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_subscriptions/get-subscriptions.md): 列出所有经常订阅。注意这种API方法不能在高负载下使用。 最大负载为每分钟20个请求。 

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Get subscription

 - [GET /projects/{project_id}/subscriptions/{subscription_id}](https://xsolla.redocly.app/zh/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/zh/api/subscriptions/admin_api_subscriptions/update-subscription.md): 更新重复性订阅。可以更新订阅的状态（active、canceled或non_renewing）以及推迟当前订阅的下一次收费日期。

## 支付

### List currencies

 - [GET /projects/{project_id}/subscriptions/currencies](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_payments/get-currencies.md): 列示所有重复性货币。

### List payments

 - [GET /projects/{project_id}/subscriptions/payments](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_payments/get-payments.md): 列示所有重复性支付。

### List user payments

 - [GET /projects/{project_id}/users/{user_id}/subscriptions/payments](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_payments/get-user-payments.md): 按用户列示所有重复性支付。

## 促销活动

### List promotions

 - [GET /merchants/{merchant_id}/promotions](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/get-promotions-list.md): 所有促销活动的列表。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Create promotion

 - [POST /merchants/{merchant_id}/promotions](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/create-promotion.md): 创建一个新的推广。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Delete promotion

 - [DELETE /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/delete-promotion.md): 删除提升。 您只能使用enabled=false删除促销活动。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Get promotion

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/get-promotion.md): 检索促销。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Update promotion

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/update-promotion.md): 更新促销。 如果提升是只读的(read_only=true)，则不允许更改project_id参数。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Get payment systems

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/get-payment-systems.md): 获得支持促销的支付系统。 如果列表为空，促销将适用于所有支付系统。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Set payment systems

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/payment_systems](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/set-payment-systems.md): 设置支持促销的支付系统。 如果列表为空，促销将适用于所有支付系统。 如果提升为只读(read_only=true)，则无法调用此方法。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Get validity periods

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/get-validity-periods.md): 获取促销有效的日期/时间范围。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Set validity periods

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/periods](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/set-validity-periods.md): 获取促销有效的日期/时间范围。设置促销有效的日期/时间范围。 如果促销是只读的(read_only=true)，则不能编辑现有时段，但可以添加新时段。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Review promotion

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/review](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/review-promotion.md): 您需要在激活促销之前查看促销。 此方法返回错误列表（如果有）。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Get rewards

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/get-rewards.md): 获取与促销相关的奖励列表。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Set rewards

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/rewards](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/set-rewards.md): 设置促销的奖励。 如果促销是只读的（read_only=true），则无法更新奖励。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Get promotion scope

 - [GET /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/get-subject.md): 获取有关促销主题的信息。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Set promotion scope

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/subject](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/set-subject.md): 设置促销的主题。 如果提升为只读(read_only=true)，则无法更新主题。 主题可以采用以下值：purchase，或items，或packages。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Toggle promotion

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/toggle](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_promotions/toggle-promotion.md): 将促销的状态从enabled切换到disabled，反之亦然。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

## 优惠券

### Create campaign

 - [POST /merchants/{merchant_id}/coupon_promotions](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_coupons/create-campaign.md): 创建一个新的优惠券活动。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Add coupon to campaign

 - [POST /merchants/{merchant_id}/coupon_promotions/{campaign_id}/coupons](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_coupons/add-coupon-to-campaign.md): 将优惠券代码添加到优惠券活动中。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Attach campaign to promotion

 - [PUT /merchants/{merchant_id}/promotions/{promotion_id}/coupons](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_coupons/attach-campaign-to-promotion.md): 将优惠券活动附加到特定促销活动。

  注意此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

### Get coupon

 - [GET /projects/{project_id}/coupons/{code}/details](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_coupons/get-coupon.md): 按代码获取有关优惠券的信息。

### Redeem coupon

 - [POST /projects/{project_id}/coupons/{code}/redeem](https://xsolla.redocly.app/zh/api/subscriptions/admin_api_coupons/admin-redeem-coupon.md): 按代码兑换优惠券。

## 订阅

### List active subscriptions

 - [GET /api/user/v1/projects/{project_id}/subscriptions](https://xsolla.redocly.app/zh/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/zh/api/subscriptions/client_api_subscriptions/buy-subscription.md)

### Get management link

 - [POST /api/user/v1/projects/{project_id}/subscriptions/manage](https://xsolla.redocly.app/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/api/subscriptions/client_api_catalog/list-public-plans.md)

### Get catalog

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

### List plans

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

### List products

 - [GET /api/user/v1/projects/{project_id}/products](https://xsolla.redocly.app/zh/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/zh/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/zh/api/subscriptions/client_api_coupons/redeem-coupon.md)

## 订阅

### List subscriptions

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions](https://xsolla.redocly.app/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/api/subscriptions/user_management_api_payment-accounts/unlink-payment-account.md)