跳转到内容

概览

  • Version: 2.0
  • 服务器https://api.xsolla.com/merchant/v2/

本API参考介绍管理订阅、优惠券和促销活动的端点。 如需了解关于订阅的详细信息,请参考产品指南词汇表

下载 OpenAPI 描述
语言
服务器
Mock server
https://xsolla.redocly.app/_mock/zh/api/subscriptions/
操作
操作
操作
操作

请求

列出所有经常订阅。

注意

这种API方法不能在高负载下使用。 最大负载为每分钟20个请求。

注意

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

安全
basicAuth
路径
merchant_idinteger必需

商户ID。

查询
offsetinteger

元素编号,从该元素开始生成列表(从0开始数)。

limitinteger必需

页面上元素数量的限制。

user_idstring

用户ID。

project_id[]Array of integers

项目ID列表。

plan_id[]Array of integers

订阅计划ID列表。

product_id[]Array of integers

计划关联的产品ID列表。

group_id[]Array of strings

计划关联的组ID列表。

status[]Array of strings

状态。

枚举"active""canceled""non_renewing"
datetime_fromstring(datetime)

示例日期。查找在请求日期之后创建的订阅。

datetime_tostring(datetime)

示例日期。查找在请求日期之后创建的订阅。

curl -i -X GET \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/zh/api/subscriptions/merchants/{merchant_id}/subscriptions?offset=0&limit=0&user_id=string&project_id%5B%5D=0&plan_id%5B%5D=0&product_id%5B%5D=0&group_id%5B%5D=string&status%5B%5D=active&datetime_from=string&datetime_to=string'

响应

OK.

