# Subscriptions API

# 概览

* **Version:** 2.0
* **服务器**：`https://api.xsolla.com/merchant/v2/`

本API参考介绍管理订阅、优惠券和促销活动的端点。
如需了解关于订阅的详细信息，请参考[产品指南](https://developers.xsolla.com/zh/doc/subscriptions)和[词汇表](https://developers.xsolla.com/zh/doc/subscriptions/integration-guide/get-started/#general_glossary)。

Version: 2.0

## Security

### basicAuth

艾克索拉API使用基本认证。所有发送到API的请求必须包含`Authorization: Basic <your_authorization_basic_key>`头，其中`<your_authorization_basic_key>`是按照Base64标准加密的`merchant_id:api_key`对。

请前往[发布商帐户](https://publisher.xsolla.com/)找到这些参数：<ul><li>`merchant_id`在以下部分中显示：<ul><li><b>公司设置 > 公司</b>部分。</li><li>发布商帐户任意页面浏览器地址栏的URL中。URL的格式如下：`https://publisher.xsolla.com/<merchant_id>`。</li></ul></li><li>`api_key`仅在创建时在发布商帐户中显示一次，必须在己侧妥善保存。您可以在以下部分创建新密钥：<ul><li><b>公司设置 > API密钥</b>。</li><li><b>项目设置 > API密钥</b>。</li></ul></li></ul><br>
关于使用API密钥的详细信息，请参阅[API参考](https://developers.xsolla.com/zh/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/zh/api/subscriptions/index.yaml)

## 令牌

### 创建令牌

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

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

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

## 计划

### 列示所有计划

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

### 创建计划

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

### 禁用计划

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

### 启用计划

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

### 更新计划

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

### 删除计划

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

## 产品

### 获取产品

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

### 创建产品

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

### 删除产品

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

### 更新产品

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

## Subscription management

### 列示所有订阅

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

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

### 获取订阅

 - [GET /projects/{project_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/zh/api/subscriptions/subscriptions/get-subscription.md): 通过ID获取特定订阅的详细信息。

### 更新订阅

 - [PUT /projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}](https://developers.xsolla.com/zh/api/subscriptions/subscriptions/update-subscription.md): 更新重复性订阅。可以更新订阅的状态（active、canceled或non_renewing）以及推迟当前订阅的下一次收费日期。

## 支付

### 列示所有货币

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

### 列示所有支付

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

### 获取用户付款

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

## 促销活动

### 获取促销活动列表

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

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

### 创建新促销活动

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

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

### 删除促销活动

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

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

### 获取促销活动

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

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

### 更新促销活动

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

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

### 获取支付系统

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

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

### 设置支付系统

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

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

### 获取期间

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

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

### 设置期间

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

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

### 检查促销活动

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

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

### 获取奖励

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

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

### 设置奖励

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

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

### 获取主题

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

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

### 设定主题

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

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

### 切换促销活动

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

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

## 优惠券

### 创建优惠券活动

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

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

### 添加优惠券至优惠券活动

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

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

### 将优惠券活动添加至促销活动

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

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

### 获取优惠券

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

### 兑换优惠券

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

## Subscription management

### List subscriptions

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions](https://developers.xsolla.com/zh/api/subscriptions/subscription-management/list-subscriptions.md)

### Get management settings

 - [GET /api/user/v1/management/projects/{project_id}/subscriptions/settings](https://developers.xsolla.com/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/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/zh/api/subscriptions/subscription-management/get-plan-for-change.md)