`为用户令牌。该令牌用于识别用户，并授予其访问个性化数据的权限。或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。
2. **不带Authorization请求头的简化模式。** 此模式仅适用于未完成身份认证的用户，且仅可用于[游戏Key销售](/zh/doc/buy-button/how-to/set-up-authentication/#guides_buy_button_selling_items_not_authenticated_users)请求中不使用令牌，而必须包含以下请求头：
- `x-unauthorized-id`，值为请求ID
- `x-user`，值为使用Base64编码的用户电子邮件地址
## 实用链接 {% #authentication-useful-links %}
- [按交互模型划分的API调用](/zh/api/getting-started/#api_interaction_model)
- [接口类型](/zh/api/getting-started/#api_endpoint_types)
- [错误处理](/zh/api/getting-started/#api_errors_handling)
- [API密钥](/zh/api/getting-started/#api_keys_overview)
# 核心实体结构 {% #core-entity-structure %}
所有类型的商品（虚拟物品、捆绑包、虚拟货币和密钥）都使用类似的数据结构。了解基本结构有助于简化API使用，并帮助您更轻松地查阅文档。
注：
部分调用可能包含其他字段，但这些字段不会改变基本结构。
**标识信息**
- `merchant_id` — [发布商帐户](https://publisher.xsolla.com/)中的公司ID
- `project_id` — 发布商帐户中的项目ID
- `sku` — 商品SKU，在项目内唯一
**商店显示**
- `name` — 商品名称
- `description` — 商品描述
- `image_url` — 图片URL
- `is_enabled` — 商品可用性
- `is_show_in_store` — 商品是否显示在商品目录中
有关在商品目录中管理商品可用性的更多信息，请参阅[文档](/zh/items-catalog/catalog-features/items-availability/)。
**组织方式**
- `type` — 商品类型，例如虚拟物品（`virtual_item`）或捆绑包（`bundle`）
- `groups` — 商品所属的组
- `order` — 在商品目录中的显示顺序
**销售条件**
- `prices` — 以真实货币或虚拟货币表示的价格
- `limits` — 购买限制
- `periods` — 可用时间段
- `regions` — 区域限制
**核心实体结构示例：**
```json
{
"attributes": [],
"bundle_type": "virtual_currency_package",
"content": [
{
"description": {
"en": "Main in-game currency"
},
"image_url": "https://.../image.png",
"name": {
"en": "Crystals",
"de": "Kristalle"
},
"quantity": 500,
"sku": "com.xsolla.crystal_2",
"type": "virtual_currency"
}
],
"description": {
"en": "Crystals x500"
},
"groups": [],
"image_url": "https://.../image.png",
"is_enabled": true,
"is_free": false,
"is_show_in_store": true,
"limits": {
"per_item": null,
"per_user": null,
"recurrent_schedule": null
},
"long_description": null,
"media_list": [],
"name": {
"en": "Medium crystal pack"
},
"order": 1,
"periods": [
{
"date_from": null,
"date_until": "2020-08-11T20:00:00+03:00"
}
],
"prices": [
{
"amount": 20,
"country_iso": "US",
"currency": "USD",
"is_default": true,
"is_enabled": true
}
],
"regions": [],
"sku": "com.xsolla.crystal_pack_2",
"type": "bundle",
"vc_prices": []
}
```
# 基本购买流程 {% #basic-purchase-flow %}
艾克索拉API可用于实现游戏内购商店逻辑，包括获取商品目录、管理购物车、创建订单以及跟踪订单状态。根据集成场景，API调用分为**管理**和**商品目录**子部分，使用不同的[身份认证方案](/zh/api/catalog/authentication)。
以下示例展示了从创建商品到完成购买的商店设置和运营基本流程。
## 创建商品和组（管理） {% #create-items-and-groups-admin %}
为您的商店创建商品目录，例如虚拟物品、捆绑包或虚拟货币。
API调用示例：
- [创建虚拟物品](/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-item)
- [创建捆绑包](/zh/api/catalog/bundles-admin/admin-create-bundle)
- [创建虚拟货币](/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency)
## 设置促销、奖励链和限制（管理） {% #set-up-promotions-chains-and-limits-admin %}
配置用户拉新和赢利工具，例如折扣、赠品、每日奖励或优惠链。
API调用示例：
- [创建买赠促销活动](/zh/api/liveops/promotions-bonuses/create-bonus-promotion)
- [创建每日奖励](/zh/api/liveops/daily-chain-admin/admin-create-daily-chain)
- [创建唯一商品目录优惠促销活动](/zh/api/liveops/promotions-unique-catalog-offers/admin-create-unique-catalog-offer)
## 获取商品信息（客户端） {% #get-item-information-client %}
在您的应用程序中配置商品显示。
提示
请勿使用管理子部分中的API调用来构建用户商品目录。这些API调用存在
速率限制，并不适用于用户流量。
API调用示例：
- [获取虚拟物品列表](/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items)
- [获取商品组列表](/zh/api/catalog/virtual-items-currency-catalog/get-item-groups)
- [获取捆绑包列表](/zh/api/catalog/bundles-catalog/get-bundle-list)
- [获取可售商品列表](/zh/api/catalog/common-catalog/get-sellable-items)
注：
默认情况下，商品目录API调用会返回请求时商店中当前可用的商品。如需获取尚未可用或已不再可用的商品，请在商品目录请求中包含参数"show_inactive_time_limited_items": 1。
## 销售商品 {% #sell-items %}
您可以使用以下方法销售商品：
- 快速购买 — 多次销售同一SKU。
- 购物车购买 — 用户可在同一订单中向购物车添加商品、移除商品并更新数量。
如果商品使用虚拟货币而非真实货币购买，请使用[创建包含指定商品的订单](/zh/api/catalog/virtual-payment/create-order-with-item-for-virtual-currency) API调用。由于扣款会在执行API调用时处理，因此无需支付UI。
如需购买免费商品，请使用[使用指定商品创建订单](/zh/api/catalog/free-item/create-free-order-with-item) API调用或[使用免费购物车创建订单](/zh/api/catalog/free-item/create-free-order) API调用。无需支付UI — 订单会立即设置为done状态。
### 快速购买 {% #fast-purchase %}
使用客户端API调用[使用指定商品创建订单](/zh/api/catalog/payment-client-side/create-order-with-item)。该调用会返回用于打开支付UI的令牌。
注：
用户只能在支付UI中查看折扣信息。不支持兑换码。
### 购物车购买 {% #cart-purchase %}
可以在客户端或服务器侧设置购物车并完成购买。
**在客户端设置和购买购物车商品**
您需要自行实现添加和移除商品的逻辑。在调用用于设置购物车的API之前，您无法获知哪些促销活动会应用于本次购买。这意味着您无法提前获知总费用以及添加的赠品的详细信息。
实现以下购物车逻辑：
1. 玩家在购物车加购后，使用[向购物车添加商品](/zh/api/shop-builder/operation/cart-fill/) API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。
2. 根据用户操作更新购物车内容：
- 如需添加商品或更改商品数量，请使用[按购物车ID更新购物车商品](/zh/api/shop-builder/operation/put-item-by-cart-id/) API调用。
- 如需移除商品，请使用[按购物车ID删除购物车商品](/zh/api/shop-builder/operation/delete-item-by-cart-id/) API调用。
注：
如需获取购物车的当前状态，请使用“获取当前用户的购物车”API调用。
3. 使用[创建包含当前购物车中所有商品的订单](/zh/api/shop-builder/operation/create-order/) API调用。该调用返回订单ID和支付令牌。新创建的订单默认设置为new状态。
**在服务器侧设置和购买购物车商品**
这种设置方式可能需要更长的购物车设置时间，因为每次更改购物车都必须伴随API调用。
实现以下购物车逻辑：
1. 玩家在购物车加购后，使用[向购物车添加商品](/zh/api/catalog/cart-server-side) API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。
2. 使用[创建包含当前购物车中所有商品的订单](/zh/api/shop-builder/operation/create-order/) API调用。该调用会返回订单ID和支付令牌。新创建的订单默认设置为new状态。
## 打开支付UI {% #open-payment-ui %}
使用返回的令牌在新窗口中打开支付UI。有关打开支付UI的其他方式，请参阅[文档](/zh/payment-ui-and-flow/payment-ui/how-to-open-payment-ui/#open_payment_ui)。
| 操作 | 接口 |
|:--------------------------------|:--------------------------------------------------------------------------|
| 在生产环境中打开。 | https://secure.xsolla.com/paystation4/?token={token} |
| 在沙盒模式中打开。 | https://sandbox-secure.xsolla.com/paystation4/?token={token} |
注：
请在开发和测试期间使用沙盒模式。测试购买不会对真实帐户扣款。您可以使用
测试银行卡。
完成第一笔真实支付后，严格的沙盒支付策略将生效。沙盒模式下的支付仅对[发布商帐户 > 公司设置 > 用户](https://publisher.xsolla.com/0/settings/users)中指定的用户可用。
只有在与艾克索拉签署许可协议后，才能使用真实货币购买虚拟货币和商品。如需签署协议，请在[发布商帐户](https://publisher.xsolla.com/)中前往**协议与税务 > 合同与协议**，填写协议表单并等待确认。协议审核最多可能需要3个工作日。
如需启用或禁用沙盒模式，请在快速购买和购物车购买请求中更改`sandbox`参数的值。沙盒模式默认关闭。
可能的订单状态：
- `new` — 订单已创建
- `paid` — 已收到付款
- `done` — 商品已交付
- `canceled` — 订单已取消
- `expired` — 订单已过期
使用以下任一方式跟踪订单状态：
- [您服务器上配置的Webhook](/zh/virtual-goods/own-ui/server-side-token-generation/set-up-order-tracking/#payments_integration_order_tracking)
- [短轮询](/zh/virtual-goods/own-ui/client-side-token-generation/set-up-order-tracking/#guides_shop_builder_integrate_store_get_order_status_via_short_polling)
- [WebSocket API](/zh/virtual-goods/own-ui/client-side-token-generation/set-up-order-tracking/#guides_shop_builder_integrate_store_get_order_status_via_websocket_api)
## 实用链接 {% #basic-purchase-flow-useful-links %}
- 身份认证
- [按交互模型划分的API调用](/zh/api/catalog/authentication)
- [支付测试](/zh/dev-resources/testing/general-info/#general_overview)
- [设置订单状态跟踪](/zh/virtual-goods/own-ui/client-side-token-generation/set-up-order-tracking/?link=200-api#payments_integration_order_tracking)
- [Webhook](/zh/webhooks/overview)
- [速率限制](/zh/api/login/rate-limits)
- [错误处理](/zh/api/getting-started/#api_errors_handling)
- [API密钥](/zh/api/getting-started/#api_keys_overview)
# 分页 {% #pagination %}
返回大量记录的API调用（例如构建商品目录时）会按页返回数据。分页是一种限制单个API响应中返回商品数量的机制，并允许您按顺序获取后续页面。
使用以下参数控制返回的商品数量：
- `limit` — 每页商品数量
- `offset` — 页面中第一个商品的索引（从0开始编号）
- `has_more` — 指示是否还有下一页
- `total_items_count` — 商品总数
请求示例：
```
GET /items?limit=20&offset=40
```
响应示例：
```json
{
"items": [...],
"has_more": true,
"total_items_count": 135
}
```
建议发送后续请求，直到响应返回`has_more = false`。
# 日期和时间格式 {% #date-and-time-format %}
日期和时间值以[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)格式传递。
支持以下内容：
- UTC偏移量
- 当商品显示没有时间限制时使用`null`值
- 部分字段使用的[Unix时间戳](https://www.unixtimestamp.com/)（以秒为单位）
格式：`YYYY-MM-DDTHH:MM:SS±HH:MM`
示例：`2026-03-16T10:00:00+03:00`
# 本地化 {% #localization %}
艾克索拉支持对商品名称、描述等面向用户的字段进行本地化。本地化值以对象形式传递，其中语言代码作为键。支持的完整语言列表，请参阅[文档](/zh/doc/shop-builder/references/supported-languages/)。
**支持的字段**
可为以下参数指定本地化内容：
- `name`
- `description`
- `long_description`
**区域格式**
语言区域键可使用以下任一格式指定：
- 两字母语言代码：`en`、`ru`
- 五字母语言代码：`en-US`、`ru-RU`、`de-DE`
**示例**
两字母语言代码示例：
```json
{
"name": {
"en": "Starter Pack",
"ru": "Стартовый набор"
}
}
```
五字母语言代码示例：
```json
{
"description": {
"en-US": "Premium bundle",
"de-DE": "Premium-Paket"
}
}
```
# 错误响应格式 {% #error-response-format %}
如果发生错误，API会返回HTTP状态和JSON响应正文。商店相关错误的完整列表，请参阅[文档](/zh/dev-resources/references/errors/store-errors/)。
**响应示例：**
```json
{
"errorCode": 1102,
"errorMessage": "Validation error",
"statusCode": 422,
"transactionId": "c9e1a..."
}
```
- `errorCode` — 错误代码。
- `errorMessage` — 简短的错误描述。
- `statusCode` — HTTP响应状态。
- `transactionId` — 请求ID。仅在部分情况下返回。
- `errorMessageExtended` — 其他错误详情，例如请求参数。仅在某些情况下返回。
**扩展响应示例：**
```json
{
"errorCode": 7001,
"errorMessage": "Chain not found",
"errorMessageExtended": {
"chain_id": "test_chain_id",
"project_id": "test_project_id",
"step_number": 2
},
"statusCode": 404
}
```
**常见HTTP状态代码**
- `400` — 请求无效
- `401` — 身份认证错误
- `403` — 权限不足
- `404` — 资源未找到
- `422` — 验证错误
- `429` — 超出速率限制
**建议**
- 结合HTTP状态和响应正文一起处理。
- 使用`errorCode`处理与应用程序逻辑相关的错误。
- 分析错误时，使用`transactionId`更快定位请求。
Version: 2.0.0
## Servers
```
https://store.xsolla.com/api
```
## Security
### basicAuth
服务器侧调用使用`basicAuth`身份认证方案。向API发送的所有请求都必须包含`Authorization: Basic `请求头，其中`your_authorization_basic_key`是根据Base64标准编码的`project_id:api_key`对。
如有需要，您可以使用`merchant_id`代替`project_id`。这不会影响功能。
前往[发布商帐户](https://publisher.xsolla.com/)查找参数值：
* `merchant_id`显示在：
* **公司设置 > 公司**部分
* 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com/`。
* `api_key`仅会在创建时于发布商帐户中显示一次，必须由您在己侧保存。您可以在以下部分创建新密钥：
* [公司设置 > API密钥](https://publisher.xsolla.com/0/settings/api_key)
* [项目设置 > API密钥](https://publisher.xsolla.com/0/projects/0/edit/api_key)
{% html name="div" attrs={"class": "notice"} %}
**提示**
如果所需的API调用不包含`project_id`路径参数，请使用对公司所有项目均有效的API密钥进行授权。
{% /html %}
* `project_id`显示在：
* 发布商帐户中项目名称旁边。
* 发布商帐户中项目页浏览器地址栏中的URL中。URL格式为：`https://publisher.xsolla.com//projects/`。
有关使用API密钥的更多信息，请参阅[API参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。
Type: http
Scheme: basic
### XsollaLoginUserJWT
客户端侧调用使用`XsollaLoginUserJWT`身份认证方案。请求须在`Authorization`请求头中包含用户JWT，格式为：Bearer ``。令牌用于识别用户并提供个性化数据访问权限。有关令牌创建方法，请参阅[艾克索拉登录管理器API文档](/zh/api/login/authentication-schemes#getting-user-token)。
或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。
Type: http
Scheme: bearer
Bearer Format: JWT
### AuthForCart
`AuthForCart`身份认证方案用于购物车购买，支持两种模式：
1. 使用用户JWT进行身份认证。 令牌通过Authorization请求头按以下格式传递：`Authorization: Bearer `，其中``是用户令牌。该令牌用于识别用户，并提供对个性化数据的访问权限。
或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。
2. 不带`Authorization`请求头的简化模式。此模式仅适用于未完成身份认证的用户，且仅可用于[游戏Key销售](/zh/doc/buy-button/how-to/set-up-authentication/#guides_buy_button_selling_items_not_authenticated_users)请求中不使用令牌，而必须包含以下请求头：
* `x-unauthorized-id`，值为请求ID
* `x-user`，值为使用Base64编码的用户电子邮件地址。
Type: http
Scheme: bearer
### basicMerchantAuth
服务器侧调用使用`basicMerchantAuth`身份认证方案。向API发送的所有请求都必须包含`Authorization: Basic `请求头，其中`your_authorization_basic_key`是根据Base64标准编码的`merchant_id:api_key`对。
前往[发布商帐户](https://publisher.xsolla.com/)查找参数值：
* `merchant_id`显示在：
* **公司设置 > 公司**部分
* 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com/`。
* `api_key`仅会在创建时于发布商帐户中显示一次，必须由您在己侧保存。您可以在[公司设置 > API密钥](https://publisher.xsolla.com/0/settings/api_key)部分创建新密钥。
有关使用API密钥的更多信息，请参阅[API参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。
Type: http
Scheme: basic
## Download OpenAPI description
[LiveOps运营API](https://xsolla.redocly.app/_bundle/@l10n/zh/api/liveops/index.yaml)
## 通用API调用
您可以调用此子部分中的API方法，管理不同类型的促销活动。
### 获取所有促销活动列表
- [GET /v3/project/{project_id}/admin/promotion](https://xsolla.redocly.app/zh/api/liveops/promotions-common/get-promotion-list.md): 获取项目的促销活动列表。
### 激活促销活动
- [PUT /v2/project/{project_id}/admin/promotion/{promotion_id}/activate](https://xsolla.redocly.app/zh/api/liveops/promotions-common/activate-promotion.md): 激活促销活动。
### 停用促销活动
- [PUT /v2/project/{project_id}/admin/promotion/{promotion_id}/deactivate](https://xsolla.redocly.app/zh/api/liveops/promotions-common/deactivate-promotion.md): 停用促销活动。
### 通过代码获取兑换型促销活动
- [GET /v3/project/{project_id}/admin/promotion/redeemable/code/{code}](https://xsolla.redocly.app/zh/api/liveops/promotions-common/get-redeemable-promotion-by-code.md): 通过兑换码或优惠券码获取促销活动。
### 验证促销代码
- [GET /v2/project/{project_id}/promotion/code/{code}/verify](https://xsolla.redocly.app/zh/api/liveops/promotions-common/verify-promotion-code.md): 确定代码是兑换码还是优惠券码，以及用户是否可以使用该代码。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
## 优惠券
调用此子部分中的API方法，配置和管理优惠券促销活动。
### 兑换优惠券码
- [POST /v2/project/{project_id}/coupon/redeem](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/redeem-coupon.md): 兑换优惠券码。优惠券兑换后，用户将获得赠品。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 获取优惠券奖励
- [GET /v2/project/{project_id}/coupon/code/{coupon_code}/rewards](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/get-coupon-rewards-by-code.md): 通过优惠券码获取优惠券奖励。可用于允许用户从多个商品中选择一个作为赠品。常见场景是：如果优惠券包含游戏作为赠品(type=unit)，则选择DRM。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 创建优惠券促销活动
- [POST /v3/project/{project_id}/admin/coupon](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/admin-create-coupon.md): 创建优惠券促销活动。
### 获取优惠券促销活动列表
- [GET /v3/project/{project_id}/admin/coupon](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/get-coupons.md): 获取项目的优惠券促销活动列表。
### 更新优惠券促销活动
- [PUT /v3/project/{project_id}/admin/coupon/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/update-coupon-promotion.md): 更新优惠券促销活动。
### 获取优惠券促销活动
- [GET /v3/project/{project_id}/admin/coupon/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/get-coupon.md): 获取指定的优惠券促销活动。
### 删除优惠券促销活动
- [DELETE /v3/project/{project_id}/admin/coupon/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/delete-coupon-promotion.md): 删除优惠券促销活动。删除的促销活动将：
* 从您项目中设置的促销活动列表中消失。
* 不再适用于商品目录。用户无法通过该促销活动获得奖励商品。
删除后，该促销活动无法恢复。
已删除促销活动的优惠券码可以添加到现有的促销活动。
### 激活优惠券促销活动
- [PUT /v2/project/{project_id}/admin/coupon/{external_id}/activate](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/activate-coupon.md): 激活优惠券促销活动。
默认情况下创建的优惠券促销活动为禁用状态。
激活之前，不能进行兑换。
使用此端点启用和激活优惠券促销活动。
### 停用优惠券促销活动
- [PUT /v2/project/{project_id}/admin/coupon/{external_id}/deactivate](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/deactivate-coupon.md): 停用优惠券促销活动。
默认情况下创建的优惠券促销活动为禁用状态。
激活之前，不能进行兑换。
使用此端点禁用和停用优惠券促销活动。
### 创建优惠券码
- [POST /v2/project/{project_id}/admin/coupon/{external_id}/code](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/create-coupon-code.md): 创建优惠券码。
### 获取优惠券码
- [GET /v2/project/{project_id}/admin/coupon/{external_id}/code](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/get-coupon-codes.md): 获取优惠券码。
响应包含该促销活动中的兑换码总数（total_count）以及当前页面的兑换码（codes）。如需获取下一页，请按limit的值递增offset（例如先传“offset”: 100，再传“offset”: 200），直到获取全部兑换码。
在大多数情况下，“limit”: 100或“limit”: 1000即可满足需求。较大的值（如“limit”: 10000）建议仅用于一次性批量导出；除非必要，请避免使用“limit”: 50000。
### 生成优惠券码
- [PUT /v2/project/{project_id}/admin/coupon/{external_id}/code/generate](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/generate-coupon-codes.md): 生成优惠券码。
兑换码生成指南：
* 每个促销活动的兑换码总数没有上限，但单次请求最多只能生成50,000个兑换码。如果请求的数量超过该限制，将返回422 Unprocessable Entity错误。如需生成超过50,000个兑换码，请发送多次请求。
* 为提高可靠性，建议分批生成兑换码，每次请求最多生成10,000个。例如，如需创建100,000个代码，请发送10次"count": 10000的请求，而不是发送2次"count": 50000的请求。请等待每次请求成功响应后，再发送下一次请求。
* 请注意，速率限制为每秒15个请求。批量生成大量券码时，请按顺序发送请求，避免超过速率限制并触发429错误。
* 如需获取代码列表，请调用获取优惠券码方法。
| 参数 | 值 |
|---|---|
| 每次请求的最小券码数量。| 1 |
| 每次请求的最大券码数量。仅在需要尽可能大的单次批量生成时使用。| 50,000 |
| 每次请求的建议券码数量。| 最多10,000个。如需创建更多券码，请按顺序发送多次请求。|
### 获取指定用户的优惠券限制
- [GET /v2/project/{project_id}/admin/user/limit/coupon/external_id/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/get-coupon-user-limit.md): 获取指定用户可以使用优惠券的剩余次数。
用户限制API允许您限制用户可以使用优惠券的次数。要配置用户限制数本身，请前往“管理”部分：
* 优惠券
### 获取唯一优惠券码限制
- [GET /v2/project/{project_id}/admin/code/limit/coupon/external_id/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-coupons/get-coupon-code-limit.md): 获取代码可以使用的剩余次数。要筛选代码，请使用codes查询参数。
要配置代码限制本身，请前往“管理”部分：
*优惠券
## 兑换码
调用此子部分中的API方法，配置和管理兑换码促销活动。
### Apply promo code
- [POST /v2/project/{project_id}/promocode/redeem](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/redeem-promo-code.md): Applies a code to a cart. When a promo code is applied, the cart total is recalculated to reflect a discount on the entire cart or on selected items. Bonus items may also be added to the cart. The discount is applied at checkout, while bonus items are granted after successful payment. Before payment, the user can remove the promo code, which cancels the discount and removes the bonus items from the cart.
### 从购物车中移除兑换码
- [PUT /v2/project/{project_id}/promocode/remove](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/remove-cart-promo-code.md): 从购物车中移除兑换码。
移除兑换码后，系统会重新计算购物车中所有商品的总价，且不再包含该兑换码提供的赠品和折扣。
### 获取兑换码奖励
- [GET /v2/project/{project_id}/promocode/code/{promocode_code}/rewards](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/get-promo-code-rewards-by-code.md): 通过兑换码获取兑换码奖励。可用于允许用户从多个商品中选择一个作为赠品。常见场景是：如果兑换码包含游戏作为赠品(type=unit)，则选择DRM。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 创建兑换码促销活动
- [POST /v3/project/{project_id}/admin/promocode](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/create-promo-code.md): 创建兑换码促销活动。
### 获取兑换码促销活动列表
- [GET /v3/project/{project_id}/admin/promocode](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/get-promo-codes.md): 获取项目的兑换码列表。
### 更新兑换码促销活动
- [PUT /v3/project/{project_id}/admin/promocode/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/update-promo-code.md): 更新兑换码促销活动。
### 获取兑换码促销活动
- [GET /v3/project/{project_id}/admin/promocode/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/get-promo-code.md): 获取指定的兑换码促销活动。
### 删除兑换码促销活动
- [DELETE /v3/project/{project_id}/admin/promocode/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/delete-promo-code.md): 删除兑换码促销活动。删除的促销活动将：
* 从您项目中设置的促销活动列表中消失。
* 不再应用于商品目录和购物车。用户无法通过该促销活动获得赠品或购买商品。
删除后，该促销活动无法恢复。
已删除促销活动的兑换码可以添加到现有促销活动。
### 激活兑换码促销活动
- [PUT /v2/project/{project_id}/admin/promocode/{external_id}/activate](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/activate-promo-code.md): 激活兑换码促销活动。
默认情况下创建的兑换码促销活动为禁用状态。
激活前，兑换码无法被核销。
使用此接口启用并激活兑换码促销活动。
### 停用兑换码促销活动
- [PUT /v2/project/{project_id}/admin/promocode/{external_id}/deactivate](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/deactivate-promo-code.md): 停用兑换码促销活动。
默认情况下创建的兑换码促销活动为禁用状态。
激活前，兑换码无法被核销。
使用此接口禁用并停用兑换码促销活动。
### 为兑换码促销活动创建兑换码
- [POST /v2/project/{project_id}/admin/promocode/{external_id}/code](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/create-promo-code-code.md): 为兑换码促销活动创建兑换码。
### 获取兑换码促销活动的兑换码
- [GET /v2/project/{project_id}/admin/promocode/{external_id}/code](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/get-promocode-codes.md): 获取兑换码促销活动的兑换码。
响应包含该促销活动中的兑换码总数（total_count）以及当前页面的兑换码（codes）。如需获取下一页，请按limit的值递增offset（例如先传“offset”: 100，再传“offset”: 200），直到获取全部兑换码。
在大多数情况下，“limit”: 100或“limit”: 1000即可满足需求。较大的值（如“limit”: 10000）建议仅用于一次性批量导出；除非必要，请避免使用“limit”: 50000。
### 为兑换码促销活动生成兑换码
- [PUT /v2/project/{project_id}/admin/promocode/{external_id}/code/generate](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/generate-promo-code-codes.md): 为兑换码促销活动生成兑换码。
兑换码生成指南：
* 每个促销活动的兑换码总数没有上限，但单次请求最多只能生成50,000个兑换码。如果请求的数量超过该限制，将返回422 Unprocessable Entity错误。如需生成超过50,000个兑换码，请发送多次请求。
* 为提高可靠性，建议分批生成兑换码，每次请求最多生成10,000个。例如，如需创建100,000个代码，请发送10次"count": 10000的请求，而不是发送2次"count": 50000的请求。请等待每次请求成功响应后，再发送下一次请求。
* 请注意，速率限制为每秒15个请求。批量生成大量券码时，请按顺序发送请求，避免超过速率限制并触发429错误。
* 如需获取兑换码列表，请调用获取兑换码促销活动的兑换码方法。
| 参数 | 值 |
|---|---|
| 每次请求的最小券码数量。| 1 |
| 每次请求的最大券码数量。仅在需要尽可能大的单次批量生成时使用。| 50,000 |
| 每次请求的建议券码数量。| 最多10,000个。如需创建更多券码，请按顺序发送多次请求。|
### 获取指定用户的兑换码使用限制
- [GET /v2/project/{project_id}/admin/user/limit/promocode/external_id/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/get-promo-code-user-limit.md): 获取指定用户可使用该兑换码的剩余次数。
用户限制API可用于限制用户使用兑换码的次数。如需配置用户限制本身，请前往“管理”部分：
* 兑换码
### 获取代码的兑换码使用限制
- [GET /v2/project/{project_id}/admin/code/limit/promocode/external_id/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-promo-codes/get-promo-code-code-limit.md): 获取代码可以使用的剩余次数。要筛选代码，请使用codes查询参数。
要配置代码限制本身，请前往“管理”部分：
*兑换码
## 专属商品目录优惠
调用此子部分中的API方法，配置和管理专属商品目录优惠。
### 创建专属商品目录优惠促销活动
- [POST /v3/project/{project_id}/admin/unique_catalog_offer](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/admin-create-unique-catalog-offer.md): 创建专属商品目录优惠促销活动。
### 获取专属商品目录优惠促销活动列表
- [GET /v3/project/{project_id}/admin/unique_catalog_offer](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/get-unique-catalog-offers.md): 获取项目的专属商品目录优惠促销活动列表。
### 更新专属商品目录优惠促销活动
- [PUT /v3/project/{project_id}/admin/unique_catalog_offer/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/update-unique-catalog-offer-promotion.md): 更新专属商品目录优惠促销活动。
### 获取专属商品目录优惠促销活动
- [GET /v3/project/{project_id}/admin/unique_catalog_offer/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/get-unique-catalog-offer.md): 获取指定的专属商品目录优惠促销活动。
### 删除专属商品目录优惠促销活动
- [DELETE /v3/project/{project_id}/admin/unique_catalog_offer/{external_id}](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/delete-unique-catalog-offer-promotion.md): 删除专属商品目录优惠促销活动。删除的促销活动将：
* 从您项目中设置的促销活动列表中消失。
* 不再应用于商品目录和购物车。用户无法通过该促销活动购买商品。
删除后，该促销活动无法恢复。
### 激活专属商品目录优惠促销活动
- [PUT /v2/project/{project_id}/admin/unique_catalog_offer/{external_id}/activate](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/activate-unique-catalog-offer.md): 开启专属商品目录优惠促销活动。默认情况下，新创建的促销活动处于禁用状态。
促销活动开启前，其兑换码无法使用。
### 停用专属商品目录优惠促销活动
- [PUT /v2/project/{project_id}/admin/unique_catalog_offer/{external_id}/deactivate](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/deactivate-unique-catalog-offer.md): 停用专属商品目录优惠促销活动。促销活动停用后，其兑换码将无法使用。
与该促销活动关联的隐藏商品不会显示在商品目录中。
### 创建专属商品目录优惠代码
- [POST /v2/project/{project_id}/admin/unique_catalog_offer/{external_id}/code](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/create-unique-catalog-offer-code.md): 创建专属商品目录优惠代码。
### 获取专属商品目录优惠代码
- [GET /v2/project/{project_id}/admin/unique_catalog_offer/{external_id}/code](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/get-unique-catalog-offer-codes.md): 获取专属商品目录优惠代码。
### 生成专属商品目录优惠代码
- [PUT /v2/project/{project_id}/admin/unique_catalog_offer/{external_id}/code/generate](https://xsolla.redocly.app/zh/api/liveops/promotions-unique-catalog-offers/generate-unique-catalog-offer-codes.md): 生成专属商品目录优惠代码。
## 折扣
调用此子部分中的API方法，配置和管理折扣促销活动。
### 为商品创建折扣促销活动
- [POST /v3/project/{project_id}/admin/promotion/item](https://xsolla.redocly.app/zh/api/liveops/promotions-discounts/create-item-promotion.md): 为商品创建折扣促销活动。
促销活动提供商品折扣(%)。
折扣应用于指定商品的所有价格。
### 获取商品促销活动列表
- [GET /v3/project/{project_id}/admin/promotion/item](https://xsolla.redocly.app/zh/api/liveops/promotions-discounts/get-item-promotion-list.md): 获取项目的商品促销列表。
促销活动提供商品折扣(%)。
折扣应用于指定商品的所有价格。
### 更新商品促销活动
- [PUT /v3/project/{project_id}/admin/promotion/{promotion_id}/item](https://xsolla.redocly.app/zh/api/liveops/promotions-discounts/update-item-promotion.md): 更新促销活动。
注：新数据将替换旧数据。如果只想更新促销活动的一部分，也需要在请求中传入所有必需数据。
促销活动提供商品折扣(%)。
折扣应用于指定商品的所有价格。
### 获取商品促销活动
- [GET /v3/project/{project_id}/admin/promotion/{promotion_id}/item](https://xsolla.redocly.app/zh/api/liveops/promotions-discounts/get-item-promotion.md): 获取应用于特定商品的促销活动。
促销活动提供商品折扣(%)。
折扣应用于指定商品的所有价格。
### 删除商品促销活动
- [DELETE /v3/project/{project_id}/admin/promotion/{promotion_id}/item](https://xsolla.redocly.app/zh/api/liveops/promotions-discounts/delete-item-promotion.md): 删除折扣促销活动。删除的促销活动将：
* 从您项目中设置的促销活动列表中消失。
* 不再适用于商品目录和购物车。用户无法通过该促销活动购买商品。
删除后，该促销活动无法恢复。
## 买赠
调用此子部分中的API方法，配置和管理买赠促销活动。
### 创建买赠促销活动
- [POST /v3/project/{project_id}/admin/promotion/bonus](https://xsolla.redocly.app/zh/api/liveops/promotions-bonuses/create-bonus-promotion.md): 创建买赠促销活动。
促销活动会在用户购买时赠送免费赠品。
该促销活动可应用于项目中的任意购买，也可应用于包含特定商品的购买。
### 获取买赠促销活动列表
- [GET /v3/project/{project_id}/admin/promotion/bonus](https://xsolla.redocly.app/zh/api/liveops/promotions-bonuses/get-bonus-promotion-list.md): 获取项目的买赠促销活动列表。
促销活动会在用户购买时赠送免费赠品。
该促销活动可应用于项目中的任意购买，也可应用于包含特定商品的购买。
### 更新买赠促销活动
- [PUT /v3/project/{project_id}/admin/promotion/{promotion_id}/bonus](https://xsolla.redocly.app/zh/api/liveops/promotions-bonuses/update-bonus-promotion.md): 更新促销活动。
注：新数据将替换旧数据。如果只想更新促销活动的一部分，也需要在请求中传入所有必需数据。
促销活动会在用户购买时赠送免费赠品。
该促销活动可应用于项目中的任意购买，也可应用于包含特定商品的购买。
### 获取买赠促销活动
- [GET /v3/project/{project_id}/admin/promotion/{promotion_id}/bonus](https://xsolla.redocly.app/zh/api/liveops/promotions-bonuses/get-bonus-promotion.md): 获取买赠促销活动。
促销活动会在用户购买时赠送免费赠品。
该促销活动可应用于项目中的任意购买，也可应用于包含特定商品的购买。
### 删除买赠促销活动
- [DELETE /v3/project/{project_id}/admin/promotion/{promotion_id}/bonus](https://xsolla.redocly.app/zh/api/liveops/promotions-bonuses/delete-bonus-promotion.md): 删除买赠促销活动。删除的促销活动将：
* 从您项目中设置的促销活动列表中消。失
* 不再应用于商品目录和购物车。用户无法通过该促销活动获得赠品。
删除后，该促销活动无法恢复。
## 个性化商品目录
个性化功能允许您指定商品目录显示和促销活动应用的条件，使其仅面向特定授权用户生效。条件基于用户属性定义，可帮助您向特定用户提供最相关的商品和促销活动。
支持以下个性化类型：
* [艾克索拉侧个性化](/zh/liveops/promotion-tools/personalization/#guides_personalization_on_xsolla_side)。个性化规则和逻辑在艾克索拉侧配置并存储。您传入用户属性后，艾克索拉会使用这些属性生成个性化商品目录。
* [合作伙伴侧个性化](/zh/liveops/promotion-tools/personalization/#guides_personalization_on_partner_side)。您在己侧配置个性化规则和逻辑，并将特定用户的最终商品目录数据载荷发送给艾克索拉。
注：
您只能使用一种个性化类型。如需更改，请按照
说明进行操作。
如需使用艾克索拉API在艾克索拉侧配置个性化：
1. 使用[虚拟物品和货币](/zh/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list/)、[捆绑包](/zh/api/catalog/bundles-admin/admin-create-bundle)或[游戏Key](/zh/api/catalog/game-keys-admin)组的**管理**子部分中的API调用创建商品。
2. 使用[使用艾克索拉登录管理器API设置用户属性](/zh/liveops/promotion-tools/personalization/#web_shop_guide_personalization_setting_attributes)，并在您的游戏中发生变更时更新艾克索拉中的数据，确保数据保持同步。
3. 为商品或促销活动配置个性化：
* 如需对商品目录进行个性化，请使用[创建商品目录筛选规则](/zh/api/liveops/personalized-catalog/create-filter-rule) API 调用定义商品目录显示规则：
* 在[attribute_conditions](/zh/api/liveops/personalized-catalog/create-filter-rule#personalized-catalog/create-filter-rule/t=request&path=attribute_conditions)数组中，指定根据用户属性确定商品可用性的条件。
* 在[items](/zh/api/liveops/personalized-catalog/create-filter-rule#personalized-catalog/create-filter-rule/t=request&path=items)数组中，提供在用户属性符合指定条件时应向用户显示的商品列表。
* 如需配置个性化促销活动，请使用[所需促销活动类型的创建和更新API调用]](/zh/api/liveops/promotions-discounts/create-item-promotion)。在[attribute_conditions](/zh/api/liveops/promotions-discounts/create-item-promotion)数组中，指定基于用户属性确定促销活动可用性的条件。
4. 在[商品目录获取API调用](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items)中传入包含用户属性的[用户JWT](/zh/api/login/getting-user-token?#getting-user-token)，以接收个性化商品目录。
**为商品目录配置并应用艾克索拉侧个性化的流程：**
**为促销活动配置并应用艾克索拉侧个性化的流程：**
### 获取商品目录筛选规则列表
- [GET /v2/project/{project_id}/admin/user/attribute/rule](https://xsolla.redocly.app/zh/api/liveops/personalized-catalog/get-filter-rules.md): 获取应用于用户属性的所有规则。
### 创建商品目录筛选规则
- [POST /v2/project/{project_id}/admin/user/attribute/rule](https://xsolla.redocly.app/zh/api/liveops/personalized-catalog/create-filter-rule.md): 创建用户属性的规则。
### 获取用于客户端侧搜索的所有商品目录规则
- [GET /v2/project/{project_id}/admin/user/attribute/rule/all](https://xsolla.redocly.app/zh/api/liveops/personalized-catalog/get-all-filter-rules.md): 获取用于在客户端侧搜索的所有商品目录规则列表。
注意仅返回规则 ID、名称和is_enabled
### 获取商品目录筛选规则
- [GET /v2/project/{project_id}/admin/user/attribute/rule/{rule_id}](https://xsolla.redocly.app/zh/api/liveops/personalized-catalog/get-filter-rule-by-id.md): 获取应用于用户属性的指定规则。
### 更新商品目录筛选规则
- [PUT /v2/project/{project_id}/admin/user/attribute/rule/{rule_id}](https://xsolla.redocly.app/zh/api/liveops/personalized-catalog/update-filter-rule-by-id.md): 更新应用于用户属性的指定规则。默认值将用于未指定的属性（如果属性非必需）。
### 部分更新商品目录筛选规则
- [PATCH /v2/project/{project_id}/admin/user/attribute/rule/{rule_id}](https://xsolla.redocly.app/zh/api/liveops/personalized-catalog/patch-filter-rule-by-id.md): 更新应用于用户属性的指定规则。当前值将用于未指定的属性。
### 删除商品目录筛选规则
- [DELETE /v2/project/{project_id}/admin/user/attribute/rule/{rule_id}](https://xsolla.redocly.app/zh/api/liveops/personalized-catalog/delete-filter-rule-by-id.md): 删除指定规则。
## 管理
### 刷新指定用户的所有促销活动限制
- [DELETE /v2/project/{project_id}/admin/user/limit/promotion/all](https://xsolla.redocly.app/zh/api/liveops/user-limits-admin/reset-all-user-promotions-limit.md): 刷新指定用户所有促销活动的所有限制，以便其可以再次使用这些促销活动。
用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：
* 折扣促销活动
* 买赠促销活动
### 刷新用户的促销活动限制
- [DELETE /v2/project/{project_id}/admin/user/limit/promotion/id/{promotion_id}/all](https://xsolla.redocly.app/zh/api/liveops/user-limits-admin/reset-user-promotion-limit.md): 刷新促销活动限制以便用户可以再次使用该促销活动。如果user参数为null，此调用将刷新所有用户的此限制。
用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：
* 折扣促销活动
* 买赠促销活动
### 获取指定用户的促销活动限制
- [GET /v2/project/{project_id}/admin/user/limit/promotion/id/{promotion_id}](https://xsolla.redocly.app/zh/api/liveops/user-limits-admin/get-user-promotion-limit.md): 获取指定用户在应用的限制内可以使用促销活动的剩余次数。
用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：
* 折扣促销活动
* 买赠促销活动
### 增加指定用户的促销活动限制
- [POST /v2/project/{project_id}/admin/user/limit/promotion/id/{promotion_id}](https://xsolla.redocly.app/zh/api/liveops/user-limits-admin/add-user-promotion-limit.md): 增加指定用户在应用的限制内可以使用促销活动的剩余次数。
用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：
* 折扣促销活动
* 买赠促销活动
### 设置指定用户的促销活动限制
- [PUT /v2/project/{project_id}/admin/user/limit/promotion/id/{promotion_id}](https://xsolla.redocly.app/zh/api/liveops/user-limits-admin/set-user-promotion-limit.md): 在增加或减少次数后设置指定用户在应用的限制内可以使用促销活动的次数。
用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：
* 折扣促销活动
* 买赠促销活动
### 减少指定用户的促销活动限制
- [DELETE /v2/project/{project_id}/admin/user/limit/promotion/id/{promotion_id}](https://xsolla.redocly.app/zh/api/liveops/user-limits-admin/remove-user-promotion-limit.md): 在已应用的限制内，减少指定用户可使用促销活动的剩余次数。
用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：
* 折扣促销活动
* 买赠促销活动
## 管理
### 获取累充积分列表
- [GET /v2/project/{project_id}/admin/items/value_points](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-get-value-points-list.md): 获取项目内的累充积分列表以用于管理。
### 创建累充积分
- [POST /v2/project/{project_id}/admin/items/value_points](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-create-value-points.md): 创建累充积分。
### 获取累充积分
- [GET /v2/project/{project_id}/admin/items/value_points/sku/{item_sku}](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-get-value-point.md): 根据项目中的SKU获取累充积分以进行管理。
### 更新累充积分
- [PUT /v2/project/{project_id}/admin/items/value_points/sku/{item_sku}](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-update-value-point.md): 按SKU更新累充积分。
### 删除累充积分
- [DELETE /v2/project/{project_id}/admin/items/value_points/sku/{item_sku}](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-delete-value-point.md): 按SKU删除累充积分。
### 获取具有累充积分的商品列表
- [GET /v2/project/{project_id}/admin/items/{value_point_sku}/value_points/rewards](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-get-items-value-point-reward.md): 获取项目内具有累充积分的商品列表以用于管理。
### 设置商品的累充积分
- [PUT /v2/project/{project_id}/admin/items/{value_point_sku}/value_points/rewards](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-set-items-value-point-reward.md): 按SKU为一件或多件商品分配累充积分。用户购买这些商品后将获得累充积分。
请注意，此PUT请求将覆盖项目中商品此前设置的所有累充积分。
为避免误删累充积分，请在每个PUT请求中包含所有商品及其对应的累充积分。
如果只想更新特定商品的累充积分，同时保留其他商品的累充积分，请先使用GET请求获取当前累充积分集合，修改目标商品的累充积分，然后将包含该商品更新后累充积分的完整集合发回。
### 部分更新商品的累充积分
- [PATCH /v2/project/{project_id}/admin/items/{value_point_sku}/value_points/rewards](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-patch-items-value-point-reward.md): 按照商品SKU部分更新一个或多个商品的累充积分数量。用户购买指定商品后可获得这些累充积分。
更新累充积分的原则：
* 如果某个商品尚无累充积分，则在amount字段中发送非零值将创建累充积分。
* 如果某个商品已有累充积分，则在amount字段中发送非零值将更新累充积分。
* 如果amount设置为0，则会删除该商品的现有累充积分。
与PUT方法（设置商品的累充积分）不同，此PATCH方法不会覆盖项目中所有商品的现有累充积分，而只会更新指定商品。
单个请求最多可以更新100个商品。同一请求中不能包含重复的商品SKU。
### 删除商品的累充积分
- [DELETE /v2/project/{project_id}/admin/items/{value_point_sku}/value_points/rewards](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-delete-items-value-point-reward.md): 删除所有商品的累充积分奖励。
### 获取累充奖励链列表
- [GET /v3/project/{project_id}/admin/reward_chain](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-get-reward-chains.md): 获取累充奖励链列表。
注意所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应10项。如需逐页获取更多数据，请使用limit和offset字段。
### 创建累充奖励链
- [POST /v3/project/{project_id}/admin/reward_chain](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-create-reward-chain.md): 创建累充奖励链。
### 获取累充奖励链
- [GET /v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-get-reward-chain.md): 获取指定累充奖励链。
### 更新累充奖励链
- [PUT /v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-update-reward-chain.md): 更新指定累充奖励链。
### 删除累充奖励链
- [DELETE /v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-delete-reward-chain.md): 删除指定累充奖励链。
### 启停累充奖励链
- [PUT /v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}/toggle](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-toggle-reward-chain.md): 启用/禁用累充奖励链。
### 重置累充奖励链
- [POST /v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}/reset](https://xsolla.redocly.app/zh/api/liveops/reward-chain-value-points-admin/admin-reset-reward-chain.md): 重置累充奖励链中所有用户的累充积分余额和进度。余额与累充积分类型绑定，而非与特定累充奖励链绑定。如果这些累充积分也用于其他奖励链，则使用这些累充积分的所有奖励链中的余额都会被重置。重置后，您可以更新累充奖励链的有效期，用户将能够重新推进该累充奖励链。公会余额按其成员余额总和计算。因此，重置后公会余额也会被重置。此请求不可逆，且适用于项目的所有用户。
提示
请勿在累充奖励链有效期内重置累充奖励链。否则，用户可能会在领取奖励前失去已获得的累充积分。
## 客户端
### 获取当前用户的累充奖励链
- [GET /v2/project/{project_id}/user/reward_chain](https://xsolla.redocly.app/zh/api/liveops/reward-chain-client/get-reward-chains-list.md): 客户端接口。获取当前用户的累充奖励链。
注意
所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 获取当前用户的累充积分余额
- [GET /v2/project/{project_id}/user/reward_chain/{reward_chain_id}/balance](https://xsolla.redocly.app/zh/api/liveops/reward-chain-client/get-user-reward-chain-balance.md): 客户端接口。获取当前用户的累充积分余额。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 领取步骤奖励
- [POST /v2/project/{project_id}/user/reward_chain/{reward_chain_id}/step/{step_id}/claim](https://xsolla.redocly.app/zh/api/liveops/reward-chain-client/claim-user-reward-chain-step-reward.md): 客户端接口。从累充奖励链中领取当前用户的阶段奖励。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
## 公会客户端
### 获取公会名下累充奖励链的前10名贡献者列表
- [GET /v2/project/{project_id}/user/clan/contributors/{reward_chain_id}/top](https://xsolla.redocly.app/zh/api/liveops/clan-reward-chain-client/get-user-clan-top-contributors.md): 获取当前用户所在公会下指定累充奖励链的前10名贡献者列表。如果用户不属于任何公会，该调用将返回空数组。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 更新当前用户的公会
- [PUT /v2/project/{project_id}/user/clan/update](https://xsolla.redocly.app/zh/api/liveops/clan-reward-chain-client/user-clan-update.md): 通过用户属性更新当前用户所属的公会。系统会领取该用户此前所属公会中累充奖励链的所有未领取奖励，并在响应中返回这些奖励。如果用户此前属于某个公会，但现在不属于任何公会，则会撤销其公会成员身份。如果用户更换了公会，则会更新为新的公会。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
## 管理
### 获取每日奖励列表
- [GET /v2/project/{project_id}/admin/daily_chain](https://xsolla.redocly.app/zh/api/liveops/daily-chain-admin/admin-get-daily-chains.md): 获取用于管理的每日奖励列表。
提示该方法返回分页的商品列表。最大值和默认值均为每个响应50个商品。如需获取列表中的更多商品，请使用limit和offset参数分页获取。例如，调用方法时传入limit = 25和offset = 100，响应将返回总列表中从第101个商品开始的25个商品。
### 创建每日奖励
- [POST /v2/project/{project_id}/admin/daily_chain](https://xsolla.redocly.app/zh/api/liveops/daily-chain-admin/admin-create-daily-chain.md): 创建每日奖励。
### 获取每日奖励
- [GET /v2/project/{project_id}/admin/daily_chain/id/{daily_chain_id}](https://xsolla.redocly.app/zh/api/liveops/daily-chain-admin/admin-get-daily-chain.md): 获取指定每日奖励以用于管理。
### 更新每日奖励
- [PUT /v2/project/{project_id}/admin/daily_chain/id/{daily_chain_id}](https://xsolla.redocly.app/zh/api/liveops/daily-chain-admin/admin-update-daily-chain.md): 更新指定每日奖励。
### 删除每日奖励
- [DELETE /v2/project/{project_id}/admin/daily_chain/id/{daily_chain_id}](https://xsolla.redocly.app/zh/api/liveops/daily-chain-admin/admin-delete-daily-chain.md): 删除指定每日奖励。
### 切换每日奖励
- [PUT /v2/project/{project_id}/admin/daily_chain/id/{daily_chain_id}/toggle](https://xsolla.redocly.app/zh/api/liveops/daily-chain-admin/admin-toggle-daily-chain.md): 启用或禁用每日奖励。
### 重置每日奖励
- [POST /v2/project/{project_id}/admin/daily_chain/id/{daily_chain_id}/reset](https://xsolla.redocly.app/zh/api/liveops/daily-chain-admin/admin-reset-daily-chain.md): 重置所有用户的每日奖励进度。仅适用于rolling类型每日奖励。
## 客户端
### 获取当前用户的每日奖励
- [GET /v2/project/{project_id}/user/daily_chain](https://xsolla.redocly.app/zh/api/liveops/daily-chain-client/get-daily-chains-list.md): 客户端接口。获取当前用户的每日奖励。
提示该方法返回分页的商品列表。最大值和默认值均为每个响应50个商品。如需获取列表中的更多商品，请使用limit和offset参数分页获取。例如，调用方法时传入limit = 25和offset = 100，响应将返回总列表中从第101个商品开始的25个商品。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 通过ID获取当前用户的每日奖励
- [GET /v2/project/{project_id}/user/daily_chain/{daily_chain_id}](https://xsolla.redocly.app/zh/api/liveops/daily-chain-client/get-user-daily-chain-by-id.md): 客户端接口。通过ID获取当前用户的每日奖励。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 领取每日奖励步骤
- [POST /v2/project/{project_id}/user/daily_chain/{daily_chain_id}/step/number/{step_number}/claim](https://xsolla.redocly.app/zh/api/liveops/daily-chain-client/claim-user-daily-chain-step-reward.md): 客户端接口。领取当前用户每日奖励中的步骤奖励。所有步骤只能按顺序领取。错过步骤的奖励无法通过虚拟货币、真实货币或观看广告获得。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
## 管理
### 获取优惠链列表
- [GET /v2/project/{project_id}/admin/offer_chain](https://xsolla.redocly.app/zh/api/liveops/offer-chain-admin/admin-get-offer-chains.md): 获取优惠链列表以用于管理。
提示所有项目的单次响应中返回的商品数量都有上限。默认值和最大值为每次响应10个商品。如需更多数据，可通过limit与offset查询参数分页获取。
### 创建优惠链
- [POST /v2/project/{project_id}/admin/offer_chain](https://xsolla.redocly.app/zh/api/liveops/offer-chain-admin/admin-create-offer-chain.md): 创建优惠链。
### 获取优惠链
- [GET /v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}](https://xsolla.redocly.app/zh/api/liveops/offer-chain-admin/admin-get-offer-chain.md): 获取指定优惠链以用于管理。
### 更新优惠链
- [PUT /v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}](https://xsolla.redocly.app/zh/api/liveops/offer-chain-admin/admin-update-offer-chain.md): 更新指定优惠链。
### 删除优惠链
- [DELETE /v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}](https://xsolla.redocly.app/zh/api/liveops/offer-chain-admin/admin-delete-offer-chain.md): 删除指定优惠链。
删除后：用户已收到的奖励保留。未完成步骤不再可用，不可再获取奖励。
与通过启停优惠链禁用优惠链不同，删除不可恢复，用户进度不保留。
### 启停优惠链
- [PUT /v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}/toggle](https://xsolla.redocly.app/zh/api/liveops/offer-chain-admin/admin-toggle-offer-chain.md): 启用/禁用优惠链。
禁用后，用户暂时无法访问，但进度保留。
重新启用后，用户可从上次步骤的进度继续。
## 客户端
### 获取当前用户的优惠链
- [GET /v2/project/{project_id}/user/offer_chain](https://xsolla.redocly.app/zh/api/liveops/offer-chain-client/get-offer-chains-list.md): 获取当前用户的优惠链。
提示所有项目的单次响应中返回的商品数量都有上限。默认值和最大值为每次响应30个商品。如需更多数据，可通过limit与offset查询参数分页获取。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 根据ID获取当前用户的优惠链
- [GET /v2/project/{project_id}/user/offer_chain/{offer_chain_id}](https://xsolla.redocly.app/zh/api/liveops/offer-chain-client/get-user-offer-chain-by-id.md): 通过优惠链ID获取当前用户的优惠链。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 领取免费优惠链步骤奖励
- [POST /v2/project/{project_id}/user/offer_chain/{offer_chain_id}/step/number/{step_number}/claim](https://xsolla.redocly.app/zh/api/liveops/offer-chain-client/claim-user-offer-chain-step-reward.md): 完成当前用户的优惠链步骤进程，并发放相关奖励。
提示
仅对优惠链中的免费步骤使用此调用。
对于需要使用真实货币支付的步骤，请改用为付费优惠链步骤创建订单调用。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
### 为付费优惠链步骤创建订单
- [POST /v2/project/{project_id}/user/offer_chain/{offer_chain_id}/step/number/{step_number}/order](https://xsolla.redocly.app/zh/api/liveops/offer-chain-client/order-user-offer-chain-step-reward.md): 为指定的付费优惠链步骤关联的商品创建订单。所创建订单的状态为new。
如需在新窗口中打开支付UI，请使用以下链接：https://secure.xsolla.com/paystation4/?token={token}，其中{token}是收到的令牌。
如要进行测试，请使用以下URL：https://sandbox-secure.xsolla.com/paystation4/?token={token}`。
提示
此方法必须在客户端侧使用。系统会根据用户的IP地址确定其所在国家/地区，这会影响适用货币和可用支付方式。从服务器侧使用此方法可能会导致货币检测错误，并影响支付收银台中的支付方式。
提示
此调用仅适用于付费优惠链步骤。
对于免费步骤，请改用领取免费优惠链步骤奖励调用。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
## payment-client-side
### 为付费优惠链步骤创建订单
- [POST /v2/project/{project_id}/user/offer_chain/{offer_chain_id}/step/number/{step_number}/order](https://xsolla.redocly.app/zh/api/liveops/offer-chain-client/order-user-offer-chain-step-reward.md): 为指定的付费优惠链步骤关联的商品创建订单。所创建订单的状态为new。
如需在新窗口中打开支付UI，请使用以下链接：https://secure.xsolla.com/paystation4/?token={token}，其中{token}是收到的令牌。
如要进行测试，请使用以下URL：https://sandbox-secure.xsolla.com/paystation4/?token={token}`。
提示
此方法必须在客户端侧使用。系统会根据用户的IP地址确定其所在国家/地区，这会影响适用货币和可用支付方式。从服务器侧使用此方法可能会导致货币检测错误，并影响支付收银台中的支付方式。
提示
此调用仅适用于付费优惠链步骤。
对于免费步骤，请改用领取免费优惠链步骤奖励调用。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
## 管理
### 获取项目中追加销售的信息
- [GET /v2/project/{project_id}/admin/items/upsell](https://xsolla.redocly.app/zh/api/liveops/upsell-admin/get-upsell-configurations-for-project-admin.md): 检索项目中追加销售的信息：是否启用、追加销售的类型以及属于此追加销售的商品SKU列表。
### 创建追加销售
- [POST /v2/project/{project_id}/admin/items/upsell](https://xsolla.redocly.app/zh/api/liveops/upsell-admin/post-upsell.md): 为项目创建追加销售。
提示
此API调用使用用户JWT进行授权。
请在Authorization请求头中包含令牌，格式为：Bearer <user_JWT>。有关用户JWT的更多信息，请参阅此调用的安全性部分。
### 更新追加销售
- [PUT /v2/project/{project_id}/admin/items/upsell](https://xsolla.redocly.app/zh/api/liveops/upsell-admin/put-upsell.md): 更新项目的追加销售。
提示
此API调用使用用户JWT进行授权。
请在Authorization请求头中包含令牌，格式为：Bearer <user_JWT>。有关用户JWT的更多信息，请参阅此调用的安全性部分。
### 激活/停用项目的追加销售
- [PUT /v2/project/{project_id}/admin/items/upsell/{toggle}](https://xsolla.redocly.app/zh/api/liveops/upsell-admin/put-upsell-toggle-active-inactive.md): 将项目中追加销售的状态更改为有效或无效。
提示
此API调用使用用户JWT进行授权。
请在Authorization请求头中包含令牌，格式为：Bearer <user_JWT>。有关用户JWT的更多信息，请参阅此调用的安全性部分。
## 客户端
### 获取项目中追加销售商品的列表
- [GET /v2/project/{project_id}/items/upsell](https://xsolla.redocly.app/zh/api/liveops/upsell-client/get-upsell-for-project-client.md): 如果项目中已设置追加销售商品，则获取这些商品的列表。
注：
此API调用使用用户JWT进行授权。
请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
## 管理
### 获取忠诚计划信息
- [GET /projects/{project_id}/admin/program](https://xsolla.redocly.app/zh/api/liveops/loyalty-program-admin/loyalty-get-programs.md): 返回项目忠诚计划的信息。
### 获取计划中的忠诚积分列表
- [GET /projects/{project_id}/admin/programs/{loyalty_program_id}/loyalty_points](https://xsolla.redocly.app/zh/api/liveops/loyalty-program-admin/loyalty-get-program-loyalty-points.md): 返回该计划中的忠诚积分列表。
### 获取用户的忠诚积分余额
- [GET /projects/{project_id}/users/{user_id}/points/{point_id}/balance](https://xsolla.redocly.app/zh/api/liveops/loyalty-program-admin/loyalty-get-user-point-balance.md): 返回指定忠诚积分的当前余额。
### 扣减用户的忠诚积分余额
- [POST /projects/{project_id}/users/{user_id}/points/{point_id}/balance/debit](https://xsolla.redocly.app/zh/api/liveops/loyalty-program-admin/loyalty-debit-user-point-balance.md): 从用户的忠诚积分余额中扣减指定数量的积分。
### 增加用户的忠诚积分余额
- [POST /projects/{project_id}/users/{user_id}/points/{point_id}/balance/credit](https://xsolla.redocly.app/zh/api/liveops/loyalty-program-admin/loyalty-credit-user-point-balance.md): 向用户的忠诚积分余额增加指定数量的积分。
## 客户端
### 获取用户的忠诚积分余额
- [GET /v1/projects/{project_id}/loyalty_point_balance](https://xsolla.redocly.app/zh/api/liveops/loyalty-program-client/loyalty-get-user-balance.md): 返回忠诚积分的当前余额。
### 创建使用忠诚积分购买指定商品的订单
- [POST /v2/project/{project_id}/payment/item/{item_sku}/loyalty_point/{loyalty_point_sku}](https://xsolla.redocly.app/zh/api/liveops/loyalty-program-client/loyalty-create-order-with-item-for-loyalty-points.md): 创建包含指定商品的订单，并完全使用用户的忠诚积分支付。如需一次购买多个商品，请在quantity参数中传入购买数量。