正文application/jsonArray [
charge_amountnumber(float)

支付金额。

commentstring

更改订阅状态的原因

currencystring

交易使用的币种。符合ISO 4217标准的三字母货币代码。

date_createstring(datetime)

按照ISO 8601规定的YYYY-MM-DD’T’HH:MM:SS格式的订阅创建日期。

date_endstring(datetime)

按照ISO 8601规定的YYYY-MM-DD’T’HH:MM:SS格式的订阅结束日期。

date_last_chargestring or null(datetime)

按照ISO 8601规定的YYYY-MM-DD’T’HH:MM:SS格式的上次订阅扣费日期。

date_next_chargestring or null(datetime)

按照ISO 8601规定的YYYY-MM-DD’T’HH:MM:SS格式的下次订阅扣费日期。

idinteger

订阅ID

planobject
plan.​billing_retryobject

账单扣费重试详情。

plan.​billing_retry.​valueinteger必需

账单扣费重试次数。

plan.​chargeobject

账单详情。

plan.​charge.​amountnumber(float)

支付金额。

plan.​charge.​currencystring

购买币种。参照ISO 4217标准的三字母货币代码。

plan.​charge.​periodobject必需

账单周期。

plan.​charge.​period.​typestring必需

时间单位。可以是daymonthlifetime

枚举"day""month""lifetime"
plan.​charge.​period.​valueinteger必需

时间单位数。该值取决于类型参数:
- 如果typeday,可以是1-366
- 如果typemonth,可以是1-12
- 如果typelifetime,则为0

plan.​charge.​pricesArray of objects

不同货币下的价格列表。

plan.​charge.​prices[].​amountnumber(float)必需

支付金额。

plan.​charge.​prices[].​currencystring必需

购买币种。参照ISO 4217标准的三字母货币代码。

plan.​charge.​prices[].​setup_feenumber(float)

包含在首次发票中收取的一次性初设费。

plan.​descriptionobject

计划描述。由"localization":"plan description"组成的键值对。

plan.​description.​arstring

阿拉伯语。

plan.​description.​bgstring

保加利亚语。

plan.​description.​cnstring

中文(简体)。

plan.​description.​csstring

捷克语。

plan.​description.​destring

德语。

plan.​description.​enstring

英语。

plan.​description.​esstring

西班牙语。

plan.​description.​frstring

法语。

plan.​description.​hestring

希伯来语。

plan.​description.​itstring

意大利语。

plan.​description.​jastring

日语。

plan.​description.​kostring

韩语。

plan.​description.​plstring

波兰语。

plan.​description.​ptstring

葡萄牙语。

plan.​description.​rostring

罗马尼亚语。

plan.​description.​rustring

俄语。

plan.​description.​thstring

泰语。

plan.​description.​trstring

土耳其语。

plan.​description.​twstring

中文(繁体)。

plan.​description.​vistring

越南语。

plan.​expirationobject

订阅到期详情。

plan.​expiration.​typestring必需

时间单位,可以是daymonth

枚举"day""month"
plan.​expiration.​valueinteger or null必需

过期之前的时间。

plan.​external_idstring

外部计划标识符。

plan.​grace_periodobject

带有宽限期相关数据的对象。

plan.​grace_period.​typestring必需

时间单位,可以是day

"day"
plan.​grace_period.​valueinteger必需

两次收费之间的间隔时间。

plan.​group_idstring or null

计划关联的组ID。

plan.​idinteger

订阅计划ID。

plan.​nameobject

计划名称。值包含 "localization":"plan name" 对。

plan.​name.​arstring

阿拉伯语。

plan.​name.​bgstring

保加利亚语。

plan.​name.​cnstring

中文(简体)。

plan.​name.​csstring

捷克语。

plan.​name.​destring

德语。

plan.​name.​enstring

英语。

plan.​name.​esstring

西班牙语。

plan.​name.​frstring

法语。

plan.​name.​hestring

希伯来语。

plan.​name.​itstring

意大利语。

plan.​name.​jastring

日语。

plan.​name.​kostring

韩语。

plan.​name.​plstring

波兰语。

plan.​name.​ptstring

葡萄牙语。

plan.​name.​rostring

罗马尼亚语。

plan.​name.​rustring

俄语。

plan.​name.​thstring

泰语。

plan.​name.​trstring

土耳其语。

plan.​name.​twstring

中文(繁体)。

plan.​name.​vistring

越南语。

plan.​project_idinteger

项目ID。

plan.​refund_periodinteger or null

订阅计划可退款的时间期限(单位为天)。

plan.​statusobject
plan.​status.​valuestring

订阅计划状态。

枚举"active""disabled"
plan.​tagsArray of strings

计划标签。

plan.​trialobject

试用期详情。

plan.​trial.​typestring必需

时间单位,可以是day

"day"
plan.​trial.​valueinteger必需

两次收费之间的间隔时间。

productobject or null
product.​idinteger or null

这些计划与之连接的产品的 ID。

product.​descriptionobject

本地化商品描述。

product.​description.​arstring

阿拉伯语。

product.​description.​bgstring

保加利亚语。

product.​description.​cnstring

中文(简体)。

product.​description.​csstring

捷克语。

product.​description.​destring

德语。

product.​description.​enstring

英语。

product.​description.​esstring

西班牙语。

product.​description.​frstring

法语。

product.​description.​hestring

希伯来语。

product.​description.​itstring

意大利语。

product.​description.​jastring

日语。

product.​description.​kostring

韩语。

product.​description.​plstring

波兰语。

product.​description.​ptstring

葡萄牙语。

product.​description.​rostring

罗马尼亚语。

product.​description.​rustring

俄语。

product.​description.​thstring

泰语。

product.​description.​trstring

土耳其语。

product.​description.​twstring

中文(繁体)。

product.​description.​vistring

越南语。

product.​group_idstring

产品关联的组ID。

product.​namestring

产品名称。

statusstring

状态

枚举"new""active""canceled""non_renewing""freeze"
userobject
user.​idstring

用户ID

user.​namestring

用户名

]
响应
application/json
[ { "charge_amount": 0.03, "currency": "USD", "date_create": "2013-09-05T15:27:47+04:00", "date_end": "2014-02-06T11:32:48+04:00", "date_last_charge": null, "date_next_charge": null, "id": 45, "plan": {}, "product": {}, "status": "canceled", "user": {} } ]

请求

通过ID获取特定订阅的详细信息。

安全
basicAuth
路径
project_idinteger必需

项目ID。

subscription_idinteger必需

订阅ID。

curl -i -X GET \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/zh/api/subscriptions/projects/{project_id}/subscriptions/{subscription_id}'

响应

OK.

正文application/json
charge_amountnumber(float)

支付金额。

commentstring

更改订阅状态的原因

currencystring

交易使用的币种。符合ISO 4217标准的三字母货币代码。

date_createstring(datetime)

按照ISO 8601规定的YYYY-MM-DD’T’HH:MM:SS格式的订阅创建日期。

date_endstring(datetime)

按照ISO 8601规定的YYYY-MM-DD’T’HH:MM:SS格式的订阅结束日期。

date_last_chargestring or null(datetime)

按照ISO 8601规定的YYYY-MM-DD’T’HH:MM:SS格式的上次订阅扣费日期。

date_next_chargestring or null(datetime)

按照ISO 8601规定的YYYY-MM-DD’T’HH:MM:SS格式的下次订阅扣费日期。

idinteger

订阅ID

planobject
plan.​billing_retryobject

账单扣费重试详情。

plan.​billing_retry.​valueinteger必需

账单扣费重试次数。

plan.​chargeobject

账单详情。

plan.​charge.​amountnumber(float)

支付金额。

plan.​charge.​currencystring

购买币种。参照ISO 4217标准的三字母货币代码。

plan.​charge.​periodobject必需

账单周期。

plan.​charge.​period.​typestring必需

时间单位。可以是daymonthlifetime

枚举"day""month""lifetime"
plan.​charge.​period.​valueinteger必需

时间单位数。该值取决于类型参数:
- 如果typeday,可以是1-366
- 如果typemonth,可以是1-12
- 如果typelifetime,则为0

plan.​charge.​pricesArray of objects

不同货币下的价格列表。

plan.​charge.​prices[].​amountnumber(float)必需

支付金额。

plan.​charge.​prices[].​currencystring必需

购买币种。参照ISO 4217标准的三字母货币代码。

plan.​charge.​prices[].​setup_feenumber(float)

包含在首次发票中收取的一次性初设费。

plan.​descriptionobject

计划描述。由"localization":"plan description"组成的键值对。

plan.​description.​arstring

阿拉伯语。

plan.​description.​bgstring

保加利亚语。

plan.​description.​cnstring

中文(简体)。

plan.​description.​csstring

捷克语。

plan.​description.​destring

德语。

plan.​description.​enstring

英语。

plan.​description.​esstring

西班牙语。

plan.​description.​frstring

法语。

plan.​description.​hestring

希伯来语。

plan.​description.​itstring

意大利语。

plan.​description.​jastring

日语。

plan.​description.​kostring

韩语。

plan.​description.​plstring

波兰语。

plan.​description.​ptstring

葡萄牙语。

plan.​description.​rostring

罗马尼亚语。

plan.​description.​rustring

俄语。

plan.​description.​thstring

泰语。

plan.​description.​trstring

土耳其语。

plan.​description.​twstring

中文(繁体)。

plan.​description.​vistring

越南语。

plan.​expirationobject

订阅到期详情。

plan.​expiration.​typestring必需

时间单位,可以是daymonth

枚举"day""month"
plan.​expiration.​valueinteger or null必需

过期之前的时间。

plan.​external_idstring

外部计划标识符。

plan.​grace_periodobject

带有宽限期相关数据的对象。

plan.​grace_period.​typestring必需

时间单位,可以是day

"day"
plan.​grace_period.​valueinteger必需

两次收费之间的间隔时间。

plan.​group_idstring or null

计划关联的组ID。

plan.​idinteger

订阅计划ID。

plan.​nameobject

计划名称。值包含 "localization":"plan name" 对。

plan.​name.​arstring

阿拉伯语。

plan.​name.​bgstring

保加利亚语。

plan.​name.​cnstring

中文(简体)。

plan.​name.​csstring

捷克语。

plan.​name.​destring

德语。

plan.​name.​enstring

英语。

plan.​name.​esstring

西班牙语。

plan.​name.​frstring

法语。

plan.​name.​hestring

希伯来语。

plan.​name.​itstring

意大利语。

plan.​name.​jastring

日语。

plan.​name.​kostring

韩语。

plan.​name.​plstring

波兰语。

plan.​name.​ptstring

葡萄牙语。

plan.​name.​rostring

罗马尼亚语。

plan.​name.​rustring

俄语。

plan.​name.​thstring

泰语。

plan.​name.​trstring

土耳其语。

plan.​name.​twstring

中文(繁体)。

plan.​name.​vistring

越南语。

plan.​project_idinteger

项目ID。

plan.​refund_periodinteger or null

订阅计划可退款的时间期限(单位为天)。

plan.​statusobject
plan.​status.​valuestring

订阅计划状态。

枚举"active""disabled"
plan.​tagsArray of strings

计划标签。

plan.​trialobject

试用期详情。

plan.​trial.​typestring必需

时间单位,可以是day

"day"
plan.​trial.​valueinteger必需

两次收费之间的间隔时间。

productobject or null
product.​idinteger or null

这些计划与之连接的产品的 ID。

product.​descriptionobject

本地化商品描述。

product.​description.​arstring

阿拉伯语。

product.​description.​bgstring

保加利亚语。

product.​description.​cnstring

中文(简体)。

product.​description.​csstring

捷克语。

product.​description.​destring

德语。

product.​description.​enstring

英语。

product.​description.​esstring

西班牙语。

product.​description.​frstring

法语。

product.​description.​hestring

希伯来语。

product.​description.​itstring

意大利语。

product.​description.​jastring

日语。

product.​description.​kostring

韩语。

product.​description.​plstring

波兰语。

product.​description.​ptstring

葡萄牙语。

product.​description.​rostring

罗马尼亚语。

product.​description.​rustring

俄语。

product.​description.​thstring

泰语。

product.​description.​trstring

土耳其语。

product.​description.​twstring

中文(繁体)。

product.​description.​vistring

越南语。

product.​group_idstring

产品关联的组ID。

product.​namestring

产品名称。

statusstring

状态

枚举"new""active""canceled""non_renewing""freeze"
userobject
user.​idstring

用户ID

user.​namestring

用户名

响应
application/json
{ "charge_amount": 0.03, "comment": "The subscription was not extended in due time", "currency": "USD", "date_create": "2018-09-21T16:54:59+03:00", "date_end": "2019-02-06T12:43:04+03:00", "date_last_charge": "2018-09-21T16:55:05+03:00", "date_next_charge": "2018-09-21T16:55:05+03:00", "id": 249579, "plan": { "external_id": "lowcost", "id": 601 }, "product": { "id": 123456 }, "status": "canceled", "user": { "id": "user1", "name": "John Smith" } }

请求

更新重复性订阅。可以更新订阅的状态(activecancelednon_renewing)以及推迟当前订阅的下一次收费日期。

安全
basicAuth
路径
project_idinteger必需

项目ID。

user_idstring必需

用户ID。

subscription_idinteger必需

订阅ID。

正文application/json必需
cancel_subscription_paymentboolean

如果设为true,此订阅的最后一次付款将被退回。只有状态更改为canceled,此选项才会有效

statusstring

状态。

枚举"active""canceled""non_renewing"
timeshiftobject

账单推迟。

timeshift.​typestring

账单时间单位,可以是daymonth

枚举"day""month"
timeshift.​valuestring

推迟账单的时间单位数。该值取决于类型参数:
- 如果typeday,可以是1-366
- 如果typemonth,可以是1-12

xsolla_networkobject
xsolla_network.​collaborator_idstring

协作推广者ID — 圈内达人联盟网络标识符。可在发布商帐户 > 流量联盟 > 圈内达人部分找到。

curl -i -X PUT \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/zh/api/subscriptions/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "active"
  }'

响应

OK.

正文application/json
响应
application/json
{ "charge_amount": 0.03, "currency": "USD", "date_create": "2018-09-21T16:54:59+03:00", "date_end": null, "date_last_charge": "2018-09-21T16:55:05+03:00", "date_next_charge": "2018-09-21T16:55:05+03:00", "id": 24953579, "plan": { "billing_retry": {}, "charge": {}, "description": null, "expiration": {}, "external_id": "lowcost", "grace_period": {}, "group_id": "newPlans", "id": 66001, "localized_name": null, "name": null, "project_id": 18404, "refund_period": null, "status": {}, "tags": null, "trial": {}, "type": "all" }, "product": null, "status": "active", "user": { "id": "jb1", "name": "J.Black" } }
操作
操作
操作
操作