{ "openapi": "3.1.0", "info": { "description": "# 概述\n\n* **Version:** 2.0.0\n* **Servers**: `https://store.xsolla.com/api`\n* **[Contact Us by Email](mailto:integration@xsolla.com)**\n* **Contact URL:** https://xsolla.com/\n* **Required TLS version:** 1.2\n\nLiveOps运营是一套工具包，可通过促销活动和个性化优惠持续提升玩家互动。\n\n使用该API管理以下功能：\n\n* **促销活动** — 创建和管理优惠券、兑换码、折扣和买赠活动。\n* **个性化** — 指定商品目录的显示条件，并仅对特定授权用户应用促销活动。\n* **促销活动限制** — 限制用户可使用促销活动的次数，并为这些限制配置定时重置。\n* **累充奖励链和累充积分** — 配置与累充积分积累相关的奖励进度。\n* **每日奖励链** — 设置周期性每日奖励，鼓励玩家定期登录。\n* **优惠链** — 构建连续购买优惠，支持按链中完成步骤阶梯定价和免费奖励选项。\n* **追加销售** — 一种销售方式，向用户推荐购买具有额外价值的商品。\n\n## API调用\n\n该API分为**以下组**：\n\n* **Admin** — 用于创建、更新、激活和删除活动及奖励链配置的调用。使用您的商户或项目凭据，通过[基本访问身份认证](https://developers.xsolla.com/zh/payment-ui-and-flow/payment-ui/how-to-get-payment-token/#payments_solution_get_user_auth_token_basic_auth)进行身份认证。\n* **Client** — 用于代表已完成身份认证的终端用户获取可用促销活动、获取有效奖励链、核销代码并领取奖励的调用。通过用户JWT进行身份认证。\n\n# 身份认证\n\nAPI调用需要以用户身份或项目身份进行身份认证。使用的身份认证方案见各调用描述中的**安全性**部分。\n\n## 使用用户JWT进行身份认证\n\n当请求从浏览器、移动应用或游戏发送时，使用用户JWT身份认证。默认情况下，应用`XsollaLoginUserJWT`方案。有关如何创建令牌的详细信息，请参阅[艾克索拉登录管理器API文档](/zh/api/login/authentication-schemes#getting-user-token)。\n\n令牌通过`Authorization`请求头按以下格式传递：`Authorization: Bearer `，其中``为用户令牌。该令牌用于识别用户，并授予其访问个性化数据的权限。\n\n或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。\n\n## 基本HTTP身份认证\n\n基本HTTP身份认证用于服务器到服务器交互，即API调用直接从您的服务器发送，而不是从用户的浏览器或移动应用发送。通常使用带有[API密钥](/zh/api/getting-started/#api_keys_overview)的HTTP Basic身份认证。\n\n
注：

API密钥属于机密信息，不得在客户端应用中存储或使用。
\n\n使用基本服务器侧身份认证时，所有API请求都必须包含以下请求头：\n\n- 对于`basicAuth` — `Authorization: Basic `，其中`your_authorization_basic_key`是以Base64编码的`project_id:api_key`对\n- 对于`basicMerchantAuth` — `Authorization: Basic `，其中`your_authorization_basic_key`是以Base64编码的`merchant_id:api_key`对\n\n您可以在[发布商帐户](https://publisher.xsolla.com/)中找到参数值：\n\n- `merchant_id`显示在：\n - **公司设置 > 公司**中。\n - 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com/`。\n- `project_id`显示在：\n - 发布商帐户中项目名称旁边。\n - 发布商帐户中项目页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com//projects/`。\n- `api_key`仅在创建时在发布商帐户中显示，必须在己侧安全存储。您可以在以下部分创建API密钥：\n - [公司设置 > API密钥](https://publisher.xsolla.com/0/settings/api_key)\n - [项目设置 > API密钥](https://publisher.xsolla.com/0/projects/0/edit/api_key)\n\n
提示

如果所需的API调用不包含project_id路径参数，请使用对公司所有项目均有效的API密钥进行授权。
\n\n有关使用API密钥的更多信息，请参阅[API参考](/zh/api/getting-started/#api_keys_overview)。\n\n## 支持访客访问的身份认证\n\n`AuthForCart`身份认证方案用于购物车购买，支持两种模式：\n\n1. **使用用户JWT进行身份认证。** 令牌通过`Authorization`请求头传递，格式如下：`Authorization: Bearer `，其中``为用户令牌。该令牌用于识别用户，并授予其访问个性化数据的权限。或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。\n\n2. **不带Authorization请求头的简化模式。** 此模式仅适用于未完成身份认证的用户，且仅可用于[游戏Key销售](/zh/doc/buy-button/how-to/set-up-authentication/#guides_buy_button_selling_items_not_authenticated_users)请求中不使用令牌，而必须包含以下请求头：\n - `x-unauthorized-id`，值为请求ID\n - `x-user`，值为使用Base64编码的用户电子邮件地址\n\n## 实用链接\n\n- [按交互模型划分的API调用](https://developers.xsolla.com/zh/api/catalog/)\n- [接口类型](https://developers.xsolla.com/zh/api/catalog/)\n- [错误处理](https://developers.xsolla.com/zh/api/catalog/)\n- [API密钥](https://developers.xsolla.com/zh/api/catalog/)\n\n# 核心实体结构\n\n所有类型的商品（虚拟物品、捆绑包、虚拟货币和密钥）都使用类似的数据结构。了解基本结构有助于简化API使用，并帮助您更轻松地查阅文档。\n\n
注：

部分调用可能包含其他字段，但这些字段不会改变基本结构。
\n\n**标识信息**\n\n- `merchant_id` — [发布商帐户](https://publisher.xsolla.com/)中的公司ID\n- `project_id` — 发布商帐户中的项目ID\n- `sku` — 商品SKU，在项目内唯一\n\n**商店显示**\n\n- `name` — 商品名称\n- `description` — 商品描述\n- `image_url` — 图片URL\n- `is_enabled` — 商品可用性\n- `is_show_in_store` — 商品是否显示在商品目录中\n\n有关在商品目录中管理商品可用性的更多信息，请参阅[文档](/zh/items-catalog/catalog-features/items-availability/)。\n\n**组织方式**\n\n- `type` — 商品类型，例如虚拟物品（`virtual_item`）或捆绑包（`bundle`）\n- `groups` — 商品所属的组\n- `order` — 在商品目录中的显示顺序\n\n**Sale conditions**\n\n- `prices` — 以真实货币或虚拟货币表示的价格\n- `limits` — 购买限制\n- `periods` — 可用时间段\n- `regions` — 区域限制\n\n**核心实体结构示例：**\n\n```json\n{\n \"attributes\": [],\n \"bundle_type\": \"virtual_currency_package\",\n \"content\": [\n {\n \"description\": {\n \"en\": \"Main in-game currency\"\n },\n \"image_url\": \"https://.../image.png\",\n \"name\": {\n \"en\": \"Crystals\",\n \"de\": \"Kristalle\"\n },\n \"quantity\": 500,\n \"sku\": \"com.xsolla.crystal_2\",\n \"type\": \"virtual_currency\"\n }\n ],\n \"description\": {\n \"en\": \"Crystals x500\"\n },\n \"groups\": [],\n \"image_url\": \"https://.../image.png\",\n \"is_enabled\": true,\n \"is_free\": false,\n \"is_show_in_store\": true,\n \"limits\": {\n \"per_item\": null,\n \"per_user\": null,\n \"recurrent_schedule\": null\n },\n \"long_description\": null,\n \"media_list\": [],\n \"name\": {\n \"en\": \"Medium crystal pack\"\n },\n \"order\": 1,\n \"periods\": [\n {\n \"date_from\": null,\n \"date_until\": \"2020-08-11T20:00:00+03:00\"\n }\n ],\n \"prices\": [\n {\n \"amount\": 20,\n \"country_iso\": \"US\",\n \"currency\": \"USD\",\n \"is_default\": true,\n \"is_enabled\": true\n }\n ],\n \"regions\": [],\n \"sku\": \"com.xsolla.crystal_pack_2\",\n \"type\": \"bundle\",\n \"vc_prices\": []\n}\n```\n\n# 基本购买流程\n\n艾克索拉API可用于实现游戏内购商店逻辑，包括获取商品目录、管理购物车、创建订单以及跟踪订单状态。根据集成场景，API调用分为**管理**和**商品目录**子部分，使用不同的[身份认证方案](/zh/api/catalog/section/authentication)。\n\n以下示例展示了从创建商品到完成购买的商店设置和运营基本流程。\n\n## 创建商品和组（管理）\n\n为您的商店创建商品目录，例如虚拟物品、捆绑包或虚拟货币。\n\nAPI调用示例：\n- [创建虚拟物品](/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-item)\n- [创建捆绑包](/zh/api/catalog/bundles-admin/admin-create-bundle)\n- [创建虚拟货币](/zh/api/catalog/virtual-items-currency-admin/admin-create-virtual-currency)\n\n## 设置促销、奖励链和限制（管理）\n\n配置用户拉新和赢利工具，例如折扣、赠品、每日奖励或优惠链。\n\nAPI调用示例：\n- [创建买赠促销活动](/zh/api/liveops/promotions-bonuses/create-bonus-promotion)\n- [创建每日奖励](/zh/api/liveops/daily-chain-admin/admin-create-daily-chain)\n- [创建唯一商品目录优惠促销活动](/zh/api/liveops/promotions-unique-catalog-offers/admin-create-unique-catalog-offer)\n\n## 获取商品信息（客户端）\n\n在您的应用程序中配置商品显示。\n\n
\n 提示

\n 请勿使用管理子部分中的API调用来构建用户商品目录。这些API调用存在速率限制，并不适用于用户流量。\n
\n\n
\n\nAPI调用示例：\n- [获取虚拟物品列表](/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items)\n- [获取商品组列表](/zh/api/catalog/virtual-items-currency-catalog/get-item-groups)\n- [获取捆绑包列表](/zh/api/catalog/bundles-catalog/get-bundle-list)\n- [获取可售商品列表](/zh/api/catalog/common-catalog/get-sellable-items)\n\n
\n 注：

\n 默认情况下，商品目录API调用会返回请求时商店中当前可用的商品。如需获取尚未可用或已不再可用的商品，请在商品目录请求中包含参数\"show_inactive_time_limited_items\": 1。\n
\n\n## 销售商品\n\n您可以使用以下方法销售商品：\n- 快速购买 — 多次销售同一SKU。\n- 购物车购买 — 用户可在同一订单中向购物车添加商品、移除商品并更新数量。\n\n如果商品使用虚拟货币而非真实货币购买，请使用[创建包含指定商品的订单](/zh/api/catalog/virtual-payment/create-order-with-item-for-virtual-currency) API调用。由于扣款会在执行API调用时处理，因此无需支付UI。\n\n如需购买免费商品，请使用[使用指定商品创建订单](/zh/api/catalog/free-item/create-free-order-with-item) API调用或[使用免费购物车创建订单](/zh/api/catalog/free-item/create-free-order) API调用。无需支付UI — 订单会立即设置为done状态。\n\n### 快速购买\n\n使用客户端API调用[使用指定商品创建订单](/zh/api/catalog/payment-client-side/create-order-with-item)。该调用会返回用于打开支付UI的令牌。\n\n
\n 注：

\n 用户只能在支付UI中查看折扣信息。不支持兑换码。\n
\n\n### 购物车购买\n\n可以在客户端或服务器侧设置购物车并完成购买。\n\n**在客户端设置和购买购物车商品**\n\n您需要自行实现添加和移除商品的逻辑。在调用用于设置购物车的API之前，您无法获知哪些促销活动会应用于本次购买。这意味着您无法提前获知总费用以及添加的赠品的详细信息。\n\n实现以下购物车逻辑：\n1. 玩家在购物车加购后，使用[向购物车添加商品](/zh/api/shop-builder/operation/cart-fill/) API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。\n2. 根据用户操作更新购物车内容：\n - 如需添加商品或更改商品数量，请使用[按购物车ID更新购物车商品](/zh/api/shop-builder/operation/put-item-by-cart-id/) API调用。\n - 如需移除商品，请使用[按购物车ID删除购物车商品](/zh/api/shop-builder/operation/delete-item-by-cart-id/) API调用。\n\n
\n 注：

\n 如需获取购物车的当前状态，请使用“获取当前用户的购物车”API调用。\n
\n\n3. 使用[创建包含当前购物车中所有商品的订单](/zh/api/shop-builder/operation/create-order/) API调用。该调用返回订单ID和支付令牌。新创建的订单默认设置为new状态。\n\n**在服务器侧设置和购买购物车商品**\n\n这种设置方式可能需要更长的购物车设置时间，因为每次更改购物车都必须伴随API调用。\n\n实现以下购物车逻辑：\n1. 玩家在购物车加购后，使用[向购物车添加商品](/zh/api/catalog/cart-server-side) API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。\n2. 使用[创建包含当前购物车中所有商品的订单](/zh/api/shop-builder/operation/create-order/) API调用。该调用会返回订单ID和支付令牌。新创建的订单默认设置为new状态。\n\n## 打开支付UI\n\n使用返回的令牌在新窗口中打开支付UI。有关打开支付UI的其他方式，请参阅[文档](/zh/payment-ui-and-flow/payment-ui/how-to-open-payment-ui/#open_payment_ui)。\n\n| 操作 | 接口 |\n|:--------------------------------|:--------------------------------------------------------------------------|\n| 在生产环境中打开。 | https://secure.xsolla.com/paystation4/?token={token} |\n| 在沙盒模式中打开。 | https://sandbox-secure.xsolla.com/paystation4/?token={token} |\n\n
\n 注：

\n 请在开发和测试期间使用沙盒模式。测试购买不会对真实帐户扣款。您可以使用测试银行卡。\n\n 完成第一笔真实支付后，严格的沙盒支付策略将生效。沙盒模式下的支付仅对[发布商帐户 > 公司设置 > 用户](https://publisher.xsolla.com/0/settings/users)中指定的用户可用。\n\n 只有在与艾克索拉签署许可协议后，才能使用真实货币购买虚拟货币和商品。如需签署协议，请在[发布商帐户](https://publisher.xsolla.com/)中前往**协议与税务 > 合同与协议**，填写协议表单并等待确认。协议审核最多可能需要3个工作日。\n
\n\n如需启用或禁用沙盒模式，请在快速购买和购物车购买请求中更改`sandbox`参数的值。沙盒模式默认关闭。\n\n可能的订单状态：\n- `new` — 订单已创建\n- `paid` — 已收到付款\n- `done` — 商品已交付\n- `canceled` — 订单已取消\n- `expired` — 订单已过期\n\n使用以下任一方式跟踪订单状态：\n- [您服务器上配置的Webhook](/zh/virtual-goods/own-ui/server-side-token-generation/set-up-order-tracking/#payments_integration_order_tracking)\n- [短轮询](/zh/virtual-goods/own-ui/client-side-token-generation/set-up-order-tracking/#guides_shop_builder_integrate_store_get_order_status_via_short_polling)\n- [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)\n\n## 实用链接\n\n- 身份认证\n- [按交互模型划分的API调用](/zh/api/catalog/section/authentication)\n- [支付测试](/zh/dev-resources/testing/general-info/#general_overview)\n- [设置订单状态跟踪](/zh/virtual-goods/own-ui/client-side-token-generation/set-up-order-tracking/?link=200-api#payments_integration_order_tracking)\n- [Webhook](/zh/webhooks/overview)\n- [速率限制](/zh/api/login/rate-limits)\n- [错误处理](/zh/api/getting-started/#api_errors_handling)\n- [API密钥](/zh/api/getting-started/#api_keys_overview)\n\n# 分页\n\n返回大量记录的API调用（例如构建商品目录时）会按页返回数据。分页是一种限制单个API响应中返回商品数量的机制，并允许您按顺序获取后续页面。\n\n使用以下参数控制返回的商品数量：\n\n- `limit` — 每页商品数量\n- `offset` — 页面中第一个商品的索引（从0开始编号）\n- `has_more` — 指示是否还有下一页\n- `total_items_count` — 商品总数\n\n请求示例：\n\n```\nGET /items?limit=20&offset=40\n```\n\n响应示例：\n\n```json\n{\n \"items\": [...],\n \"has_more\": true,\n \"total_items_count\": 135\n}\n```\n\n建议发送后续请求，直到响应返回`has_more = false`。\n\n# 日期和时间格式\n\n日期和时间值以[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)格式传递。\n\n支持以下内容：\n\n- UTC偏移量\n- 当商品显示没有时间限制时使用`null`值\n- 部分字段使用的[Unix时间戳](https://www.unixtimestamp.com/)（以秒为单位）\n\n格式：`YYYY-MM-DDTHH:MM:SS±HH:MM`\n\n示例：`2026-03-16T10:00:00+03:00`\n\n# 本地化\n\n艾克索拉支持对商品名称、描述等面向用户的字段进行本地化。本地化值以对象形式传递，其中语言代码作为键。支持的完整语言列表，请参阅[文档](/zh/doc/shop-builder/references/supported-languages/)。\n\n**支持的字段**\n\n可为以下参数指定本地化内容：\n\n- `name`\n- `description`\n- `long_description`\n\n**区域格式**\n\n语言区域键可使用以下任一格式指定：\n\n- 两字母语言代码：`en`、`ru`\n- 五字母语言代码：`en-US`、`ru-RU`、`de-DE`\n\n**示例**\n\n两字母语言代码示例：\n\n```json\n{\n \"name\": {\n \"en\": \"Starter Pack\",\n \"ru\": \"Стартовый набор\"\n }\n}\n```\n\n五字母语言代码示例：\n\n```json\n{\n \"description\": {\n \"en-US\": \"Premium bundle\",\n \"de-DE\": \"Premium-Paket\"\n }\n}\n```\n\n# 错误响应格式\n\n如果发生错误，API会返回HTTP状态和JSON响应正文。商店相关错误的完整列表，请参阅[文档](/zh/dev-resources/references/errors/store-errors/)。\n\n**响应示例：**\n\n```json\n{\n \"errorCode\": 1102,\n \"errorMessage\": \"Validation error\",\n \"statusCode\": 422,\n \"transactionId\": \"c9e1a...\"\n}\n```\n\n- `errorCode` — 错误代码。\n- `errorMessage` — 简短的错误描述。\n- `statusCode` — HTTP响应状态。\n- `transactionId` — 请求ID。仅在部分情况下返回。\n- `errorMessageExtended` — 其他错误详情，例如请求参数。仅在某些情况下返回。\n\n**扩展响应示例：**\n\n```json\n{\n \"errorCode\": 7001,\n \"errorMessage\": \"Chain not found\",\n \"errorMessageExtended\": {\n \"chain_id\": \"test_chain_id\",\n \"project_id\": \"test_project_id\",\n \"step_number\": 2\n },\n \"statusCode\": 404\n}\n```\n\n**常见HTTP状态代码**\n\n- `400` — 请求无效\n- `401` — 身份认证错误\n- `403` — 权限不足\n- `404` — 资源未找到\n- `422` — 验证错误\n- `429` — 超出速率限制\n\n**建议**\n\n- 结合HTTP状态和响应正文一起处理。\n- 使用`errorCode`处理与应用程序逻辑相关的错误。\n- 分析错误时，使用`transactionId`更快定位请求。", "version": "2.0.0", "title": "LiveOps运营API" }, "servers": [ { "url": "https://store.xsolla.com/api" } ], "tags": [ { "name": "promotion-limits-overview", "x-displayName": "概述", "description": "促销活动使用限制用于限制特定用户可使用某个促销活动的次数。您还可以配置定时重置限制。\n\n限制数信息存储在艾克索拉侧，可在[发布商帐户](https://publisher.xsolla.com/0/projects/0/storefront/promotions)的促销活动设置中配置，也可以在以下API调用中通过`limits`对象配置：\n* [为商品创建折扣促销活动](/zh/api/liveops/promotions-discounts/create-item-promotion/)或[更新折扣促销活动](/zh/api/liveops/promotions-discounts/update-item-promotion)\n* [创建买赠促销活动](/zh/api/liveops/promotions-bonuses/create-bonus-promotion/)或[更新买赠促销活动](/zh/api/liveops/promotions-bonuses/update-bonus-promotion)\n\nLimit information is returned in the `items.promotions.limits` object in the following API calls for retrieving the items catalog:\n* [Get virtual items list](/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items/)\n* [Get virtual currency list](/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency/)\n* [Get virtual currency packages list](/zh/api/catalog/virtual-items-currency-catalog/get-virtual-currency-package/)\n* [Get bundles list](/zh/api/catalog/bundles-catalog/get-bundle-list/)\n* [Get games list](/zh/api/catalog/game-keys-catalog/get-games-list/)\n\n**限制**组的**管理**部分中的API调用可用于获取限制的当前状态，并针对特定用户更新限制，例如在任务完成后重置计数器，或手动调整剩余数量。\n\n
\n 注：

\n 有关在商品目录中配置限制数的详细信息，请参阅促销活动使用限制部分。\n
\n\n您可以配置[limits.per_user](/zh/api/liveops/promotions-discounts/create-item-promotion#promotions-discounts/create-item-promotion/t=request&path=limits)，即单个用户可使用某个促销活动的次数限制。\n\n未认证用户始终会看到促销活动的最大可使用次数。\n\n如需显示用户在当前有效限制下剩余的促销活动可使用次数，请在请求商品目录时传入用户授权数据。\n\n如需配置定时重置周期（日、周或月），请在[创建](/zh/api/liveops/promotions-discounts/create-item-promotion#promotions-discounts/create-item-promotion/t=request&path=limits/recurrent_schedule)或[更新](/zh/api/liveops/promotions-discounts/update-item-promotion#promotions-discounts/update-item-promotion/t=request&path=limits/recurrent_schedule)促销活动时传入`limits.recurrent_schedule`对象。\n\n**限制配置和执行场景**\n\n1. 使用[为商品创建折扣促销](/zh/api/liveops/promotions-discounts/create-item-promotion/)或[创建买赠促销活动](/zh/api/liveops/promotions-bonuses/create-bonus-promotion/) API调用创建促销活动，并传入`limits`对象。\n2. 为未认证用户请求商品目录⸺响应会在`items.promotions.limits`对象中返回促销活动的最大可使用次数。\n3. 用户登录。\n4. 使用用户的授权令牌请求商品目录⸺响应会返回当前有效限制下的剩余可使用次数。\n5. 用户选择促销商品并进行购买。\n6. 支付成功后，艾克索拉会更新`items.promotions.limits.per_user`值。当该值达到`0`时，后续商品目录API调用会返回该商品，但不再包含折扣或赠品。\n7. 您可以使用**管理**子部分中的API调用更新限制数：\n * [刷新指定用户的所有促销活动限制](/zh/api/liveops/user-limits-admin/reset-all-user-promotions-limit/)或[刷新特定促销活动的限制](/zh/api/liveops/user-limits-admin/reset-user-promotion-limit/)\n * [设置特定限制值](/zh/api/liveops/user-limits-admin/set-user-promotion-limit/)\n * [增加](/zh/api/liveops/user-limits-admin/add-user-promotion-limit/)或[减少可用次数](/zh/api/liveops/user-limits-admin/remove-user-promotion-limit/)\n8. 在下一次使用用户授权令牌发起的商品目录请求中，您可以从`items.promotions.limits`获取更新后的限制值，并将其显示给用户。\n\n![促销活动限制](https://cdn.xsolla.net/developers/current/images/api_docs/promotion-limit.svg)" }, { "name": "promotions-overview", "x-displayName": "概述", "description": "促销活动是用于吸引新用户并提升销售额的营销工具。您可以使用艾克索拉API配置以下促销活动：\n\n* 折扣 — 为所选商品提供降价优惠。\n* 赠品 — 用户购买时随订单获得的商品。\n* 优惠券 — 用户兑换后可获得一个或多个赠品的代码。\n* 兑换码 — 用户可通过此类代码获得赠品、特定商品折扣或整个购物车折扣。优惠券会在用户输入后兑换；与之不同，兑换码会在购买过程中（结算时）兑换。\n* 专属优惠 — 在商品目录中向已输入专属优惠代码的用户显示的隐藏商品。如果未输入代码，则不会显示这些商品。\n\n配置折扣促销活动的示例流程：\n1. 使用[虚拟物品和货币](/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)组的**管理**子部分中的调用创建商品。\n2. 使用[为商品创建折扣促销活动](/zh/api/liveops/promotions-discounts/create-item-promotion/)调用创建促销活动。在`items`数组中传入所需的商品SKU。\n3. 设置促销活动有效期。为此，请调用[为商品创建折扣促销活动](/zh/api/liveops/promotions-discounts/create-item-promotion/)或[更新商品促销活动](/zh/api/liveops/promotions-discounts/update-item-promotion/)方法，并将`promotion_periods`字段作为对象数组传入，其中`date_from`定义有效期开始日期，`date_until`定义有效期结束日期。\n4. 使用[更新商品促销活动](/zh/api/liveops/promotions-discounts/update-item-promotion/)调用激活促销活动。传入`\"is_enabled\": true`参数。\n5. 如需获取商品价格信息（包括折后价格），请调用[通用 > 商品目录](/zh/api/catalog/tag/common-catalog/)、[虚拟物品和货币 > 商品目录](/zh/api/catalog/virtual-items-currency-catalog/get-virtual-items/)和[捆绑包 > 商品目录](/zh/api/catalog/bundles-catalog/get-bundle-list/)子部分中用于获取商品目录的客户端API方法。\n\n![促销活动配置示例](https://cdn.xsolla.net/developers/current/images/api_docs/promo-overview.svg)\n\n关于配置促销活动的详细信息，请参阅我们的文档：\n* [折扣](https://developers.xsolla.com/zh/liveops/promotion-tools/discounts/)\n* [买赠](https://developers.xsolla.com/zh/liveops/promotion-tools/bonuses/)\n* [优惠券](https://developers.xsolla.com/zh/liveops/promotion-tools/coupons/)\n* [兑换码](https://developers.xsolla.com/zh/liveops/promotion-tools/promo-codes/)\n* [专属商品目录优惠](https://developers.xsolla.com/zh/liveops/promotion-tools/unique-offer/)" }, { "name": "promotions-common", "x-displayName": "通用API调用", "description": "您可以调用此子部分中的API方法，管理不同类型的促销活动。" }, { "name": "promotions-coupons", "x-displayName": "优惠券", "description": "调用此子部分中的API方法，配置和管理优惠券促销活动。\n\n
\n

注：

\n

关于优惠券的详细信息，请参阅我们的文档。

\n
" }, { "name": "promotions-promo-codes", "x-displayName": "兑换码", "description": "Call API methods from this subsection to configure and manage promo code promotions.\n\n
\n

注：

\n

关于兑换码的详细信息，请参阅我们的文档。

\n
" }, { "name": "promotions-unique-catalog-offers", "x-displayName": "专属商品目录优惠", "description": "调用此子部分中的API方法，配置和管理专属商品目录优惠。\n\n
\n

注：

\n

关于专属优惠的详细信息，请参阅我们的文档。

\n
" }, { "name": "promotions-discounts", "x-displayName": "折扣", "description": "调用此子部分中的API方法，配置和管理折扣促销活动。\n\n
\n

注：

\n

关于折扣的详细信息，请参阅我们的文档。

\n
" }, { "name": "promotions-bonuses", "x-displayName": "买赠", "description": "调用此子部分中的API方法，配置和管理买赠促销活动。\n\n
\n

注：

\n

关于赠品的详细信息，请参阅我们的文档。

\n
" }, { "name": "personalized-catalog", "x-displayName": "个性化商品目录", "description": "个性化功能允许您指定商品目录显示和促销活动应用的条件，使其仅面向特定授权用户生效。条件基于用户属性定义，可帮助您向特定用户提供最相关的商品和促销活动。\n\n支持以下个性化类型：\n\n* [艾克索拉侧个性化](/zh/liveops/promotion-tools/personalization/#guides_personalization_on_xsolla_side)。个性化规则和逻辑在艾克索拉侧配置并存储。您传入用户属性后，艾克索拉会使用这些属性生成个性化商品目录。\n* [合作伙伴侧个性化](/zh/liveops/promotion-tools/personalization/#guides_personalization_on_partner_side)。您在己侧配置个性化规则和逻辑，并将特定用户的最终商品目录数据载荷发送给艾克索拉。\n\n
\n 注：

\n 您只能使用一种个性化类型。如需更改，请按照\n 说明进行操作。\n
\n\n如需使用艾克索拉API在艾克索拉侧配置个性化：\n\n1. 使用[虚拟物品和货币](/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调用创建商品。\n2. 使用[使用艾克索拉登录管理器API设置用户属性](/zh/liveops/promotion-tools/personalization/#web_shop_guide_personalization_setting_attributes)，并在您的游戏中发生变更时更新艾克索拉中的数据，确保数据保持同步。\n3. 为商品或促销活动配置个性化：\n * 如需对商品目录进行个性化，请使用[创建商品目录筛选规则](/zh/api/liveops/personalized-catalog/create-filter-rule) API 调用定义商品目录显示规则：\n * 在[attribute_conditions](/zh/api/liveops/personalized-catalog/create-filter-rule#personalized-catalog/create-filter-rule/t=request&path=attribute_conditions)数组中，指定根据用户属性确定商品可用性的条件。\n * 在[items](/zh/api/liveops/personalized-catalog/create-filter-rule#personalized-catalog/create-filter-rule/t=request&path=items)数组中，提供在用户属性符合指定条件时应向用户显示的商品列表。\n * 如需配置个性化促销活动，请使用[所需促销活动类型的创建和更新API调用]](/zh/api/liveops/promotions-discounts/create-item-promotion)。在[attribute_conditions](/zh/api/liveops/promotions-discounts/create-item-promotion)数组中，指定基于用户属性确定促销活动可用性的条件。\n\n4. 在[商品目录获取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)，以接收个性化商品目录。\n\n**为商品目录配置并应用艾克索拉侧个性化的流程：**\n\n![商品目录个性化](https://cdn.xsolla.net/developers/current/images/api_docs/personalization-catalog.png)\n\n**为促销活动配置并应用艾克索拉侧个性化的流程：**\n\n![促销活动个性化](https://cdn.xsolla.net/developers/current/images/api_docs/personalization-liveops.png)\n\n
\n注：

\n详细信息请参阅：\n\n
" }, { "name": "user-limits-admin", "x-displayName": "管理" }, { "name": "reward-chain-value-points-overview", "x-displayName": "概述", "description": "Reward chains encourage users to make purchases in the store using real currency. For each purchase, users earn value points and progress through a reward chain. If users are part of clans, their purchases contribute value points to the entire clan. For detailed information on configuring the reward chains, refer to the [Reward system](https://developers.xsolla.com/zh/liveops/promotion-tools/reward-system/) section.\n\nTo configure reward chains, use API calls from the **Admin** subsection. To display chains and claim rewards, use API calls from the **Client** subsection. To work with clan reward chains, use API calls from the **Clans client** subsection.\n\nExample of reward chain configuration flow:\n\n1. Create items using the API calls from the **Admin** subsection of the [Virtual items and currency](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-overview) or [Bundles](https://developers.xsolla.com/zh/api/catalog/bundles-admin) groups.\n2. Create value points using the [Create value point](https://developers.xsolla.com/zh/api/liveops/reward-chain-value-points-admin/admin-create-value-points) API call.\n3. Assign value points to items using the [Set value points for items](https://developers.xsolla.com/zh/api/liveops/reward-chain-value-points-admin/admin-set-items-value-point-reward) API call. Users receive value points after purchasing these items.\n4. Create a chain using the [Create reward chain](https://developers.xsolla.com/zh/api/liveops/reward-chain-value-points-admin/admin-create-reward-chain) API call. To activate the chain, pass the `is_enabled: true` parameter.\n5. Implement reward chain display. To do this, request the list of available chains using the [Get current user's reward chains](https://developers.xsolla.com/zh/api/liveops/reward-chain-client/get-reward-chains-list) API call. The response contains all active chains with their steps and statuses.\n6. Implement value point balance display. To do this, use the [Get current user's value point balance](https://developers.xsolla.com/zh/api/liveops/reward-chain-client/get-user-reward-chain-balance) API call.\n7. Implement step reward claiming. To do this, use the [Claim step reward](https://developers.xsolla.com/zh/api/liveops/reward-chain-client/claim-user-reward-chain-step-reward) API call.\n8. Configure order status tracking, e.g., using [webhooks](https://developers.xsolla.com/zh/webhooks/section/overview), to promptly receive data on claimed rewards and grant them to the user.\n\n![Reward chain configuration flow](https://cdn.xsolla.net/developers/current/images/api_docs/reward-chains-and-value-points-overview.svg)" }, { "name": "reward-chain-value-points-admin", "x-displayName": "管理" }, { "name": "reward-chain-client", "x-displayName": "客户端" }, { "name": "clan-reward-chain-client", "x-displayName": "公会客户端" }, { "name": "daily-chain-admin", "x-displayName": "管理" }, { "name": "daily-chain-client", "x-displayName": "客户端" }, { "name": "offer-chains-overview", "x-displayName": "概述", "description": "Offer chains are a sequence of steps, each containing an item that users receive for free or purchase as part of an active offer. Offer chains can include exclusive items available only within the chain, as well as items at discounted prices compared to store prices. For detailed information on configuring this marketing tool, refer to the [Offer chains](https://developers.xsolla.com/zh/liveops/promotion-tools/offer-chains/) section.\n\nTo configure offer chains, use API calls from the **Admin** subsection. To display chains and implement the logic for working with items that users receive, use API calls from the **Client** subsection.\n\nExample of offer chain configuration flow:\n\n1. Create items using the API calls from the **Admin** subsection of the [Virtual items and currency](https://developers.xsolla.com/zh/api/catalog/virtual-items-currency-overview) or [Bundles](https://developers.xsolla.com/zh/api/catalog/bundles-admin) groups.\n\n2. Create a chain using the [Create offer chain](https://developers.xsolla.com/zh/api/liveops/offer-chain-admin/admin-create-offer-chain) API call. To activate the chain, pass the `is_enabled: true` parameter.\n\n3. Implement offer chain display. To do this, request the list of available chains using the [Get current user's offer chains](https://developers.xsolla.com/zh/api/liveops/offer-chain-client/get-offer-chains-list) API call. The response contains all active chains with their steps and statuses.\n\n4. Implement the logic for working with items that users receive:\n\n- If the step item is free, use the [Claim free offer chain step](https://developers.xsolla.com/zh/api/liveops/offer-chain-client/claim-user-offer-chain-step-reward) API call. Pass `offer_chain_id` and `step_number` in the request.\n\n- If the step item is paid, use the [Create order for paid offer chain step](https://developers.xsolla.com/zh/api/liveops/offer-chain-client/order-user-offer-chain-step-reward) API call. Pass `offer_chain_id` and `step_number` in the request. The response returns an `order_id` and token to open the payment UI.\n\n5. Configure order status tracking, e.g., using [webhooks](https://developers.xsolla.com/zh/webhooks/section/overview), to promptly receive data on claimed or purchased items and grant them to the user.\n\n![Reward chain configuration flow](https://cdn.xsolla.net/developers/current/images/api_docs/offer-chains-overview.svg)" }, { "name": "offer-chain-admin", "x-displayName": "管理" }, { "name": "offer-chain-client", "x-displayName": "客户端" }, { "name": "upsell-admin", "x-displayName": "管理" }, { "name": "upsell-client", "x-displayName": "客户端" } ], "paths": { "/v3/project/{project_id}/admin/promotion": { "get": { "summary": "获取所有促销活动列表", "description": "获取项目的促销活动列表。", "operationId": "get-promotion-list", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/enabled-query-param" } ], "tags": [ "promotions-common" ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-get-promotions" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" } }, "security": [ { "basicAuth": [] } ] } }, "/v2/project/{project_id}/admin/promotion/{promotion_id}/activate": { "put": { "summary": "激活促销活动", "description": "激活促销活动。", "operationId": "activate-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "security": [ { "basicAuth": [] } ], "tags": [ "promotions-common" ], "responses": { "204": { "description": "Promotion was successfully activated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/Promotions_422-activate-deactivate-promotion" } } } }, "/v2/project/{project_id}/admin/promotion/{promotion_id}/deactivate": { "put": { "summary": "停用促销活动", "description": "停用促销活动。", "operationId": "deactivate-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "security": [ { "basicAuth": [] } ], "tags": [ "promotions-common" ], "responses": { "204": { "description": "Promotion was successfully deactivated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/Promotions_422-activate-deactivate-promotion" } } } }, "/v3/project/{project_id}/admin/promotion/redeemable/code/{code}": { "get": { "summary": "通过代码获取兑换型促销活动", "description": "通过兑换码或优惠券码获取促销活动。", "operationId": "get-redeemable-promotion-by-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/code-path-param" } ], "security": [ { "basicAuth": [] } ], "tags": [ "promotions-common" ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-redeemable-by-code" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-code-not-found" }, "405": { "$ref": "#/components/responses/405-method-not-found" } } } }, "/v2/project/{project_id}/coupon/redeem": { "post": { "summary": "兑换优惠券码", "description": "兑换优惠券码。优惠券兑换后，用户将获得赠品。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "operationId": "redeem-coupon", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "promotions-coupons" ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_redeem-coupon-model" }, "responses": { "200": { "$ref": "#/components/responses/Promotions_200-coupon-redeemed" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "403": { "$ref": "#/components/responses/Promotions_403-auth-header" }, "404": { "$ref": "#/components/responses/Promotions_404-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-redeem-coupon" } }, "security": [ { "XsollaLoginUserJWT": [] } ] } }, "/v2/project/{project_id}/coupon/code/{coupon_code}/rewards": { "get": { "summary": "获取优惠券奖励", "description": "通过优惠券码获取优惠券奖励。可用于允许用户从多个商品中选择一个作为赠品。常见场景是：如果优惠券包含游戏作为赠品(`type=unit`)，则选择DRM。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "operationId": "get-coupon-rewards-by-code", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/coupon_code-path-param" } ], "tags": [ "promotions-coupons" ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-coupon-rewards" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "403": { "$ref": "#/components/responses/Promotions_403-auth-header" }, "404": { "$ref": "#/components/responses/Promotions_404-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-rewards" } }, "security": [ { "XsollaLoginUserJWT": [] } ] } }, "/v3/project/{project_id}/admin/coupon": { "post": { "summary": "创建优惠券促销活动", "description": "创建优惠券促销活动。", "operationId": "admin-create-coupon", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_coupon-create" }, "responses": { "201": { "description": "Coupon was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" } } }, "examples": { "response": { "value": { "external_id": "coupon_external_id" } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/Promotions_422-invalid-coupon" } } }, "get": { "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "operationId": "get-coupons", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取优惠券促销活动列表", "description": "获取项目的优惠券促销活动列表。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-get-coupons" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" } } } }, "/v3/project/{project_id}/admin/coupon/{external_id}": { "put": { "summary": "更新优惠券促销活动", "description": "更新优惠券促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "operationId": "update-coupon-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_coupon-update" }, "responses": { "204": { "description": "Coupon was successfully updated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-invalid-coupon" } } }, "get": { "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "operationId": "get-coupon", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取优惠券促销活动", "description": "获取指定的优惠券促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "responses": { "200": { "description": "Coupon was successfully received.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin-promotions_200-get-coupon-promotion-model" }, "examples": { "response": { "value": { "external_id": "summer20221", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "Coupon name", "ru-RU": "Название купона" }, "is_enabled": true, "bonus": [ { "sku": "com.xsolla.diamonds_1", "quantity": 100 } ], "redeem_user_limit": null, "redeem_total_limit": 100, "redeem_code_limit": null, "total_limit_state": { "available": 50, "reserved": 10, "used": 40 } } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" } } }, "delete": { "summary": "删除优惠券促销活动", "description": "删除[优惠券促销活动](https://developers.xsolla.com/zh/doc/shop-builder/features/coupons/)。删除的促销活动将：\n * 从您项目中设置的促销活动列表中消失。\n* 不再适用于商品目录。用户无法通过该促销活动获得奖励商品。\n\n删除后，该促销活动无法恢复。\n已删除促销活动的优惠券码可以[添加到](https://developers.xsolla.com/zh/api/shop-builder/operation/create-coupon-code/)现有的促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "operationId": "delete-coupon-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "responses": { "204": { "description": "Coupon promotion was successfully deleted." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" } } } }, "/v2/project/{project_id}/admin/coupon/{external_id}/activate": { "put": { "summary": "激活优惠券促销活动", "description": "激活优惠券促销活动。\n默认情况下创建的优惠券促销活动为禁用状态。\n激活之前，不能进行兑换。\n使用此端点启用和激活优惠券促销活动。", "operationId": "activate-coupon", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "responses": { "204": { "description": "Coupon was successfully activated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-error" } } } }, "/v2/project/{project_id}/admin/coupon/{external_id}/deactivate": { "put": { "summary": "停用优惠券促销活动", "description": "停用优惠券促销活动。\n默认情况下创建的优惠券促销活动为禁用状态。\n激活之前，不能进行兑换。\n使用此端点禁用和停用优惠券促销活动。", "operationId": "deactivate-coupon", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "responses": { "204": { "description": "Coupon was successfully deactivated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-error" } } } }, "/v2/project/{project_id}/admin/coupon/{external_id}/code": { "post": { "operationId": "create-coupon-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "创建优惠券码", "description": "创建优惠券码。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_create-coupon-promocode-code" }, "responses": { "201": { "$ref": "#/components/responses/Promotions_201-coupon-promocode-code-created" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-coupon-promocode-same-code-exists" } } }, "get": { "operationId": "get-coupon-codes", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取优惠券码", "description": "Gets coupon codes.\n\nThe response includes the total number of codes in the promotion (`total_count`) and the codes for the current page (`codes`). To fetch the next page, increase the `offset` by the value of `limit` (e.g., `“offset”: 100`, then `“offset”: 200`) until you have retrieved all codes.\n\nIn most cases, `“limit”: 100` or `“limit”: 1000` is sufficient. Reserve larger values such as `“limit”: 10000` for one-time bulk exports, and avoid using `“limit”: 50000` unless necessary.", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-coupon-code-list" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" } } } }, "/v2/project/{project_id}/admin/coupon/{external_id}/code/generate": { "put": { "summary": "生成优惠券码", "description": "Generates coupon codes.\n\nGuidelines on code generation:\n\n* There is no maximum total number of codes per promotion, but each request is limited to 50,000 codes. Requests with a higher count returns a `422 Unprocessable Entity` error. If you need more than 50,000 codes, send multiple requests.\n\n* For better reliability, we recommend generating codes in smaller batches, up to 10,000 per request. E.g., to create 100,000 codes, send 10 requests with `\"count\": 10000` instead of 2 requests with `\"count\": 50000`. Wait for a successful response for each request before sending the next one.\n\n* Keep in mind rate limits that are set to 15 requests per second. When generating large volumes, send requests sequentially to avoid exceeding the rate limit and getting a `429` error.\n\n* To retrieve the list of codes, call the [Get coupon codes](/zh/api/liveops/promotions-coupons/get-coupon-codes) method.\n\n| Parameter | Value |\n|---|---|\n| Minimum number of codes per request. | 1 |\n| Maximum number of codes per request. Use it only when you need the largest possible single batch. | 50,000 |\n| Recommended number of codes per request. | Up to 10,000. If you need to create more, send multiple sequential requests. |", "operationId": "generate-coupon-codes", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/Promotions_coupon-generate-count" } }, "required": [ "count" ] } } } }, "responses": { "200": { "description": "Codes were successfully generated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/Promotions_coupon-generate-count" } } }, "examples": { "response": { "value": { "count": 10 } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" } } } }, "/v2/project/{project_id}/promocode/redeem": { "post": { "summary": "核销兑换码", "description": "核销兑换码促销活动的兑换码。\n核销兑换码后，用户将获得免费商品，和/或购物车或特定商品的价格将降低。", "operationId": "redeem-promo-code", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "promotions-promo-codes" ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_redeem-promo-code-model" }, "responses": { "200": { "$ref": "#/components/responses/Promotions_200-promo-code-redeemed" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "403": { "$ref": "#/components/responses/Promotions_403-auth-header" }, "404": { "$ref": "#/components/responses/Promotions_404-promo-code" }, "422": { "$ref": "#/components/responses/Promotions_422-redeem-coupon" } }, "security": [ { "AuthForCart": [] } ] } }, "/v2/project/{project_id}/promocode/remove": { "put": { "summary": "从购物车中移除兑换码", "description": "从购物车中移除兑换码。\n移除兑换码后，系统会重新计算购物车中所有商品的总价，且不再包含该兑换码提供的赠品和折扣。", "operationId": "remove-cart-promo-code", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "promotions-promo-codes" ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_cancel-promo-code-model" }, "responses": { "200": { "$ref": "#/components/responses/Promotions_200-promo-code-canceled" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "403": { "$ref": "#/components/responses/Promotions_403-auth-header" }, "422": { "$ref": "#/components/responses/Promotions_422-cancel-promo-code" } }, "security": [ { "AuthForCart": [] } ] } }, "/v2/project/{project_id}/promocode/code/{promocode_code}/rewards": { "get": { "summary": "获取兑换码奖励", "description": "通过兑换码获取兑换码奖励。可用于允许用户从多个商品中选择一个作为赠品。常见场景是：如果兑换码包含游戏作为赠品(`type=unit`)，则选择DRM。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "operationId": "get-promo-code-rewards-by-code", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promocode_code-path-param" } ], "tags": [ "promotions-promo-codes" ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-promocode-rewards" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "403": { "$ref": "#/components/responses/Promotions_403-auth-header" }, "404": { "$ref": "#/components/responses/Promotions_404-promo-code" }, "422": { "$ref": "#/components/responses/Promotions_422-rewards" } }, "security": [ { "XsollaLoginUserJWT": [] } ] } }, "/v3/project/{project_id}/admin/promocode": { "post": { "operationId": "create-promo-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "创建兑换码促销活动", "description": "创建兑换码促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_promocode-create" }, "responses": { "201": { "description": "Promo code was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" } } }, "examples": { "response": { "value": { "external_id": "coupon_external_id" } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/Promotions_422-invalid-coupon" } } }, "get": { "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "operationId": "get-promo-codes", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取兑换码促销活动列表", "description": "获取项目的兑换码列表。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-get-promocodes" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" } } } }, "/v3/project/{project_id}/admin/promocode/{external_id}": { "put": { "summary": "更新兑换码促销活动", "description": "更新兑换码促销活动。", "operationId": "update-promo-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_promocode-update" }, "responses": { "204": { "description": "Promo code was successfully updated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" }, "422": { "$ref": "#/components/responses/Promotions_422-invalid-coupon" } } }, "get": { "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "operationId": "get-promo-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取兑换码促销活动", "description": "获取指定的兑换码促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "responses": { "200": { "description": "Promo code was successfully received.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Promotions_200-get-promocode-promotion-model" }, "examples": { "simple": { "value": { "external_id": "summer20221", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "Coupon name", "ru-RU": "Название купона" }, "is_enabled": true, "bonus": [ { "sku": "com.xsolla.diamonds_1", "quantity": 100 } ], "redeem_user_limit": null, "redeem_total_limit": 100, "redeem_code_limit": 1, "discount": { "percent": "10.99" }, "discounted_items": null, "total_limit_state": { "available": 50, "reserved": 10, "used": 40 }, "excluded_promotions": [ 23, 45 ] } }, "with price conditions": { "value": { "external_id": "summer20221", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "Coupon name", "ru-RU": "Название купона" }, "is_enabled": true, "bonus": [ { "sku": "com.xsolla.diamonds_2", "quantity": 100 } ], "redeem_user_limit": null, "redeem_total_limit": 100, "redeem_code_limit": 1, "discount": { "percent": "10.99" }, "discounted_items": null, "total_limit_state": { "available": 50, "reserved": 10, "used": 40 }, "price_conditions": [ { "operator": "gt", "value": "10.0000" }, { "operator": "lt", "value": "50.0000" } ] } }, "with item price conditions": { "value": { "external_id": "summer20221", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "Coupon name", "ru-RU": "Название купона" }, "is_enabled": true, "bonus": [ { "sku": "com.xsolla.diamonds_3", "quantity": 100 } ], "redeem_user_limit": null, "redeem_total_limit": 100, "redeem_code_limit": 1, "discount": { "percent": "10.99" }, "discounted_items": null, "total_limit_state": { "available": 50, "reserved": 10, "used": 40 }, "item_price_conditions": [ { "operator": "gt", "value": "10.0000" }, { "operator": "lt", "value": "50.0000" } ], "excluded_promotions": [ 23, 45 ] } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" } } }, "delete": { "summary": "删除兑换码促销活动", "description": "删除[兑换码促销活动](https://developers.xsolla.com/zh/doc/shop-builder/features/promo-codes/)。删除的促销活动将：\n * 从您项目中设置的促销活动列表中消失。\n * 不再应用于商品目录和购物车。用户无法通过该促销活动获得赠品或购买商品。\n\n删除后，该促销活动无法恢复。\n已删除促销活动的兑换码可以[添加到](https://developers.xsolla.com/zh/api/shop-builder/operation/create-promo-code-code/)现有促销活动。", "operationId": "delete-promo-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "responses": { "204": { "description": "Promo code promotion was successfully deleted." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" } } } }, "/v2/project/{project_id}/admin/promocode/{external_id}/activate": { "put": { "summary": "激活兑换码促销活动", "description": "激活兑换码促销活动。\n\n默认情况下创建的兑换码促销活动为禁用状态。\n激活前，兑换码无法被核销。\n使用此接口启用并激活兑换码促销活动。", "operationId": "activate-promo-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "responses": { "204": { "description": "Promo code was successfully activated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-error" } } } }, "/v2/project/{project_id}/admin/promocode/{external_id}/deactivate": { "put": { "summary": "停用兑换码促销活动", "description": "停用兑换码促销活动。\n\n默认情况下创建的兑换码促销活动为禁用状态。\n激活前，兑换码无法被核销。\n使用此接口禁用并停用兑换码促销活动。", "operationId": "deactivate-promo-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "responses": { "204": { "description": "Coupon was successfully deactivated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-error" } } } }, "/v2/project/{project_id}/admin/promocode/{external_id}/code": { "post": { "operationId": "create-promo-code-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "为兑换码促销活动创建兑换码", "description": "为兑换码促销活动创建兑换码。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_create-coupon-promocode-code" }, "responses": { "201": { "$ref": "#/components/responses/Promotions_201-coupon-promocode-code-created" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" }, "422": { "$ref": "#/components/responses/Promotions_422-coupon-promocode-same-code-exists" } } }, "get": { "operationId": "get-promocode-codes", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取兑换码促销活动的兑换码", "description": "Gets codes of a promo code promotion.\n\nThe response includes the total number of codes in the promotion (`total_count`) and the codes for the current page (`codes`). To fetch the next page, increase the `offset` by the value of `limit` (e.g., `“offset”: 100`, then `“offset”: 200`) until you have retrieved all codes.\n\nIn most cases, `“limit”: 100` or `“limit”: 1000` is sufficient. Reserve larger values such as `“limit”: 10000` for one-time bulk exports, and avoid using `“limit”: 50000` unless necessary.", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-promocode-code-list" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" } } } }, "/v2/project/{project_id}/admin/promocode/{external_id}/code/generate": { "put": { "summary": "为兑换码促销活动生成兑换码", "description": "Generates codes for a promo code promotion.\n\nGuidelines on code generation:\n\n* There is no maximum total number of codes per promotion, but each request is limited to 50,000 codes. Requests with a higher count returns a `422 Unprocessable Entity` error. If you need more than 50,000 codes, send multiple requests.\n\n* For better reliability, we recommend generating codes in smaller batches, up to 10,000 per request. E.g., to create 100,000 codes, send 10 requests with `\"count\": 10000` instead of 2 requests with `\"count\": 50000`. Wait for a successful response for each request before sending the next one.\n\n* Keep in mind rate limits that are set to 15 requests per second. When generating large volumes, send requests sequentially to avoid exceeding the rate limit and getting a `429` error.\n\n* To retrieve the list of codes, call the [Get codes of promo code promotion](/zh/api/liveops/promotions-promo-codes/get-promocode-codes) method.\n\n| Parameter | Value |\n|---|---|\n| Minimum number of codes per request. | 1 |\n| Maximum number of codes per request. Use it only when you need the largest possible single batch. | 50,000 |\n| Recommended number of codes per request. | Up to 10,000. If you need to create more, send multiple sequential requests. |", "operationId": "generate-promo-code-codes", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/Promotions_coupon-generate-count" } }, "required": [ "count" ] } } } }, "responses": { "200": { "description": "Codes were successfully generated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/Promotions_coupon-generate-count" } } }, "examples": { "response": { "value": { "count": 10 } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" } } } }, "/v3/project/{project_id}/admin/promotion/item": { "post": { "summary": "为商品创建折扣促销活动", "description": "为商品创建折扣促销活动。\n\n促销活动提供商品折扣(%)。\n折扣应用于指定商品的所有价格。", "operationId": "create-item-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "promotions-discounts" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_create-update-item-promotion" }, "responses": { "201": { "$ref": "#/components/responses/Promotions_201-create-promotion" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-missed-items-property" } } }, "get": { "tags": [ "promotions-discounts" ], "security": [ { "basicAuth": [] } ], "operationId": "get-item-promotion-list", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取商品促销活动列表", "description": "获取项目的商品促销列表。\n\n促销活动提供商品折扣(%)。\n折扣应用于指定商品的所有价格。", "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "项目ID。", "schema": { "type": "integer", "default": 59080 } }, { "name": "limit", "in": "query", "required": false, "description": "页面上元素数量的限制。", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "required": false, "description": "生成列表时作为起始位置的元素编号（从0开始计数）。", "schema": { "type": "integer" } } ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-get-item-promotions" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" } } } }, "/v3/project/{project_id}/admin/promotion/{promotion_id}/item": { "put": { "tags": [ "promotions-discounts" ], "security": [ { "basicAuth": [] } ], "operationId": "update-item-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "更新商品促销活动", "description": "更新促销活动。\n\n
注：

新数据将替换旧数据。如果只想更新促销活动的一部分，也需要在请求中传入所有必需数据。
\n\n促销活动提供商品折扣(%)。\n折扣应用于指定商品的所有价格。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "responses": { "204": { "description": "Promotion was successfully updated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promotion" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-missed-items-property" } }, "requestBody": { "$ref": "#/components/requestBodies/Promotions_create-update-item-promotion" } }, "get": { "tags": [ "promotions-discounts" ], "security": [ { "basicAuth": [] } ], "operationId": "get-item-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "summary": "获取商品促销活动", "description": "获取应用于特定商品的促销活动。\n\n促销活动提供商品折扣(%)。\n折扣应用于指定商品的所有价格。", "responses": { "200": { "description": "Item promotion was successfully received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "促销活动ID。项目内的唯一促销活动标识符。" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "is_enabled": { "$ref": "#/components/schemas/Promotions_is_enabled" }, "name": { "type": "object", "description": "促销活动名称。应包含键/值对，\n其中键是格式为\"^[a-z]{2}-[A-Z]{2}$\"的区域设置，值是字符串。", "additionalProperties": { "type": "string", "example": { "en-US": "Promotion", "ru-RU": "Акция" } } }, "discount": { "type": "object", "properties": { "percent": { "type": [ "string", "null" ], "description": "百分比折扣。\n商品价格使用此百分比计算打折价格。", "default": "10.00" } } }, "items": { "type": [ "array", "null" ], "items": { "description": "适用折扣的商品列表。", "type": "object", "properties": { "sku": { "type": "string", "description": "商品SKU。", "default": "elven_sword" } } } }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-get" }, "limits": { "$ref": "#/components/schemas/Promotions_promotion_limits_response" }, "price_conditions": { "$ref": "#/components/schemas/price_conditions_discount" }, "excluded_promotions": { "$ref": "#/components/schemas/excluded_promotions" } }, "example": { "id": 1, "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "is_enabled": true, "discount": { "percent": "15.00" }, "items": [ { "sku": "com.xsolla.elven_sword_1" }, { "sku": "com.xsolla.elven_helmet_1" }, { "sku": "com.xsolla.elven_armor_1" } ], "name": { "en-US": "Promotion", "ru-RU": "Акция" } } }, "examples": { "response": { "value": { "id": 1, "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "is_enabled": true, "discount": { "percent": "20.00" }, "items": [ { "sku": "com.xsolla.elven_helmet_1" }, { "sku": "com.xsolla.elven_armor_1" } ], "name": { "en-US": "Promotion", "ru-RU": "Акция" }, "limits": { "per_user": { "total": 10 }, "per_item": null, "recurrent_schedule": { "per_user": { "interval_type": "daily", "day_of_week": null, "day_of_month": null, "time": "11:00:00+08:00", "reset_next_date": 1677553200, "displayable_reset_start_date": "2023-02-28T11:00:00+08:00", "displayable_reset_next_date": "2023-02-28T11:00:00+08:00" } } }, "price_conditions": [ { "operator": "ge", "value": "10.0000" }, { "operator": "le", "value": "50.0000" } ], "excluded_promotions": [ 23, 45 ] } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "description": "未找到促销活动。请确保`promotion_id`正确无误。", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 9502 }, "errorMessage": { "type": "string", "example": "[0401-9502]: Can not find promotion with ID = 111425 in project 59080" } }, "type": "object" }, "examples": { "response": { "value": { "statusCode": 404, "errorCode": 9502, "errorMessage": "[0401-9502]: Can not find promotion with ID = 111425 in project 59080" } } } } } } } }, "delete": { "summary": "删除商品促销活动", "tags": [ "promotions-discounts" ], "security": [ { "basicAuth": [] } ], "operationId": "delete-item-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "description": "删除[折扣促销活动](https://developers.xsolla.com/zh/doc/shop-builder/features/discounts/)。删除的促销活动将：\n * 从您项目中设置的促销活动列表中消失。\n* 不再适用于商品目录和购物车。用户无法通过该促销活动购买商品。\n\n删除后，该促销活动无法恢复。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "responses": { "204": { "description": "Promotion was successfully deleted." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promotion" } } } }, "/v3/project/{project_id}/admin/promotion/bonus": { "post": { "summary": "创建买赠促销活动", "description": "创建买赠促销活动。\n\n促销活动会在用户购买时赠送免费赠品。\n该促销活动可应用于项目中的任意购买，也可应用于包含特定商品的购买。", "operationId": "create-bonus-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "promotions-bonuses" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_create-update-bonus-promotion" }, "responses": { "201": { "$ref": "#/components/responses/Promotions_201-create-promotion" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-missed-bonus-property" } } }, "get": { "tags": [ "promotions-bonuses" ], "security": [ { "basicAuth": [] } ], "operationId": "get-bonus-promotion-list", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取买赠促销活动列表", "description": "获取项目的买赠促销活动列表。\n\n促销活动会在用户购买时赠送免费赠品。\n该促销活动可应用于项目中的任意购买，也可应用于包含特定商品的购买。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-get-bonus-promotions" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" } } } }, "/v3/project/{project_id}/admin/promotion/{promotion_id}/bonus": { "put": { "summary": "更新买赠促销活动", "description": "更新促销活动。\n\n
注：

新数据将替换旧数据。如果只想更新促销活动的一部分，也需要在请求中传入所有必需数据。
\n\n促销活动会在用户购买时赠送免费赠品。\n该促销活动可应用于项目中的任意购买，也可应用于包含特定商品的购买。", "operationId": "update-bonus-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "tags": [ "promotions-bonuses" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_create-update-bonus-promotion" }, "responses": { "204": { "description": "Promotion was successfully updated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-missed-bonus-property" } } }, "get": { "tags": [ "promotions-bonuses" ], "security": [ { "basicAuth": [] } ], "operationId": "get-bonus-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取买赠促销活动", "description": "获取买赠促销活动。\n\n促销活动会在用户购买时赠送免费赠品。\n该促销活动可应用于项目中的任意购买，也可应用于包含特定商品的购买。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-admin-get-bonus-promotion" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promotion" } } }, "delete": { "summary": "删除买赠促销活动", "tags": [ "promotions-bonuses" ], "security": [ { "basicAuth": [] } ], "operationId": "delete-bonus-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "description": "删除[买赠促销活动](https://developers.xsolla.com/zh/doc/shop-builder/features/bonuses/)。删除的促销活动将：\n * 从您项目中设置的促销活动列表中消。失\n * 不再应用于商品目录和购物车。用户无法通过该促销活动获得赠品。\n\n删除后，该促销活动无法恢复。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "responses": { "204": { "description": "Promotion was successfully deleted." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promotion" } } } }, "/v2/project/{project_id}/promotion/code/{code}/verify": { "get": { "summary": "验证促销代码", "description": "确定代码是兑换码还是优惠券码，以及用户是否可以使用该代码。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "operationId": "verify-promotion-code", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/code-path-param" } ], "tags": [ "promotions-common" ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-verify-promo-code" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "403": { "$ref": "#/components/responses/Promotions_403-auth-header" }, "404": { "$ref": "#/components/responses/Promotions_404-verify-promo-code" }, "422": { "$ref": "#/components/responses/Promotions_422-verify-promo-code" } } } }, "/v3/project/{project_id}/admin/unique_catalog_offer": { "post": { "operationId": "admin-create-unique-catalog-offer", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "创建专属商品目录优惠促销活动", "description": "创建专属商品目录优惠促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_unique_catalog_offer-create" }, "responses": { "201": { "description": "Unique catalog offer was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" } } }, "examples": { "response": { "value": { "external_id": "coupon_external_id" } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/Promotions_422-invalid-coupon" } } }, "get": { "operationId": "get-unique-catalog-offers", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "summary": "获取专属商品目录优惠促销活动列表", "description": "获取项目的专属商品目录优惠促销活动列表。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-get-unique-catalog-offers" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" } } } }, "/v3/project/{project_id}/admin/unique_catalog_offer/{external_id}": { "put": { "operationId": "update-unique-catalog-offer-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "更新专属商品目录优惠促销活动", "description": "更新专属商品目录优惠促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_unique_catalog_offer-update" }, "responses": { "204": { "description": "Unique catalog offer was successfully updated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-invalid-coupon" } } }, "get": { "operationId": "get-unique-catalog-offer", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "summary": "获取专属商品目录优惠促销活动", "description": "获取指定的专属商品目录优惠促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "responses": { "200": { "description": "Unique catalog offer was successfully received.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Promotions_200-get-unique-catalog-offer-promotion-model" }, "examples": { "response": { "value": { "external_id": "secret_shop", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "Secret shop", "ru-RU": "Секретный магазин" }, "items": [ "helmet", "sword", "shield" ], "is_enabled": true, "redeem_user_limit": 1, "redeem_total_limit": 100, "redeem_code_limit": 1, "total_limit_state": { "available": 50, "reserved": 10, "used": 40 } } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" } } }, "delete": { "operationId": "delete-unique-catalog-offer-promotion", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "删除专属商品目录优惠促销活动", "description": "删除[专属商品目录优惠促销活动](https://developers.xsolla.com/zh/doc/shop-builder/features/unique-offer/)。删除的促销活动将：\n * 从您项目中设置的促销活动列表中消失。\n * 不再应用于商品目录和购物车。用户无法通过该促销活动购买商品。\n\n删除后，该促销活动无法恢复。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "responses": { "204": { "description": "Unique catalog offer was successfully deleted." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" } } } }, "/v2/project/{project_id}/admin/unique_catalog_offer/{external_id}/activate": { "put": { "operationId": "activate-unique-catalog-offer", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "激活专属商品目录优惠促销活动", "description": "激活专属商品目录优惠促销活动。\n默认情况下，创建的专属商品目录优惠促销活动为禁用状态。\n激活前，该促销活动无法进行核销。\n使用此接口启用并激活专属商品目录优惠促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "responses": { "204": { "description": "Unique catalog offer was successfully activated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-error" } } } }, "/v2/project/{project_id}/admin/unique_catalog_offer/{external_id}/deactivate": { "put": { "operationId": "deactivate-unique-catalog-offer", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "停用专属商品目录优惠促销活动", "description": "停用专属商品目录优惠促销活动。\n默认情况下，创建的专属商品目录优惠促销活动为禁用状态。\n激活前，该促销活动无法进行核销。\n使用此接口禁用并停用专属商品目录优惠促销活动。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "responses": { "204": { "description": "Unique catalog offer was successfully deactivated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-admin-promotion-error" } } } }, "/v2/project/{project_id}/admin/unique_catalog_offer/{external_id}/code": { "post": { "operationId": "create-unique-catalog-offer-code", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "创建专属商品目录优惠代码", "description": "创建专属商品目录优惠代码。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/Promotions_create-coupon-promocode-code" }, "responses": { "201": { "$ref": "#/components/responses/Promotions_201-coupon-promocode-code-created" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" }, "422": { "$ref": "#/components/responses/Promotions_422-coupon-promocode-same-code-exists" } } }, "get": { "operationId": "get-unique-catalog-offer-codes", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "获取专属商品目录优惠代码", "description": "获取专属商品目录优惠代码。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/Promotions_200-unique-catalog-offer-code-list" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-coupon" } } } }, "/v2/project/{project_id}/admin/unique_catalog_offer/{external_id}/code/generate": { "put": { "operationId": "generate-unique-catalog-offer-codes", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "summary": "生成专属商品目录优惠代码", "description": "生成专属商品目录优惠代码。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" } ], "tags": [ "promotions-unique-catalog-offers" ], "security": [ { "basicAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/Promotions_coupon-generate-count" } }, "required": [ "count" ] } } } }, "responses": { "200": { "description": "The codes were successfully generated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "$ref": "#/components/schemas/Promotions_coupon-generate-count" } } }, "examples": { "response": { "value": { "count": 10 } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/Promotions_404-admin-promocode" } } } }, "/v2/project/{project_id}/admin/user/limit/promocode/external_id/{external_id}": { "get": { "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "operationId": "get-promo-code-user-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" }, { "$ref": "#/components/parameters/user_external_id-query-param" } ], "summary": "获取指定用户的兑换码使用限制", "description": "获取指定用户可使用该兑换码的剩余次数。\n\n用户限制API可用于限制用户使用兑换码的次数。如需配置用户限制本身，请前往“管理”部分：\n* [兑换码](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-promo-codes/)", "responses": { "200": { "$ref": "#/components/responses/200-admin-get-user-promo-code-limits" }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "Promo code not found": { "$ref": "#/components/examples/404-coupon-not-found" }, "User not found": { "$ref": "#/components/examples/404-user-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" }, "transactionId": { "type": "string" } } }, "examples": { "Invalid user_external_id": { "$ref": "#/components/examples/Promotions_422-invalid-coupon" } } } } } } } }, "/v2/project/{project_id}/admin/user/limit/coupon/external_id/{external_id}": { "get": { "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "operationId": "get-coupon-user-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" }, { "$ref": "#/components/parameters/user_external_id-query-param" } ], "summary": "获取指定用户的优惠券限制", "description": "获取指定用户可以使用优惠券的剩余次数。\n\n用户限制API允许您限制用户可以使用优惠券的次数。要配置用户限制数本身，请前往“管理”部分：\n* [优惠券](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-coupons/)", "responses": { "200": { "$ref": "#/components/responses/200-admin-get-user-coupon-limits" }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "Coupon not found": { "$ref": "#/components/examples/404-coupon-not-found" }, "User not found": { "$ref": "#/components/examples/404-user-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" }, "transactionId": { "type": "string" } } }, "examples": { "Invalid user_external_id": { "$ref": "#/components/examples/Promotions_422-invalid-coupon" } } } } } } } }, "/v2/project/{project_id}/admin/code/limit/promocode/external_id/{external_id}": { "get": { "tags": [ "promotions-promo-codes" ], "security": [ { "basicAuth": [] } ], "operationId": "get-promo-code-code-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" }, { "$ref": "#/components/parameters/codes-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "summary": "获取代码的兑换码使用限制", "description": "获取代码可以使用的剩余次数。要筛选代码，请使用`codes`查询参数。\n\n要配置代码限制本身，请前往“管理”部分：\n *[兑换码](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-promo-codes/)", "responses": { "200": { "$ref": "#/components/responses/200-admin-get-code-promo-code-limits" }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "Promo code not found": { "$ref": "#/components/examples/404-coupon-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" } } } } } } } } }, "/v2/project/{project_id}/admin/code/limit/coupon/external_id/{external_id}": { "get": { "tags": [ "promotions-coupons" ], "security": [ { "basicAuth": [] } ], "operationId": "get-coupon-code-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/external_id-promotion-path-param" }, { "$ref": "#/components/parameters/codes-query-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "summary": "获取唯一优惠券码限制", "description": "获取代码可以使用的剩余次数。要筛选代码，请使用`codes`查询参数。\n\n要配置代码限制本身，请前往“管理”部分：\n *[优惠券](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-coupons/)", "responses": { "200": { "$ref": "#/components/responses/200-admin-get-code-coupon-limits" }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "Coupon not found": { "$ref": "#/components/examples/404-coupon-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" } } } } } } } } }, "/v2/project/{project_id}/admin/user/attribute/rule": { "get": { "tags": [ "personalized-catalog" ], "security": [ { "basicAuth": [] } ], "operationId": "get-filter-rules", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/is_enabled-query-param" } ], "summary": "获取商品目录筛选规则列表", "description": "获取应用于用户属性的所有规则。", "responses": { "200": { "description": "Rules were successfully received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/user-attribute_personalized-catalog" } }, "total_items_count": { "type": "number", "description": "Total number of rules." }, "has_more": { "type": "boolean", "description": "If another page with rules exists." } } }, "examples": { "response": { "value": { "items": [ { "rule_id": 1, "name": "Ork race armor rule", "is_enabled": true, "is_satisfied_for_unauth": false, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "ork", "type": "string", "can_be_missing": false } ], "items": [ { "item_id": 1, "sku": "com.xsolla.ork_armor_1", "name": "Ork Armor", "type": "virtual_good" }, { "item_id": 2, "sku": "com.xsolla.potion_pack_1", "name": "Potion pack", "type": "bundle", "bundle_type": "standard" } ] } ], "total_items_count": 20, "has_more": true } } } } } }, "401": { "$ref": "#/components/responses/Common_401-complex" }, "403": { "$ref": "#/components/responses/403-auth-header-not-sent" } } }, "post": { "tags": [ "personalized-catalog" ], "security": [ { "basicAuth": [] } ], "operationId": "create-filter-rule", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "summary": "创建商品目录筛选规则", "description": "创建用户属性的规则。", "responses": { "201": { "description": "Rule was successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule_id": { "type": "number", "description": "规则ID。" } } }, "examples": { "response": { "value": { "rule_id": 1 } } } } } }, "401": { "$ref": "#/components/responses/Common_401-complex" }, "422": { "$ref": "#/components/responses/Common_422-body-validation" } }, "requestBody": { "$ref": "#/components/requestBodies/personalized-catalog_create-update-body" } } }, "/v2/project/{project_id}/admin/user/attribute/rule/all": { "get": { "tags": [ "personalized-catalog" ], "security": [ { "basicAuth": [] } ], "operationId": "get-all-filter-rules", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "summary": "获取用于客户端侧搜索的所有商品目录规则", "description": "获取用于在客户端侧搜索的所有商品目录规则列表。\n\n
Attention

Returns only rule id, name and is_enabled
", "responses": { "200": { "description": "Rules were successfully received.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/user-attribute_personalized-catalog_all" } } } }, "examples": { "response": { "value": { "items": [ { "rule_id": 1, "name": "Ork race armor rule", "is_enabled": true, "is_satisfied_for_unauth": false }, { "rule_id": 2, "name": "Age", "is_enabled": false, "is_satisfied_for_unauth": false } ] } } } } } }, "401": { "$ref": "#/components/responses/Common_401-complex" }, "403": { "$ref": "#/components/responses/403-auth-header-not-sent" } } } }, "/v2/project/{project_id}/admin/user/attribute/rule/{rule_id}": { "get": { "tags": [ "personalized-catalog" ], "security": [ { "basicAuth": [] } ], "operationId": "get-filter-rule-by-id", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/personalized-catalog-rule_id-path-param" } ], "summary": "获取商品目录筛选规则", "description": "获取应用于用户属性的指定规则。", "responses": { "200": { "description": "Rule was successfuly recieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-attribute_personalized-catalog" }, "examples": { "response": { "value": { "rule_id": 1, "name": "Ork race armor rule", "is_enabled": true, "is_satisfied_for_unauth": true, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "ork", "type": "string", "can_be_missing": false } ], "items": [ { "item_id": 1, "sku": "com.xsolla.ork_armor_1", "name": "Ork Armor" } ] } } } } } }, "401": { "$ref": "#/components/responses/Common_401-complex" } } }, "put": { "tags": [ "personalized-catalog" ], "security": [ { "basicAuth": [] } ], "operationId": "update-filter-rule-by-id", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/personalized-catalog-rule_id-path-param" } ], "summary": "更新商品目录筛选规则", "description": "更新应用于用户属性的指定规则。默认值将用于未指定的属性（如果属性非必需）。", "responses": { "204": { "description": "Successful update." }, "401": { "$ref": "#/components/responses/Common_401-complex" }, "422": { "$ref": "#/components/responses/Common_422-body-validation" } }, "requestBody": { "$ref": "#/components/requestBodies/personalized-catalog_create-update-body" } }, "patch": { "tags": [ "personalized-catalog" ], "security": [ { "basicAuth": [] } ], "operationId": "patch-filter-rule-by-id", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/personalized-catalog-rule_id-path-param" } ], "summary": "部分更新商品目录筛选规则", "description": "更新应用于用户属性的指定规则。当前值将用于未指定的属性。", "responses": { "204": { "description": "Update was successful." }, "401": { "$ref": "#/components/responses/Common_401-complex" }, "422": { "$ref": "#/components/responses/Common_422-body-validation" } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-attribute_personalized-catalog-body" }, "example": { "is_enabled": false } } } } }, "delete": { "tags": [ "personalized-catalog" ], "security": [ { "basicAuth": [] } ], "operationId": "delete-filter-rule-by-id", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/personalized-catalog-rule_id-path-param" } ], "summary": "删除商品目录筛选规则", "description": "删除指定规则。", "responses": { "204": { "description": "Delete was successful." }, "401": { "$ref": "#/components/responses/Common_401-complex" } } } }, "/v2/project/{project_id}/admin/user/limit/promotion/all": { "delete": { "tags": [ "user-limits-admin" ], "security": [ { "basicAuth": [] } ], "operationId": "reset-all-user-promotions-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "summary": "刷新指定用户的所有促销活动限制", "description": "刷新指定用户所有促销活动的所有限制，以便其可以再次使用这些促销活动。\n\n用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：\n* [折扣促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-discounts/)\n* [买赠促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-bonuses/)", "responses": { "200": { "description": "The promotion limit was successfully refreshed." }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "User not found": { "$ref": "#/components/examples/404-user-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" }, "transactionId": { "type": "string" } } }, "examples": { "Invalid user_external_id": { "$ref": "#/components/examples/422-user_external_id_invalid" } } } } } }, "requestBody": { "$ref": "#/components/requestBodies/reset-user-limits" } } }, "/v2/project/{project_id}/admin/user/limit/promotion/id/{promotion_id}/all": { "delete": { "tags": [ "user-limits-admin" ], "security": [ { "basicAuth": [] } ], "operationId": "reset-user-promotion-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "summary": "刷新用户的促销活动限制", "description": "刷新促销活动限制以便用户可以再次使用该促销活动。如果*user*参数为`null`，此调用将刷新所有用户的此限制。\n\n用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：\n* [折扣促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-discounts/)\n* [买赠促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-bonuses/)", "responses": { "200": { "description": "The promotion limit was successfully refreshed." }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "Item not found": { "$ref": "#/components/examples/404-promotion-by-id-not-found" }, "User not found": { "$ref": "#/components/examples/404-user-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" }, "transactionId": { "type": "string" } } }, "examples": { "Invalid user_external_id": { "$ref": "#/components/examples/422-user_external_id_invalid" }, "Promotion does not have configured user limits": { "$ref": "#/components/examples/422-promotion-without-user-limit" } } } } } }, "requestBody": { "$ref": "#/components/requestBodies/reset-user-limits-flexible" } } }, "/v2/project/{project_id}/admin/user/limit/promotion/id/{promotion_id}": { "get": { "tags": [ "user-limits-admin" ], "security": [ { "basicAuth": [] } ], "operationId": "get-user-promotion-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" }, { "$ref": "#/components/parameters/user_external_id-query-param" } ], "summary": "获取指定用户的促销活动限制", "description": "获取指定用户在应用的限制内可以使用促销活动的剩余次数。\n\n用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：\n* [折扣促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-discounts/)\n* [买赠促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-bonuses/)", "responses": { "200": { "$ref": "#/components/responses/200-admin-get-user-promotion-limits" }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "Item not found": { "$ref": "#/components/examples/404-promotion-by-id-not-found" }, "User not found": { "$ref": "#/components/examples/404-user-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" }, "transactionId": { "type": "string" } } }, "examples": { "Invalid user_external_id": { "$ref": "#/components/examples/422-user_external_id_invalid" }, "Promotion does not have configured user limits": { "$ref": "#/components/examples/422-promotion-without-user-limit" } } } } } } }, "post": { "tags": [ "user-limits-admin" ], "security": [ { "basicAuth": [] } ], "operationId": "add-user-promotion-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "summary": "增加指定用户的促销活动限制", "description": "增加指定用户在应用的限制内可以使用促销活动的剩余次数。\n\n用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：\n* [折扣促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-discounts/)\n* [买赠促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-bonuses/)", "responses": { "200": { "$ref": "#/components/responses/200-admin-get-user-promotion-limits" }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "Item not found": { "$ref": "#/components/examples/404-promotion-by-id-not-found" }, "User not found": { "$ref": "#/components/examples/404-user-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" }, "transactionId": { "type": "string" } } }, "examples": { "Invalid user_external_id": { "$ref": "#/components/examples/422-user_external_id_invalid" }, "Promotion does not have configured user limits": { "$ref": "#/components/examples/422-promotion-without-user-limit" }, "Available promotion limit is out of range": { "$ref": "#/components/examples/422-promotion-out-of-range-available-user-limit" } } } } } }, "requestBody": { "$ref": "#/components/requestBodies/update-user-limits-strict" } }, "put": { "tags": [ "user-limits-admin" ], "security": [ { "basicAuth": [] } ], "operationId": "set-user-promotion-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "summary": "设置指定用户的促销活动限制", "description": "在增加或减少次数后设置指定用户在应用的限制内可以使用促销活动的次数。\n\n用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：\n* [折扣促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-discounts/)\n* [买赠促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-bonuses/)", "responses": { "200": { "$ref": "#/components/responses/200-admin-get-user-promotion-limits" }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "Item not found": { "$ref": "#/components/examples/404-promotion-by-id-not-found" }, "User not found": { "$ref": "#/components/examples/404-user-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" }, "transactionId": { "type": "string" } } }, "examples": { "Invalid user_external_id": { "$ref": "#/components/examples/422-user_external_id_invalid" }, "Promotion does not have configured user limits": { "$ref": "#/components/examples/422-promotion-without-user-limit" } } } } } }, "requestBody": { "$ref": "#/components/requestBodies/update-user-limits-flexible" } }, "delete": { "tags": [ "user-limits-admin" ], "security": [ { "basicAuth": [] } ], "operationId": "remove-user-promotion-limit", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/promotion_id-path-param" } ], "summary": "减少指定用户的促销活动限制", "description": "Decreases the remaining number of times the specified user can use a promotion within the limit applied.\n\n用户限制API可用于限制用户使用促销活动的次数。如需配置用户限制，请前往所需促销活动类型的“管理”部分：\n* [折扣促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-discounts/)\n* [买赠促销活动](https://developers.xsolla.com/zh/api/shop-builder/tag/promotions-bonuses/)", "responses": { "200": { "$ref": "#/components/responses/200-admin-get-user-promotion-limits" }, "401": { "$ref": "#/components/responses/Common_401-invalid-basic-auth" }, "404": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "transactionId": { "type": "string" } } }, "examples": { "Item not found": { "$ref": "#/components/examples/404-promotion-by-id-not-found" }, "User not found": { "$ref": "#/components/examples/404-user-not-found" } } } } }, "422": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer" }, "errorCode": { "type": "integer" }, "errorMessage": { "type": "string" }, "errorMessageExtended": { "type": "array" }, "transactionId": { "type": "string" } } }, "examples": { "Invalid user_external_id": { "$ref": "#/components/examples/422-user_external_id_invalid" }, "Promotion does not have configured user limits": { "$ref": "#/components/examples/422-promotion-without-user-limit" }, "Available promotion limit is out of range": { "$ref": "#/components/examples/422-promotion-out-of-range-available-user-limit" } } } } } }, "requestBody": { "$ref": "#/components/requestBodies/update-user-limits-strict" } } }, "/v2/project/{project_id}/admin/items/value_points": { "get": { "summary": "获取累充积分列表", "description": "获取项目内的累充积分列表以用于管理。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "tags": [ "reward-chain-value-points-admin" ], "operationId": "admin-get-value-points-list", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-value-points" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } }, "post": { "summary": "创建累充积分", "description": "创建累充积分。", "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "operationId": "admin-create-value-points", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "security": [ { "basicAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/create-value-point" }, "responses": { "201": { "$ref": "#/components/responses/201-admin-create-value-point" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/422-admin-create-update-rc-vp-invalid-request" } } } }, "/v2/project/{project_id}/admin/items/value_points/sku/{item_sku}": { "get": { "summary": "获取累充积分", "description": "根据项目中的SKU获取累充积分以进行管理。", "operationId": "admin-get-value-point", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/item_sku-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-value-point" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } }, "put": { "summary": "更新累充积分", "description": "按SKU更新累充积分。", "operationId": "admin-update-value-point", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/item_sku-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "requestBody": { "$ref": "#/components/requestBodies/create-value-point" }, "responses": { "204": { "description": "Value point was successfully updated.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/422-admin-create-update-rc-vp-invalid-request" } } }, "delete": { "summary": "删除累充积分", "description": "按SKU删除累充积分。", "operationId": "admin-delete-value-point", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/item_sku-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "responses": { "204": { "description": "Value point was successfully deleted.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } } }, "/v2/project/{project_id}/admin/items/{value_point_sku}/value_points/rewards": { "get": { "summary": "获取具有累充积分的商品列表", "description": "获取项目内具有累充积分的商品列表以用于管理。", "operationId": "admin-get-items-value-point-reward", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/value_point_sku-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-list-value-point-rewards" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } }, "put": { "summary": "设置商品的累充积分", "description": "按SKU为一件或多件商品分配累充积分。用户购买这些商品后将获得累充积分。\n\n请注意，此PUT请求将覆盖项目中商品此前设置的所有累充积分。\n\n为避免误删累充积分，请在每个PUT请求中包含所有商品及其对应的累充积分。\n\n如果只想更新特定商品的累充积分，同时保留其他商品的累充积分，请先使用GET请求获取当前累充积分集合，修改目标商品的累充积分，然后将包含该商品更新后累充积分的完整集合发回。", "operationId": "admin-set-items-value-point-reward", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/value_point_sku-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "requestBody": { "$ref": "#/components/requestBodies/set-item-value-point-reward" }, "responses": { "204": { "description": "Value point rewards for items were successfully updated.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/sellable-item-by-sku_404" } } }, "patch": { "summary": "部分更新商品的累充积分", "description": "按照商品SKU部分更新一个或多个商品的累充积分数量。用户购买指定商品后可获得这些累充积分。\n\n更新累充积分的原则：\n * 如果某个商品尚无累充积分，则在`amount`字段中发送非零值将创建累充积分。\n * 如果某个商品已有累充积分，则在`amount`字段中发送非零值将更新累充积分。\n * 如果`amount`设置为0，则会删除该商品的现有累充积分。\n\n与`PUT`方法（[设置商品的累充积分](https://developers.xsolla.com/zh/api/shop-builder/operation/admin-set-items-value-point-reward/)）不同，此`PATCH`方法不会覆盖项目中所有商品的现有累充积分，而只会更新指定商品。\n\n单个请求最多可以更新100个商品。同一请求中不能包含重复的商品SKU。", "operationId": "admin-patch-items-value-point-reward", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/value_point_sku-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "requestBody": { "$ref": "#/components/requestBodies/set-item-value-point-reward-for-patch" }, "responses": { "204": { "description": "Value point rewards for items were successfully updated.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/sellable-item-by-sku_404" } } }, "delete": { "summary": "删除商品的累充积分", "description": "删除所有商品的累充积分奖励。", "operationId": "admin-delete-items-value-point-reward", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "security": [ { "basicAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/value_point_sku-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "responses": { "204": { "description": "Value point rewards for items were successfully deleted.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } } }, "/v2/project/{project_id}/user/reward_chain": { "get": { "tags": [ "reward-chain-client" ], "operationId": "get-reward-chains-list", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "获取当前用户的累充奖励链", "description": "客户端接口。获取当前用户的累充奖励链。\n\n
\n 注意

\n 所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。\n
\n\n
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "responses": { "200": { "$ref": "#/components/responses/200-client-get-reward-chains-list" } } } }, "/v2/project/{project_id}/user/reward_chain/{reward_chain_id}/balance": { "get": { "tags": [ "reward-chain-client" ], "operationId": "get-user-reward-chain-balance", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "获取当前用户的累充积分余额", "description": "Client endpoint. Gets the current user’s value point balance.
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/reward_chain_id-path-param" } ], "responses": { "200": { "$ref": "#/components/responses/200-client-get-user-reward-chain-balance" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" } } } }, "/v2/project/{project_id}/user/reward_chain/{reward_chain_id}/step/{step_id}/claim": { "post": { "tags": [ "reward-chain-client" ], "operationId": "claim-user-reward-chain-step-reward", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "领取步骤奖励", "description": "客户端接口。从累充奖励链中领取当前用户的阶段奖励。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/reward_chain_id-path-param" }, { "$ref": "#/components/parameters/reward_chain_step_id-path-param" } ], "responses": { "204": { "description": "Successfully claimed the current user's step reward from a reward chain." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "404": { "$ref": "#/components/responses/404-reward-chain-step-not-found" }, "422": { "$ref": "#/components/responses/422-reward-chain-step-reward-can-not-claimed" } } } }, "/v2/project/{project_id}/user/clan/contributors/{reward_chain_id}/top": { "get": { "tags": [ "clan-reward-chain-client" ], "operationId": "get-user-clan-top-contributors", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "responses": { "200": { "description": "The top 10 list of contributors to the clan's reward chain.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Rocket", "description": "User ID. This is the ID sending to Xsolla during authorization and links the user to your Xsolla Login project." }, "contributed_amount": { "type": "integer", "example": 100, "description": "The amount of value points contributed by the user." } } } }, "examples": { "clan": { "summary": "User has a clan", "value": [ { "name": "winner", "contributed_amount": 555 }, { "name": "Rocket", "contributed_amount": 398 }, { "name": "MrJoe", "contributed_amount": 201 }, { "name": "beginner", "contributed_amount": 1 } ] }, "without-clan": { "summary": "User doesn't belong to a clan", "value": [] } } } } } }, "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "项目ID。", "schema": { "type": "integer", "example": 44056 } }, { "name": "reward_chain_id", "in": "path", "required": true, "description": "累充奖励链ID。", "schema": { "type": "integer", "example": 101 } } ], "summary": "获取公会名下累充奖励链的前10名贡献者列表", "description": "获取当前用户所在公会下指定累充奖励链的前10名贡献者列表。如果用户不属于任何公会，该调用将返回空数组。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
" } }, "/v2/project/{project_id}/user/clan/update": { "put": { "tags": [ "clan-reward-chain-client" ], "operationId": "user-clan-update", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "responses": { "200": { "$ref": "#/components/responses/200-client-update-user-clan" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" } }, "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "description": "项目ID。", "schema": { "type": "integer", "default": 44056 } } ], "summary": "更新当前用户的公会", "description": "通过用户属性更新当前用户所属的公会。系统会领取该用户此前所属公会中累充奖励链的所有未领取奖励，并在响应中返回这些奖励。如果用户此前属于某个公会，但现在不属于任何公会，则会撤销其公会成员身份。如果用户更换了公会，则会更新为新的公会。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
" } }, "/v3/project/{project_id}/admin/reward_chain": { "get": { "summary": "获取累充奖励链列表", "description": "获取累充奖励链列表。\n\n
注意

所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应10项。如需逐页获取更多数据，请使用limit和offset字段。
", "operationId": "admin-get-reward-chains", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/enabled-query-param" } ], "tags": [ "reward-chain-value-points-admin" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-list-reward-chains" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } }, "post": { "summary": "创建累充奖励链", "description": "创建累充奖励链。", "security": [ { "basicAuth": [] } ], "operationId": "admin-create-reward-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "requestBody": { "$ref": "#/components/requestBodies/create-reward-chain" }, "responses": { "201": { "$ref": "#/components/responses/201-admin-create-reward-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/422-admin-create-update-rc-vp-invalid-request" } } } }, "/v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}": { "get": { "summary": "获取累充奖励链", "description": "获取指定累充奖励链。", "operationId": "admin-get-reward-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/reward_chain_id-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-reward-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-admin-reward-chain-not-found" } } }, "put": { "summary": "更新累充奖励链", "description": "更新指定累充奖励链。", "security": [ { "basicAuth": [] } ], "operationId": "admin-update-reward-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/reward_chain_id-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "requestBody": { "$ref": "#/components/requestBodies/update-reward-chain" }, "responses": { "204": { "$ref": "#/components/responses/204-admin-update-reward-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-admin-reward-chain-not-found" }, "422": { "$ref": "#/components/responses/422-admin-create-update-rc-vp-invalid-request" } } }, "delete": { "summary": "删除累充奖励链", "description": "删除指定累充奖励链。", "security": [ { "basicAuth": [] } ], "operationId": "admin-delete-reward-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/reward_chain_id-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "responses": { "204": { "$ref": "#/components/responses/204-admin-delete-reward-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } } }, "/v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}/toggle": { "put": { "summary": "启停累充奖励链", "description": "启用/禁用累充奖励链。", "security": [ { "basicAuth": [] } ], "operationId": "admin-toggle-reward-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/reward_chain_id-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "responses": { "204": { "$ref": "#/components/responses/204-admin-toggle-reward-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } } }, "/v3/project/{project_id}/admin/reward_chain/id/{reward_chain_id}/reset": { "post": { "summary": "重置累充奖励链", "description": "重置累充奖励链中所有用户的累充积分余额和进度。
余额与累充积分类型绑定，而非与特定累充奖励链绑定。如果这些累充积分也用于其他奖励链，则使用这些累充积分的所有奖励链中的余额都会被重置。
重置后，您可以更新累充奖励链的有效期，用户将能够重新推进该累充奖励链。
公会余额按其成员余额总和计算。因此，重置后公会余额也会被重置。
此请求不可逆，且适用于项目的所有用户。\n\n
提示\n

\n请勿在累充奖励链有效期内重置累充奖励链。否则，用户可能会在领取奖励前失去已获得的累充积分。\n
", "security": [ { "basicAuth": [] } ], "operationId": "admin-reset-reward-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/reward_chain_id-path-param" } ], "tags": [ "reward-chain-value-points-admin" ], "responses": { "204": { "$ref": "#/components/responses/204-admin-reset-reward-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } } }, "/v2/project/{project_id}/admin/daily_chain": { "get": { "summary": "获取每日奖励列表", "description": "获取用于管理的每日奖励列表。\n\n
提示

该方法返回分页的商品列表。最大值和默认值均为每个响应50个商品。如需获取列表中的更多商品，请使用`limit`和`offset`参数分页获取。例如，调用方法时传入`limit = 25`和`offset = 100`，响应将返回总列表中从第101个商品开始的25个商品。
", "operationId": "admin-get-daily-chains", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/enabled-query-param" }, { "$ref": "#/components/parameters/is_expired-daily-chain-query-param" }, { "$ref": "#/components/parameters/type-daily-chain-query-param" } ], "tags": [ "daily-chain-admin" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-list-daily-chains" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } }, "post": { "summary": "创建每日奖励", "description": "创建每日奖励。", "security": [ { "basicAuth": [] } ], "operationId": "admin-create-daily-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "daily-chain-admin" ], "requestBody": { "$ref": "#/components/requestBodies/create-daily-chain" }, "responses": { "201": { "$ref": "#/components/responses/201-admin-create-daily-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/422-admin-create-error-list" } } } }, "/v2/project/{project_id}/admin/daily_chain/id/{daily_chain_id}": { "get": { "summary": "获取每日奖励", "description": "获取指定每日奖励以用于管理。", "operationId": "admin-get-daily-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/daily_chain_id-path-param" } ], "tags": [ "daily-chain-admin" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-daily-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-daily-chain-not-found" } } }, "put": { "summary": "更新每日奖励", "description": "更新指定每日奖励。", "security": [ { "basicAuth": [] } ], "operationId": "admin-update-daily-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/daily_chain_id-path-param" } ], "tags": [ "daily-chain-admin" ], "requestBody": { "$ref": "#/components/requestBodies/update-daily-chain" }, "responses": { "204": { "description": "Daily reward was successfully updated.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-daily-chain-not-found" }, "422": { "$ref": "#/components/responses/422-admin-update-error-list" } } }, "delete": { "summary": "删除每日奖励", "description": "删除指定每日奖励。", "security": [ { "basicAuth": [] } ], "operationId": "admin-delete-daily-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/daily_chain_id-path-param" } ], "tags": [ "daily-chain-admin" ], "responses": { "204": { "description": "Daily reward was successfully deleted.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-daily-chain-not-found" } } } }, "/v2/project/{project_id}/admin/daily_chain/id/{daily_chain_id}/toggle": { "put": { "summary": "切换每日奖励", "description": "启用或禁用每日奖励。", "security": [ { "basicAuth": [] } ], "operationId": "admin-toggle-daily-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/daily_chain_id-path-param" } ], "tags": [ "daily-chain-admin" ], "responses": { "204": { "description": "The daily reward has been disabled or enabled.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-daily-chain-not-found" } } } }, "/v2/project/{project_id}/admin/daily_chain/id/{daily_chain_id}/reset": { "post": { "summary": "重置每日奖励", "description": "重置所有用户的每日奖励进度。仅适用于`rolling`类型每日奖励。", "security": [ { "basicAuth": [] } ], "operationId": "admin-reset-daily-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/daily_chain_id-path-param" } ], "tags": [ "daily-chain-admin" ], "responses": { "204": { "description": "The daily reward has been reset.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-daily-chain-not-found" } } } }, "/v2/project/{project_id}/user/daily_chain": { "get": { "tags": [ "daily-chain-client" ], "operationId": "get-daily-chains-list", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "获取当前用户的每日奖励", "description": "客户端接口。获取当前用户的每日奖励。\n\n
提示

该方法返回分页的商品列表。最大值和默认值均为每个响应50个商品。如需获取列表中的更多商品，请使用limit和offset参数分页获取。例如，调用方法时传入limit = 25和offset = 100，响应将返回总列表中从第101个商品开始的25个商品。
\n\n
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "responses": { "200": { "$ref": "#/components/responses/200-client-get-daily-chains-list" }, "401": { "$ref": "#/components/responses/401-client-auth-error" } } } }, "/v2/project/{project_id}/user/daily_chain/{daily_chain_id}": { "get": { "tags": [ "daily-chain-client" ], "operationId": "get-user-daily-chain-by-id", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "通过ID获取当前用户的每日奖励", "description": "客户端接口。通过ID获取当前用户的每日奖励。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/daily_chain_id-path-param" } ], "responses": { "200": { "description": "The user’s daily reward was successfully retrieved.", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-client-daily-chain" } }, "schema": { "$ref": "#/components/schemas/client-daily-chain-model" } } } }, "404": { "$ref": "#/components/responses/404-daily-chain-not-found" } } } }, "/v2/project/{project_id}/user/daily_chain/{daily_chain_id}/step/number/{step_number}/claim": { "post": { "tags": [ "daily-chain-client" ], "operationId": "claim-user-daily-chain-step-reward", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "领取每日奖励步骤", "description": "客户端接口。领取当前用户每日奖励中的步骤奖励。所有步骤只能按顺序领取。错过步骤的奖励无法通过虚拟货币、真实货币或观看广告获得。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/daily_chain_id-path-param" }, { "$ref": "#/components/parameters/daily_chain_step_number-path-param" } ], "responses": { "204": { "description": "Successfully claimed the current user's step reward for a daily reward step." }, "401": { "$ref": "#/components/responses/401-client-auth-error" }, "404": { "$ref": "#/components/responses/404-daily-chain-step-not-found" }, "422": { "description": "Step can't be claimed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/daily-chain-error-model" }, "examples": { "invalid-step": { "$ref": "#/components/examples/422-daily-chain-claim-error-invalid-step" } } } } } } } }, "/v2/project/{project_id}/user/offer_chain": { "get": { "tags": [ "offer-chain-client" ], "operationId": "get-offer-chains-list", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "获取当前用户的优惠链", "description": "获取当前用户的优惠链。\n\n
提示

所有项目的单次响应中返回的商品数量都有上限。默认值和最大值为每次响应30个商品。如需更多数据，可通过limit与offset查询参数分页获取。
\n\n
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" } ], "responses": { "200": { "$ref": "#/components/responses/200-client-get-offer-chains-list" } } } }, "/v2/project/{project_id}/user/offer_chain/{offer_chain_id}": { "get": { "tags": [ "offer-chain-client" ], "operationId": "get-user-offer-chain-by-id", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "根据ID获取当前用户的优惠链", "description": "通过优惠链ID获取当前用户的优惠链。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/offer_chain_id-path-param" } ], "responses": { "200": { "description": "The user’s offer chain was successfully retrieved.", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-client-offer-chain" } }, "schema": { "$ref": "#/components/schemas/client-offer-chain-model" } } } }, "404": { "$ref": "#/components/responses/404-offer-chain-not-found" } } } }, "/v2/project/{project_id}/user/offer_chain/{offer_chain_id}/step/number/{step_number}/claim": { "post": { "tags": [ "offer-chain-client" ], "operationId": "claim-user-offer-chain-step-reward", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "领取免费优惠链步骤奖励", "description": "完成当前用户的优惠链步骤进程，并发放相关奖励。\n\n
\n 提示

\n 仅对优惠链中的免费步骤使用此调用。\n 对于需要使用真实货币支付的步骤，请改用为付费优惠链步骤创建订单调用。\n
\n\n
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/offer_chain_id-path-param" }, { "$ref": "#/components/parameters/offer_chain_step_number-path-param" } ], "responses": { "200": { "description": "The free step was successfully claimed and the reward granted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "integer", "description": "订单ID。" } } }, "examples": { "response": { "value": { "order_id": 641 } } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "404": { "$ref": "#/components/responses/404-offer-chain-step-not-found" }, "422": { "description": "The step cannot be claimed. Ensure all previous steps are completed and the step is marked as free.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/offer-chain-error-model" }, "examples": { "invalid-step": { "$ref": "#/components/examples/422-offer-chain-claim-error-invalid-step" } } } } } } } }, "/v2/project/{project_id}/user/offer_chain/{offer_chain_id}/step/number/{step_number}/order": { "post": { "tags": [ "offer-chain-client", "payment-client-side" ], "operationId": "order-user-offer-chain-step-reward", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "summary": "为付费优惠链步骤创建订单", "description": "为指定的付费优惠链步骤关联的商品创建订单。所创建订单的状态为`new`。\n\n如需在新窗口中打开支付UI，请使用以下链接：`https://secure.xsolla.com/paystation4/?token={token}`，其中`{token}是收到的令牌。\n\n如要进行测试，请使用以下URL：`https://sandbox-secure.xsolla.com/paystation4/?token={token}`。\n\n
\n 提示

\n 此方法必须在客户端侧使用。系统会根据用户的IP地址确定其所在国家/地区，这会影响适用货币和可用支付方式。从服务器侧使用此方法可能会导致货币检测错误，并影响支付收银台中的支付方式。\n
\n\n
\n\n
\n 提示

\n 此调用仅适用于付费优惠链步骤。\n 对于免费步骤，请改用领取免费优惠链步骤奖励调用。\n
\n\n
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/offer_chain_id-path-param" }, { "$ref": "#/components/parameters/offer_chain_step_number-path-param" } ], "responses": { "200": { "$ref": "#/components/responses/Cart-Payment_200-order-created" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "404": { "$ref": "#/components/responses/404-offer-chain-step-not-found" }, "422": { "description": "The step cannot be purchased.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/offer-chain-error-model" }, "examples": { "invalid-step": { "$ref": "#/components/examples/422-offer-chain-claim-error-invalid-step" } } } } } } } }, "/v2/project/{project_id}/admin/offer_chain": { "get": { "summary": "获取优惠链列表", "description": "获取优惠链列表以用于管理。\n\n
提示

所有项目的单次响应中返回的商品数量都有上限。默认值和最大值为每次响应10个商品。如需更多数据，可通过limit与offset查询参数分页获取。
", "operationId": "admin-get-offer-chains", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/limit-query-param" }, { "$ref": "#/components/parameters/offset-query-param" }, { "$ref": "#/components/parameters/enabled-query-param" } ], "tags": [ "offer-chain-admin" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-list-offer-chains" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" } } }, "post": { "summary": "创建优惠链", "description": "创建优惠链。", "security": [ { "basicAuth": [] } ], "operationId": "admin-create-offer-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "tags": [ "offer-chain-admin" ], "requestBody": { "$ref": "#/components/requestBodies/create-offer-chain" }, "responses": { "201": { "$ref": "#/components/responses/201-admin-create-offer-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "422": { "$ref": "#/components/responses/422-create-error-list" } } } }, "/v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}": { "get": { "summary": "获取优惠链", "description": "获取指定优惠链以用于管理。", "operationId": "admin-get-offer-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/offer_chain_id-path-param" } ], "tags": [ "offer-chain-admin" ], "security": [ { "basicAuth": [] } ], "responses": { "200": { "$ref": "#/components/responses/200-admin-get-offer-chain" }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-offer-chain-not-found" } } }, "put": { "summary": "更新优惠链", "description": "更新指定优惠链。", "security": [ { "basicAuth": [] } ], "operationId": "admin-update-offer-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/offer_chain_id-path-param" } ], "tags": [ "offer-chain-admin" ], "requestBody": { "$ref": "#/components/requestBodies/update-offer-chain" }, "responses": { "204": { "description": "Offer chain was successfully updated.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-offer-chain-not-found" }, "422": { "$ref": "#/components/responses/422-update-error-list" } } }, "delete": { "summary": "删除优惠链", "description": "删除指定优惠链。\n\n删除后：
  • 用户已收到的奖励保留。
  • 未完成步骤不再可用，不可再获取奖励。
\n\n与通过启停优惠链禁用优惠链不同，删除不可恢复，用户进度不保留。", "security": [ { "basicAuth": [] } ], "operationId": "admin-delete-offer-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/offer_chain_id-path-param" } ], "tags": [ "offer-chain-admin" ], "responses": { "204": { "description": "Offer chain was successfully deleted.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-offer-chain-not-found" } } } }, "/v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}/toggle": { "put": { "summary": "启停优惠链", "description": "启用/禁用优惠链。\n\n禁用后，用户暂时无法访问，但进度保留。\n\n重新启用后，用户可从上次步骤的进度继续。", "security": [ { "basicAuth": [] } ], "operationId": "admin-toggle-offer-chain", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "$ref": "#/components/parameters/offer_chain_id-path-param" } ], "tags": [ "offer-chain-admin" ], "responses": { "204": { "description": "The offer chain has been disabled/enabled.", "content": {} }, "401": { "$ref": "#/components/responses/401-invalid-basic-auth" }, "404": { "$ref": "#/components/responses/404-offer-chain-not-found" } } } }, "/v2/project/{project_id}/admin/items/upsell": { "get": { "tags": [ "upsell-admin" ], "operationId": "get-upsell-configurations-for-project-admin", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "responses": { "200": { "description": "The list of configuration details and items used for upsell in the project.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "is_enabled": { "type": "boolean", "example": true, "description": "Whether upsell is enabled for the project." }, "type": { "type": "string", "enum": [ "fixed_list", "most_sellable", "only_promotions" ], "example": "fixed_list", "description": "The type of upsell." }, "items": { "type": "array", "example": [ { "item_id": 1, "sku": "com.xsolla.booster_mega_1", "name": { "en": "Item's name", "de": "Name des Artikels" }, "type": "virtual_good" } ], "description": "The list of items SKU that are a part of the upsell in the project.", "items": { "type": "object", "properties": { "item_id": { "$ref": "#/components/schemas/item_id" }, "sku": { "$ref": "#/components/schemas/sku" }, "type": { "$ref": "#/components/schemas/item_type" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "bundle_type": { "$ref": "#/components/schemas/bundle_type" }, "unit_type": { "$ref": "#/components/schemas/unit_type" }, "unit_items": { "type": "array", "description": "Game keys for different DRMs.", "items": { "type": "object", "description": "Game key item. It represents game on a certain platform (steam, gog, etc.).", "properties": { "item_id": { "$ref": "#/components/schemas/item_id" }, "sku": { "$ref": "#/components/schemas/sku" }, "type": { "$ref": "#/components/schemas/item_type" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "drm_name": { "$ref": "#/components/schemas/drm_name" }, "drm_sku": { "$ref": "#/components/schemas/drm_sku" } } } } } } } } } }, "examples": { "upsell": { "summary": "Project has upsell", "value": [ { "is_enabled": true, "type": "fixed_list", "items": [ { "item_id": 1, "sku": "com.xsolla.booster_mega_1", "name": { "en": "Item's name", "de": "Name des Artikels" }, "type": "virtual_good" }, { "item_id": 2, "sku": "com.xsolla.booster_mega_2", "name": { "en": "Item's name", "de": "Name des Artikels" }, "type": "bundle", "bundle_type": "standard" }, { "item_id": 3, "sku": "com.xsolla.mega_game_1", "name": { "en": "Mega game" }, "type": "unit", "unit_type": "game", "unit_items": [ { "item_id": 4, "sku": "com.xsolla.mega_game_steam_1", "name": { "en": "Mega game steam" }, "drm_name": "Steam", "drm_sku": "steam_key_1" } ] } ] } ] } } } } }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" } }, "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "summary": "获取项目中追加销售的信息", "description": "检索项目中追加销售的信息：是否启用、追加销售的类型以及属于此追加销售的商品SKU列表。" }, "post": { "tags": [ "upsell-admin" ], "operationId": "post-upsell", "summary": "创建追加销售", "description": "为项目创建追加销售。
\n\n
\n 提示

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中包含令牌，格式为：Bearer <user_JWT>。有关用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "requestBody": { "$ref": "#/components/requestBodies/create-upsell" }, "responses": { "202": { "description": "Upsell has been created for the project." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "404": { "$ref": "#/components/responses/Upsell-404-item-not-found" }, "422": { "$ref": "#/components/responses/Upsell-422-invalid-request" } } }, "put": { "tags": [ "upsell-admin" ], "operationId": "put-upsell", "summary": "更新追加销售", "description": "更新项目的追加销售。
\n\n
\n 提示

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中包含令牌，格式为：Bearer <user_JWT>。有关用户JWT的更多信息，请参阅此调用的安全性部分。\n
", "security": [ { "XsollaLoginUserJWT": [] } ], "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "requestBody": { "$ref": "#/components/requestBodies/update-upsell" }, "responses": { "202": { "description": "Upsell has been updated for the project." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" }, "404": { "$ref": "#/components/responses/Upsell-404-item-not-found" }, "422": { "$ref": "#/components/responses/Upsell-422-invalid-request" } } } }, "/v2/project/{project_id}/admin/items/upsell/{toggle}": { "put": { "tags": [ "upsell-admin" ], "operationId": "put-upsell-toggle-active-inactive", "x-badges": [ { "name": "Server-side", "color": "#95ff80" }, { "name": "管理", "color": "#d7dee0" } ], "responses": { "202": { "description": "An upsell in a project was activated or deactivated." }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" } }, "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" }, { "name": "toggle", "in": "path", "required": true, "description": "激活状态。", "schema": { "type": "string", "example": "activate" } } ], "summary": "激活/停用项目的追加销售", "description": "将项目中追加销售的状态更改为有效或无效。
\n\n
\n 提示

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中包含令牌，格式为：Bearer <user_JWT>。有关用户JWT的更多信息，请参阅此调用的安全性部分。\n
" } }, "/v2/project/{project_id}/items/upsell": { "get": { "tags": [ "upsell-client" ], "operationId": "get-upsell-for-project-client", "x-badges": [ { "name": "Client-side", "color": "#80eaff" } ], "responses": { "200": { "$ref": "#/components/responses/Upsell-200-get-client-list" }, "401": { "$ref": "#/components/responses/Promotions_401-invalid-client-auth" } }, "security": [ { "XsollaLoginUserJWT": [] } ], "parameters": [ { "$ref": "#/components/parameters/project_id-path-param" } ], "summary": "获取项目中追加销售商品的列表", "description": "如果项目中已设置追加销售商品，则获取这些商品的列表。
\n\n
\n 注：

\n 此API调用使用用户JWT进行授权。

\n 请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。\n
" } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "description": "服务器侧调用使用`basicAuth`身份认证方案。向API发送的所有请求都必须包含`Authorization: Basic `请求头，其中`your_authorization_basic_key`是根据Base64标准编码的`project_id:api_key`对。\n\n如有需要，您可以使用`merchant_id`代替`project_id`。这不会影响功能。\n\n前往[发布商帐户](https://publisher.xsolla.com/)查找参数值：\n\n* `merchant_id`显示在：\n * **公司设置 > 公司**部分\n * 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com/`。\n* `api_key`仅会在创建时于发布商帐户中显示一次，必须由您在己侧保存。您可以在以下部分创建新密钥：\n * [公司设置 > API密钥](https://publisher.xsolla.com/0/settings/api_key)\n * [项目设置 > API密钥](https://publisher.xsolla.com/0/projects/0/edit/api_key)\n\n{% html name=\"div\" attrs={\"class\": \"notice\"} %}\n**提示**\n\n如果所需的API调用不包含`project_id`路径参数，请使用对公司所有项目均有效的API密钥进行授权。\n{% /html %}\n\n* `project_id`显示在：\n * 发布商帐户中项目名称旁边。\n * 发布商帐户中项目页浏览器地址栏中的URL中。URL格式为：`https://publisher.xsolla.com//projects/`。\n\n有关使用API密钥的更多信息，请参阅[API参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。", "scheme": "basic" }, "XsollaLoginUserJWT": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "客户端侧调用使用`XsollaLoginUserJWT`身份认证方案。请求须在`Authorization`请求头中包含用户JWT，格式为：Bearer ``。令牌用于识别用户并提供个性化数据访问权限。有关令牌创建方法，请参阅[艾克索拉登录管理器API文档](/zh/api/login/authentication-schemes#getting-user-token)。\n\n或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。" }, "AuthForCart": { "type": "http", "scheme": "bearer", "description": "`AuthForCart`身份认证方案用于购物车购买，支持两种模式：\n\n1. 使用用户JWT进行身份认证。 令牌通过Authorization请求头按以下格式传递：`Authorization: Bearer `，其中``是用户令牌。该令牌用于识别用户，并提供对个性化数据的访问权限。\n\n或者，您也可以使用[用于打开支付UI的令牌](/zh/api/pay-station/token/create-token)。\n\n2. 不带`Authorization`请求头的简化模式。此模式仅适用于未完成身份认证的用户，且仅可用于[游戏Key销售](/zh/doc/buy-button/how-to/set-up-authentication/#guides_buy_button_selling_items_not_authenticated_users)请求中不使用令牌，而必须包含以下请求头：\n* `x-unauthorized-id`，值为请求ID\n* `x-user`，值为使用Base64编码的用户电子邮件地址。" }, "basicMerchantAuth": { "type": "http", "description": "服务器侧调用使用`basicMerchantAuth`身份认证方案。向API发送的所有请求都必须包含`Authorization: Basic `请求头，其中`your_authorization_basic_key`是根据Base64标准编码的`merchant_id:api_key`对。\n\n前往[发布商帐户](https://publisher.xsolla.com/)查找参数值：\n\n* `merchant_id`显示在：\n * **公司设置 > 公司**部分\n * 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：`https://publisher.xsolla.com/`。\n* `api_key`仅会在创建时于发布商帐户中显示一次，必须由您在己侧保存。您可以在[公司设置 > API密钥](https://publisher.xsolla.com/0/settings/api_key)部分创建新密钥。\n\n有关使用API密钥的更多信息，请参阅[API参考](https://developers.xsolla.com/zh/api/getting-started/#api_keys_overview)。", "scheme": "basic" } }, "parameters": { "project_id-path-param": { "name": "project_id", "in": "path", "required": true, "description": "项目ID。您可以在[发布商帐户](https://publisher.xsolla.com/0/projects/0/)的项目名称旁找到此参数；使用项目时，也可以在浏览器地址栏中找到此参数。URL格式如下：`https://publisher.xsolla.com//projects/`。", "schema": { "type": "integer", "example": 44056 } }, "limit-query-param": { "name": "limit", "in": "query", "example": 50, "required": false, "description": "页面上元素数量的限制。", "schema": { "type": "integer", "example": 50, "minimum": 1 } }, "offset-query-param": { "name": "offset", "in": "query", "required": false, "example": 0, "description": "生成列表时作为起始位置的元素编号（从0开始计数）。", "schema": { "type": "integer", "example": 0, "minimum": 0 } }, "enabled-query-param": { "name": "enabled", "in": "query", "required": false, "description": "通过`is_enabled`标志筛选元素。", "schema": { "type": "integer" } }, "promotion_id-path-param": { "name": "promotion_id", "in": "path", "required": true, "description": "促销活动ID。项目内的唯一促销活动标识符。", "schema": { "type": "integer", "example": 111425 } }, "code-path-param": { "name": "code", "in": "path", "required": true, "description": "唯一区分大小写的代码。包含字母和数字。", "schema": { "type": "string", "example": "WINTER2021", "minLength": 1, "maxLength": 128 } }, "coupon_code-path-param": { "name": "coupon_code", "in": "path", "required": true, "description": "区分大小写的唯一兑换码。包含字母和数字。", "schema": { "type": "string", "example": "WINTER2021", "minLength": 1, "maxLength": 128 } }, "external_id-promotion-path-param": { "name": "external_id", "in": "path", "required": true, "description": "促销活动外部ID。项目内的唯一促销活动标识符。", "schema": { "type": "integer", "example": "coupon_44056_1" } }, "promocode_code-path-param": { "name": "promocode_code", "in": "path", "required": true, "description": "区分大小写的唯一兑换码。包含字母和数字。", "schema": { "type": "string", "example": "SO6rew99j9", "minLength": 1, "maxLength": 128 } }, "user_external_id-query-param": { "name": "user_external_id", "in": "query", "required": true, "description": "用户外部ID", "schema": { "type": "string", "example": "d342dad2-9d59-11e9-a384-42010aa8003f" } }, "codes-query-param": { "name": "codes[]", "in": "query", "description": "区分大小写的唯一代码。仅包含字母和数字。", "schema": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "is_enabled-query-param": { "name": "is_enabled", "in": "query", "required": false, "description": "通过`is_enabled`标志筛选元素。", "schema": { "type": "integer" } }, "personalized-catalog-rule_id-path-param": { "name": "rule_id", "in": "path", "required": true, "description": "规则ID。", "schema": { "type": "number", "example": 1 } }, "item_sku-path-param": { "name": "item_sku", "in": "path", "required": true, "description": "商品SKU。", "schema": { "type": "string", "example": "booster_mega_1" } }, "value_point_sku-path-param": { "name": "value_point_sku", "in": "path", "required": true, "description": "累充积分SKU。", "schema": { "type": "string", "example": "value_point_3" } }, "reward_chain_id-path-param": { "name": "reward_chain_id", "in": "path", "required": true, "description": "累充奖励链ID。", "schema": { "type": "integer", "example": 101 } }, "reward_chain_step_id-path-param": { "name": "step_id", "in": "path", "required": true, "description": "奖励链步骤ID。", "schema": { "type": "integer", "example": 120 } }, "is_expired-daily-chain-query-param": { "name": "is_expired", "in": "query", "required": false, "description": "筛选每日奖励，仅显示已过期的奖励。", "schema": { "type": "integer" } }, "type-daily-chain-query-param": { "name": "type", "in": "query", "required": false, "description": "按指定类型筛选每日奖励。", "schema": { "type": "string", "enum": [ "calendar_hard", "rolling_skippable", "rolling_unskippable" ] } }, "daily_chain_id-path-param": { "name": "daily_chain_id", "in": "path", "required": true, "description": "每日奖励ID。", "schema": { "type": "integer", "example": 101 } }, "daily_chain_step_number-path-param": { "name": "step_number", "in": "path", "required": true, "description": "每日奖励步骤编号。", "schema": { "type": "integer", "example": 1 } }, "offer_chain_id-path-param": { "name": "offer_chain_id", "in": "path", "required": true, "description": "优惠链ID。", "schema": { "type": "integer", "example": 101 } }, "offer_chain_step_number-path-param": { "name": "step_number", "in": "path", "required": true, "description": "优惠链步骤编号。", "schema": { "type": "integer", "example": 1 } } }, "schemas": { "Promotions_promotion_id": { "type": "integer", "description": "促销活动ID。项目内的唯一促销活动标识符。", "example": 1 }, "promotion_periods": { "type": "array", "nullable": false, "description": "促销活动有效期。若指定了多个时间段，则`date_from`和`date_until`均为必需。", "items": { "type": "object", "properties": { "date_from": { "type": "string", "format": "date-time", "nullable": false, "example": "2020-08-11T10:00:00+03:00", "description": "指定促销活动的开始日期。" }, "date_until": { "type": [ "string", "null" ], "format": "date-time", "example": "2020-08-11T20:00:00+03:00", "description": "促销活动的结束日期。设置为`null`时，促销活动永久有效。仅在指定单个有效期时可设置为`null`。" } }, "required": [ "date_from" ] } }, "Promotions_coupon_name": { "type": "object", "description": "促销活动名称。应包含键/值对，\n其中键是\"^[a-z]{2}-[A-Z]{2}$\"格式的区域设置，值是字符串。", "additionalProperties": { "type": "string" }, "example": { "en-US": "Coupon title", "de-DE": "Gutscheintitel" }, "default": { "en-US": "Coupon title", "de-DE": "Gutscheintitel" } }, "unit_items": { "type": "array", "description": "平台专属游戏Key数组。仅当商品类型为`unit` (`bonus.item.type = 'unit'`)时使用。如果游戏Key套餐包含平台专属Key，用户可以选择其中一个作为赠品。", "items": { "type": "object", "properties": { "sku": { "type": "string", "example": "cool_game_steam", "pattern": "^[a-zA-Z0-9_\\-.]*$", "description": "唯一的平台专属游戏Key套餐ID。允许使用以下字符：a-z、A-Z、0-9、句点（.）、连字符（-）、下划线（_）。该值由`bonus.item.​sku`和`bonus.item.unit_items.drm_sku`的值组合而成。例如，如果`bonus.item.​sku = 'cool_game'`，且`bonus.item.unit_items.drm_sku = 'steam'`，则该值为`cool_game_steam`。" }, "is_free": { "type": "boolean" }, "type": { "type": "string", "enum": [ "game_key" ], "description": "表示该商品为游戏Key。" }, "name": { "type": "string", "example": "Awesome Game", "description": "游戏名称。" }, "drm_name": { "type": "string", "example": "Steam", "description": "DRM名称。" }, "drm_sku": { "type": "string", "pattern": "^[a-zA-Z0-9_\\-.]*$", "example": "steam", "description": "唯一DRM ID，用作后缀以表示平台专属游戏Key。允许使用以下字符：a-z、A-Z、0-9、句点（.）、连字符（-）、下划线（_）。" } } } }, "Promotions_200-coupon-bonus-reward": { "type": "object", "properties": { "item": { "type": "object", "properties": { "sku": { "type": "string", "example": "game_01", "description": "唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。" }, "name": { "type": "object", "example": { "en": "Game name" }, "description": "商品名称。" }, "type": { "type": "string", "example": "unit", "description": "商品类型。可能值：
  • virtual_good — 虚拟物品
  • virtual_currency — 虚拟货币
  • bundle — 捆绑包
  • unit — 游戏Key套餐
" }, "bundle_type": { "type": "string", "description": "捆绑包类型。当商品类型为捆绑包时返回。", "enum": [ "standard", "virtual_currency_package" ] }, "description": { "type": [ "string", "null" ], "example": "Game description", "description": "Item description." }, "image_url": { "type": [ "string", "null" ], "example": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "description": "图片URL。" }, "content": { "type": "array" }, "unit_items": { "$ref": "#/components/schemas/unit_items" } } }, "quantity": { "type": "number", "description": "商品数量。", "default": 1 } } }, "Promotions_sku": { "type": "string", "example": "booster_mega_1", "description": "唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。" }, "Promotions_name": { "type": "object", "description": "商品名称。应包含键/值对，\n其中键是\"^[a-z]{2}-[A-Z]{2}$\"格式的区域设置，值是字符串。", "additionalProperties": { "type": "string" }, "example": { "en-US": "Item title", "de-DE": "Artikeltitel" }, "default": { "en-US": "Item title", "de-DE": "Artikeltitel" } }, "Promotions_type": { "type": "string", "description": "商品类型：`virtual_good`/`virtual_currency`/`bundle`/`physical_good`/`unit`。" }, "Promotions_redeem_code_limit": { "type": [ "integer", "null" ], "description": "每个代码的核销次数。", "example": 10, "default": 10 }, "Promotions_promotion_condition": { "type": [ "array", "null" ], "items": { "description": "用户因购买而获得赠品的商品列表。", "type": "object", "properties": { "item": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/Promotions_sku" }, "name": { "$ref": "#/components/schemas/Promotions_name" }, "type": { "$ref": "#/components/schemas/Promotions_type" }, "description": { "type": [ "string", "null" ], "example": "Game description", "description": "Item description." }, "image_url": { "type": [ "string", "null" ], "example": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "description": "图片URL。" }, "external_id": { "type": "string", "description": "促销活动外部ID。项目内的唯一促销活动标识符。", "minLength": 1, "maxLength": 255, "pattern": "^[-_.\\d\\w]+$" }, "is_enabled": { "type": "boolean" }, "redeem_total_limit": { "type": [ "integer", "null" ] }, "redeem_user_limit": { "type": [ "integer", "null" ] }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" } } } } } }, "Promotions_coupon-is_enabled": { "type": "boolean", "default": true }, "Promotions_promotion_type": { "type": "string", "description": "促销活动类型。", "example": "item_discount" }, "Promotions_promotion_discount_percent": { "type": [ "string", "null" ], "description": "百分比折扣。\n购物车价格将按照此百分比打折，然后四舍五入到小数点后两位。", "default": "10.00", "example": "10.00" }, "promotion_recurrent_schedule_response": { "type": [ "object", "null" ], "description": "限制数刷新周期。", "properties": { "per_user": { "type": [ "object", "null" ], "description": "用户的限制数刷新周期。", "oneOf": [ { "type": "object", "title": "interval_type = daily", "description": "Daily type of user limits refresh.", "properties": { "interval_type": { "type": "string", "description": "Recurrent refresh period type.", "enum": [ "daily" ] }, "time": { "type": "string", "description": "Time of limit refresh in the desired time zone (rounding to hours).", "format": "full-time", "example": "11:00:00+03:00" }, "reset_next_date": { "type": "integer", "description": "Date and time when limits refresh (Unix Timestamp).", "example": 1677553200 }, "displayable_reset_start_date": { "description": "Date and time of the first limit refresh (ISO 8601).", "type": "string", "format": "date-time", "example": "2023-02-28T11:00:00+08:00" }, "displayable_reset_next_date": { "description": "Date and time when limits should reset (ISO 8601).", "type": "string", "format": "date-time", "example": "2023-02-28T11:00:00+08:00" } } }, { "type": "object", "title": "interval_type = weekly", "description": "Weekly type of user limits refresh.", "properties": { "interval_type": { "type": "string", "description": "Recurrent refresh period type.", "enum": [ "weekly" ] }, "day_of_week": { "type": [ "integer", "null" ], "description": "Day of the week when the limits refresh. Where 1 is Monday and 7 is Sunday. Not `null` only for `weekly` limit refresh period type.", "minimum": 1, "maximum": 7 }, "time": { "type": "string", "description": "Time of limit refresh in the desired time zone (rounding to hours).", "format": "full-time", "example": "11:00:00+03:00" }, "reset_next_date": { "type": "integer", "description": "Date and time when limits refresh (Unix Timestamp).", "example": 1677553200 }, "displayable_reset_start_date": { "description": "Date and time of the first limit refresh (ISO 8601).", "type": "string", "format": "date-time", "example": "2023-02-28T11:00:00+08:00" }, "displayable_reset_next_date": { "description": "Date and time when limits should reset (ISO 8601).", "type": "string", "format": "date-time", "example": "2023-02-28T11:00:00+08:00" } } }, { "type": "object", "title": "interval_type = monthly", "description": "Monthly type of refresh of user limits.", "properties": { "interval_type": { "type": "string", "description": "Recurrent refresh period type.", "enum": [ "monthly" ] }, "day_of_month": { "type": [ "integer", "null" ], "description": "Day of the month when limits refresh. If there's no selected day of the month as it's shorter, then the refresh will occur on the last day of the month. Not `null` only for `monthly` limit refresh period type.", "minimum": 1, "maximum": 31 }, "time": { "type": "string", "description": "Time of limit refresh in the desired time zone (rounding to hours).", "format": "full-time", "example": "11:00:00+03:00" }, "reset_next_date": { "type": "integer", "description": "Date and time when limits refresh (Unix Timestamp).", "example": 1677553200 }, "displayable_reset_start_date": { "description": "Date and time of the first limit refresh (ISO 8601).", "type": "string", "format": "date-time", "example": "2023-02-28T11:00:00+08:00" }, "displayable_reset_next_date": { "description": "Date and time when limits should reset (ISO 8601).", "type": "string", "format": "date-time", "example": "2023-02-28T11:00:00+08:00" } } } ] } } }, "Promotions_promotion_limits_response": { "type": "object", "description": "促销活动限制。", "properties": { "per_user": { "type": [ "object", "null" ], "description": "针对单独用户的促销活动限制。", "properties": { "total": { "type": "integer", "description": "用户可购买的商品总数。您可以在发布商帐户中设置此数值，也可以使用商店实体的管理接口（limits对象）进行设置。", "example": 5 } } }, "per_item": { "type": [ "integer", "null" ], "description": "全局商品限制数。", "example": 10 }, "recurrent_schedule": { "$ref": "#/components/schemas/promotion_recurrent_schedule_response" } } }, "Promotions_200-get-promotion-model": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Promotions_promotion_id" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "bonus": { "type": "array", "items": { "$ref": "#/components/schemas/Promotions_200-coupon-bonus-reward" } }, "condition": { "$ref": "#/components/schemas/Promotions_promotion_condition" }, "is_enabled": { "$ref": "#/components/schemas/Promotions_coupon-is_enabled" }, "type": { "$ref": "#/components/schemas/Promotions_promotion_type" }, "discount": { "type": [ "object", "null" ], "properties": { "percent": { "$ref": "#/components/schemas/Promotions_promotion_discount_percent" } }, "example": { "discount": { "percent": "10.99" } } }, "limits": { "$ref": "#/components/schemas/Promotions_promotion_limits_response" } } }, "total_promotions_count": { "type": "integer", "description": "促销活动总数。" }, "active_promotions_count": { "type": "integer", "description": "进行中的促销活动的数量。" }, "inactive_promotions_count": { "type": "integer", "description": "已停用的促销活动的数量。" }, "Promotions_coupon-external_id": { "type": "string", "example": "coupon_external_id", "default": "coupon_external_id", "description": "唯一促销活动ID。 `external_id`只能包含大小写英文字母和数字字符、句点、破折号和下划线。" }, "Promotions_coupon_bonus": { "type": [ "array", "null" ], "items": { "description": "将作为赠品添加到用户购买中的商品列表。", "type": "object", "properties": { "sku": { "type": "string", "description": "商品SKU。", "default": "elven_shield" }, "quantity": { "type": "number", "description": "商品数量。", "default": 1 } } } }, "Promotions_coupon-redeem_total_limit": { "type": [ "integer", "null" ], "description": "限制优惠券的总数。", "example": 10, "default": 10 }, "Promotions_coupon-redeem_user_limit": { "type": [ "integer", "null" ], "description": "限制单个用户兑换的优惠券总数。", "example": 10, "default": 10 }, "Promotions_coupon_total_limit_state": { "type": [ "object", "null" ], "description": "每个唯一优惠券码的限制。", "properties": { "available": { "type": "integer", "description": "优惠券剩余可使用次数。", "example": 3 }, "reserved": { "type": "integer", "description": "优惠券预留数量。", "example": 3 }, "used": { "type": "integer", "description": "优惠券被使用的次数。", "example": 5 } } }, "Promotions_cart_item_discount": { "type": "string", "nullable": false, "description": "百分比折扣。\n\n购物车商品价格将按照此百分比打折，\n然后四舍五入到小数点后两位。", "default": "10.00", "example": "10.00" }, "admin-promotions_200-get-redeemable-coupon-promotion-model": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "bonus": { "$ref": "#/components/schemas/Promotions_coupon_bonus" }, "is_enabled": { "$ref": "#/components/schemas/Promotions_coupon-is_enabled" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" }, "total_limit_state": { "$ref": "#/components/schemas/Promotions_coupon_total_limit_state" }, "discount": { "type": [ "object", "null" ], "description": "仅适用于兑换码。", "properties": { "percent": { "type": [ "string", "null" ], "description": "百分比折扣。\n购物车价格将按照此百分比打折，然后四舍五入到小数点后两位。", "default": "10.00", "example": "10.00" } }, "example": { "discount": { "percent": "10.99" } } }, "discounted_items": { "type": [ "array", "null" ], "description": "通过兑换码享受折扣的商品列表。仅适用于兑换码。", "items": { "description": "购物车中特定商品的折扣。", "type": "object", "properties": { "sku": { "type": "string", "description": "商品SKU。", "default": "elven_shield" }, "discount": { "type": "object", "nullable": false, "properties": { "percent": { "$ref": "#/components/schemas/Promotions_cart_item_discount" } }, "required": [ "percent" ] } }, "required": [ "sku", "discount" ], "minItems": 1 } } } }, "Promotions_selected_unit_items": { "type": "object", "description": "用户选择作为赠品的平台对应游戏Key。将[收到的](/zh/api/liveops/promotions-coupons/get-coupon-rewards-by-code#promotions-coupons/get-coupon-rewards-by-code/t=response&c=200&path=bonus/item) `bonus.item.sku`作为键，将所选`bonus.item.unit_items.sku`作为其值。", "additionalProperties": { "type": "string" }, "example": { "game_1": "game_1_steam", "game_2": "game_2_playstation" } }, "Promotions_200-coupon-discount-reward": { "type": [ "object", "null" ], "description": "百分比折扣。\n购物车价格将按照此百分比打折，然后四舍五入到小数点后两位。", "properties": { "percent": { "type": "string", "example": "10.00" } } }, "Promotions_422_limit_error": { "description": "已达到兑换限制。", "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 9804 }, "errorMessage": { "type": "string", "example": "[0401-9804]: You have reached the coupon redemption limit." }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } }, "example": { "statusCode": 422, "errorCode": 9804, "errorMessage": "[0401-9804]: You have reached the coupon redemption limit." } }, "Promotions_422_reglock_error": { "description": "优惠券在用户所在区域不可用。", "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 9808 }, "errorMessage": { "type": "string", "example": "[0401-9808]: Coupon is not available in your region." }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } }, "example": { "statusCode": 422, "errorCode": 9804, "errorMessage": "[0401-9804]: You have reached the coupon redemption limit." } }, "user-attribute_conditions_properties_attribute": { "type": "string", "description": "用户属性代码。", "minLength": 1, "maxLength": 255, "pattern": "^[-_.\\d\\w]+$" }, "user-attribute_conditions_properties_type-string": { "type": "string", "enum": [ "string" ], "description": "用户属性类型。" }, "user-attribute_conditions_properties_operator_string": { "type": "string", "enum": [ "eq", "ne" ], "description": "按条件执行的操作类型。用于string属性类型。\n\n可能值：\n- `eq` — 等于\n- `ne` — 不等于" }, "user-attribute_conditions_properties_value": { "type": "string", "description": "与用户属性值进行比较的条件值。类型取决于属性类型。", "maxLength": 255 }, "user-attribute_conditions_properties_can_be_missing": { "type": "boolean", "description": "表示即使用户属性中缺少该属性，条件仍会被视为满足。传入`true`可向不具有此属性的用户显示该商品。具有该属性但属性值与条件中指定值不匹配的用户将看不到该商品。传入`false`时，具有该属性但属性值不匹配，或缺少该属性的用户都将看不到该商品。" }, "user-attribute_condition_string_model-get": { "type": "object", "title": "type = string", "properties": { "attribute": { "$ref": "#/components/schemas/user-attribute_conditions_properties_attribute" }, "type": { "$ref": "#/components/schemas/user-attribute_conditions_properties_type-string" }, "operator": { "$ref": "#/components/schemas/user-attribute_conditions_properties_operator_string" }, "value": { "$ref": "#/components/schemas/user-attribute_conditions_properties_value" }, "can_be_missing": { "$ref": "#/components/schemas/user-attribute_conditions_properties_can_be_missing" } } }, "user-attribute_conditions_properties_type-number": { "type": "string", "enum": [ "number" ], "description": "用户属性类型。" }, "user-attribute_conditions_properties_operator_number": { "type": "string", "enum": [ "eq", "ne", "gt", "ge", "lt", "le" ], "description": "按条件执行的操作类型。用于number属性类型。\n\n可能值：\n- `eq` — 等于\n- `ne` — 不等于\n- `gt` — 大于\n- `ge` — 大于或等于\n- `lt` — 小于\n- `le` — 小于或等于" }, "user-attribute_condition_number_model-get": { "type": "object", "title": "type = number", "properties": { "attribute": { "$ref": "#/components/schemas/user-attribute_conditions_properties_attribute" }, "type": { "$ref": "#/components/schemas/user-attribute_conditions_properties_type-number" }, "operator": { "$ref": "#/components/schemas/user-attribute_conditions_properties_operator_number" }, "value": { "$ref": "#/components/schemas/user-attribute_conditions_properties_value" }, "can_be_missing": { "$ref": "#/components/schemas/user-attribute_conditions_properties_can_be_missing" } } }, "user-attribute_conditions_properties_type-date": { "type": "string", "enum": [ "date" ], "description": "用户属性类型。" }, "user-attribute_conditions_properties_operator_date": { "type": "string", "enum": [ "eq", "ne", "lt", "gt", "le", "ge" ], "description": "按条件执行的操作类型。用于date属性类型。\n\n可能值：\n- `eq` — 等于\n- `ne` — 不等于\n- `lt` — 早于\n- `gt` — 晚于\n- `le` — 早于或等于\n- `ge` — 晚于或等于" }, "user-attribute_condition_date_model-get": { "type": "object", "title": "type = date", "properties": { "attribute": { "$ref": "#/components/schemas/user-attribute_conditions_properties_attribute" }, "type": { "$ref": "#/components/schemas/user-attribute_conditions_properties_type-date" }, "operator": { "$ref": "#/components/schemas/user-attribute_conditions_properties_operator_date" }, "value": { "$ref": "#/components/schemas/user-attribute_conditions_properties_value" }, "can_be_missing": { "$ref": "#/components/schemas/user-attribute_conditions_properties_can_be_missing" } } }, "user-attribute_conditions_model-get": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "$ref": "#/components/schemas/user-attribute_condition_string_model-get" }, { "$ref": "#/components/schemas/user-attribute_condition_number_model-get" }, { "$ref": "#/components/schemas/user-attribute_condition_date_model-get" } ] } }, "promotion_user-attribute_conditions_model-get": { "allOf": [ { "$ref": "#/components/schemas/user-attribute_conditions_model-get" }, { "description": "Conditions for validating user attributes.\nDetermine promotion availability based on whether user attributes match all specified conditions.\n" } ] }, "admin-promotions_200-get-coupon-promotion-model": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "bonus": { "$ref": "#/components/schemas/Promotions_coupon_bonus" }, "is_enabled": { "$ref": "#/components/schemas/Promotions_coupon-is_enabled" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" }, "total_limit_state": { "$ref": "#/components/schemas/Promotions_coupon_total_limit_state" }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-get" } } }, "user-attribute_condition_string_model-post": { "type": "object", "title": "type = string", "properties": { "attribute": { "$ref": "#/components/schemas/user-attribute_conditions_properties_attribute" }, "type": { "$ref": "#/components/schemas/user-attribute_conditions_properties_type-string" }, "operator": { "$ref": "#/components/schemas/user-attribute_conditions_properties_operator_string" }, "value": { "$ref": "#/components/schemas/user-attribute_conditions_properties_value" }, "can_be_missing": { "$ref": "#/components/schemas/user-attribute_conditions_properties_can_be_missing" } }, "required": [ "attribute", "operator", "value", "type" ] }, "user-attribute_condition_number_model-post": { "type": "object", "title": "type = number", "properties": { "attribute": { "$ref": "#/components/schemas/user-attribute_conditions_properties_attribute" }, "type": { "$ref": "#/components/schemas/user-attribute_conditions_properties_type-number" }, "operator": { "$ref": "#/components/schemas/user-attribute_conditions_properties_operator_number" }, "value": { "$ref": "#/components/schemas/user-attribute_conditions_properties_value" }, "can_be_missing": { "$ref": "#/components/schemas/user-attribute_conditions_properties_can_be_missing" } }, "required": [ "attribute", "operator", "value", "type" ] }, "user-attribute_condition_date_model-post": { "type": "object", "title": "type = date", "properties": { "attribute": { "$ref": "#/components/schemas/user-attribute_conditions_properties_attribute" }, "type": { "$ref": "#/components/schemas/user-attribute_conditions_properties_type-date" }, "operator": { "$ref": "#/components/schemas/user-attribute_conditions_properties_operator_date" }, "value": { "$ref": "#/components/schemas/user-attribute_conditions_properties_value" }, "can_be_missing": { "$ref": "#/components/schemas/user-attribute_conditions_properties_can_be_missing" } }, "required": [ "attribute", "operator", "value", "type" ] }, "user-attribute_conditions_model-post": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "$ref": "#/components/schemas/user-attribute_condition_string_model-post" }, { "$ref": "#/components/schemas/user-attribute_condition_number_model-post" }, { "$ref": "#/components/schemas/user-attribute_condition_date_model-post" } ] } }, "promotion_user-attribute_conditions_model-post": { "allOf": [ { "$ref": "#/components/schemas/user-attribute_conditions_model-post" }, { "description": "Conditions for validating user attributes.\nDetermine promotion availability based on whether user attributes match all specified conditions.\n" } ] }, "Promotions_coupon_code": { "type": "string", "description": "区分大小写的唯一兑换码。包含字母和数字。", "minLength": 1, "maxLength": 128, "example": "WINTER2021", "default": "WINTER2021", "pattern": "^[a-zA-Z0-9]+$" }, "Promotions_coupon-generate-count": { "type": "integer", "minimum": 1, "maximum": 50000, "example": 10 }, "value-is_free": { "type": "boolean", "example": false, "default": false, "description": "该商品是否免费。" }, "Catalog_item_promotions": { "type": "array", "description": "应用于购物车中指定商品的促销活动。仅在以下情况下返回该数组：\n\n* 为某商品配置了折扣促销活动。\n\n* 应用了具有**对所选商品提供折扣**设置的兑换码。\n\n如果未应用任何商品级促销活动，则返回空数组。", "items": { "type": "object", "properties": { "name": { "type": "string" }, "date_start": { "type": [ "string", "null" ], "format": "date-time" }, "date_end": { "type": [ "string", "null" ], "format": "date-time" }, "discount": { "type": [ "object", "null" ], "properties": { "percent": { "type": [ "string", "null" ] }, "value": { "type": [ "string", "null" ] } } }, "bonus": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "integer" }, "type": { "type": "string", "description": "赠品类型。", "enum": [ "virtual_good", "virtual_currency", "bundle", "physical_good", "game_key", "nft" ] }, "name": { "type": "string", "description": "赠品名称。不适用于`physical_good`赠品类型。" }, "image_url": { "type": "string", "description": "赠品图片URL。不适用于`physical_good`赠品类型。" }, "bundle_type": { "type": "string", "description": "赠品捆绑包商品类型。仅适用于`bundle`赠品类型。", "enum": [ "standard", "virtual_currency_package" ] } } } }, "limits": { "type": "object", "properties": { "per_user": { "type": "object", "properties": { "available": { "type": "integer" }, "total": { "type": "integer" } } } } } } } }, "Can_be_bought": { "type": "boolean", "example": true, "description": "如为`true`，则用户可以购买商品。" }, "item_id": { "type": "integer", "example": 1, "description": "内部唯一商品ID。" }, "value-point-sku": { "type": "string", "description": "唯一累充积分ID。" }, "value-point-amount": { "type": "integer", "description": "累充积分数量。" }, "value-point-name": { "type": "string", "description": "累充积分名称。" }, "Common_admin-image_url": { "type": "string", "example": "https://image.example.com", "description": "图片URL。" }, "is_clan": { "type": "boolean", "description": "累充积分是否用于公会累充奖励链。", "example": true }, "client-item-value-point-reward": { "type": "array", "description": "累充积分商品奖励。", "items": { "type": "object", "properties": { "item_id": { "$ref": "#/components/schemas/item_id" }, "sku": { "$ref": "#/components/schemas/value-point-sku" }, "amount": { "$ref": "#/components/schemas/value-point-amount" }, "name": { "$ref": "#/components/schemas/value-point-name" }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "is_clan": { "$ref": "#/components/schemas/is_clan" } } } }, "catalog_recurrent_schedule_client_response": { "type": [ "object", "null" ], "description": "用户的商品限制循环刷新周期。", "oneOf": [ { "type": "object", "title": "interval_type = daily", "description": "Daily type of user limits refresh.", "properties": { "interval_type": { "type": "string", "description": "Recurrent refresh period type.", "enum": [ "daily" ] }, "reset_next_date": { "type": "integer", "description": "Date and time when limits reset (Unix Timestamp).", "example": 1677553200 } } }, { "type": "object", "title": "interval_type = weekly", "description": "Weekly type of user limits refresh.", "properties": { "interval_type": { "type": "string", "description": "Recurrent refresh period type.", "enum": [ "weekly" ] }, "reset_next_date": { "type": "integer", "description": "Date and time when limits reset (Unix Timestamp).", "example": 1677553200 } } }, { "type": "object", "title": "interval_type = monthly", "description": "Monthly type of refresh of user limits.", "properties": { "interval_type": { "type": "string", "description": "Recurrent refresh period type.", "enum": [ "monthly" ] }, "reset_next_date": { "type": "integer", "description": "Date and time when limits reset (Unix Timestamp).", "example": 1677553200 } } }, { "type": "object", "title": "interval_type = hourly", "description": "Reset of the user limits performed at the specified time interval in hours.", "properties": { "interval_type": { "type": "string", "description": "Recurrent refresh period type.", "enum": [ "hourly" ] }, "reset_next_date": { "type": "integer", "description": "Date and time when limits reset (Unix Timestamp).", "example": 1677553200 } } } ] }, "limit_exceeded_visibility": { "type": "string", "example": "show", "enum": [ "show", "hide" ], "description": "设定商品在达到购买限制后、下次限制重置前在商品目录中的可见性。\n\n适用于在recurrent_schedule数组中配置了周期性重置数量限制的商品。\n\n如果未配置重置限制，则达到购买限制后，无论`limit_exceeded_visibility`的值如何，该商品都不会显示在商品目录中。\n\n可能值：\n- `show` — 达到购买限制后，商品目录检索API调用仍会返回该商品。在客户端侧\n商品目录检索API调用中，达到限制后返回的商品会带有`can_be_bought: false` 标志。下一次重置日期\n将在`reset_next_date`中返回。\n- `hide` — 达到购买限制后，在限制\n重置之前，商品目录检索API调用不会返回该商品。", "default": "show" }, "Catalog_item_limits": { "description": "商品限制数。", "properties": { "per_user": { "type": [ "object", "null" ], "description": "单个用户的商品购买数量限制。", "properties": { "total": { "type": "integer", "description": "单个用户可购买的最大商品数量。", "example": 5 }, "available": { "type": "integer", "description": "当前用户可购买的剩余商品数量。", "example": 3 }, "recurrent_schedule": { "$ref": "#/components/schemas/catalog_recurrent_schedule_client_response" }, "limit_exceeded_visibility": { "$ref": "#/components/schemas/limit_exceeded_visibility" } } }, "per_item": { "type": [ "object", "null" ], "description": "单个商品的购买数量限制。", "properties": { "total": { "type": "integer", "description": "所有用户可购买的最大商品数量。", "example": 5 }, "available": { "type": "integer", "description": "所有用户还可购买的剩余商品数量。", "example": 3 } } } }, "type": [ "object", "null" ] }, "item-periods": { "type": [ "array", "null" ], "description": "商品销售期。", "items": { "type": "object", "properties": { "date_from": { "type": "string", "format": "date-time", "example": "2020-08-11T10:00:00+03:00", "description": "指定商品开始可购的日期。" }, "date_until": { "type": [ "string", "null" ], "format": "date-time", "example": "2020-08-11T20:00:00+03:00", "description": "指定商品停止可购的日期。可为`null`。" } } } }, "Promotions_200-promo-code-bonus-reward": { "type": "object", "properties": { "item": { "type": "object", "properties": { "sku": { "type": "string", "example": "game_01", "description": "唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。" }, "name": { "type": "string", "example": "Game name", "description": "商品名称。" }, "type": { "type": "string", "example": "unit", "description": "商品类型。可能值：
  • virtual_good — 虚拟物品
  • virtual_currency — 虚拟货币
  • bundle — 捆绑包
  • unit — 游戏Key套餐
" }, "description": { "type": "string", "example": "Game description", "description": "Item description." }, "image_url": { "type": "string", "example": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "description": "图片URL。" }, "unit_items": { "$ref": "#/components/schemas/unit_items" } } }, "quantity": { "type": "number", "description": "商品数量。", "default": 1 } } }, "Promotions_discounted_items": { "type": [ "array", "null" ], "description": "通过兑换码享受折扣的商品列表。", "items": { "description": "购物车中特定商品的折扣。", "type": "object", "properties": { "sku": { "type": "string", "description": "商品SKU。", "default": "elven_shield" }, "discount": { "type": "object", "nullable": false, "properties": { "percent": { "$ref": "#/components/schemas/Promotions_cart_item_discount" } }, "required": [ "percent" ] } }, "required": [ "sku", "discount" ], "minItems": 1 } }, "Promo_code_rewards": { "type": "object", "properties": { "bonus": { "type": "array", "items": { "$ref": "#/components/schemas/Promotions_200-promo-code-bonus-reward" } }, "discount": { "$ref": "#/components/schemas/Promotions_200-coupon-discount-reward" }, "discounted_items": { "$ref": "#/components/schemas/Promotions_discounted_items" }, "is_selectable": { "type": "boolean", "description": "如果为`true`，则用户应在核销兑换码前选择赠品。" } } }, "admin-attribute-external_id": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z0-9-_]+$", "example": "attribute_1", "description": "唯一属性ID。 `external_id`只能包含大小写英文字母、数字、短横线和下划线。" }, "value-external_id": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[-_.\\d\\w]+$", "example": "attribute_value", "description": "属性的唯一值ID。 `external_id`只能包含小写英文字母、数字、短横线和下划线。" }, "client-attributes": { "type": "array", "description": "与商品对应的属性及其值的列表。可用于商品目录筛选。", "example": { "value": { "external_id": "genre", "name": "Жанр", "values": [ { "external_id": "genre_e3364991f92e751689a68b96598a5a5a84010b85", "value": "Casual" }, { "external_id": "genre_eba07bfd0f982940773cba3744d97264dd58acd7", "value": "Strategy" }, { "external_id": "genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8", "value": "Mobile" } ] } }, "default": [], "items": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/admin-attribute-external_id" }, "name": { "type": "string", "description": "属性名称。", "example": "Genre" }, "values": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/value-external_id" }, "value": { "type": "string", "description": "属性值。", "example": "Strategy" } } } } } } }, "Promotions_promocode_total_limit_state": { "type": [ "object", "null" ], "description": "每个唯一兑换码的限制。", "properties": { "available": { "type": "integer", "description": "兑换码的剩余可用次数。", "example": 3 }, "reserved": { "type": "integer", "description": "兑换码的预留数量。", "example": 3 }, "used": { "type": "integer", "description": "兑换码被使用的次数。", "example": 5 } } }, "price_conditions_items": { "description": "每个对象描述一条价格应遵循的规则。", "type": "object", "properties": { "operator": { "type": "string", "description": "用于设置应用促销活动的价格范围的比较运算符。\n\n可能值：\n- `ge` — 大于或等于\n- `gt` — 大于\n- `le` — 小于或等于\n- `lt` — 小于\n- `eq` — 等于\n- `ne` — 不等于", "enum": [ "ge", "gt", "le", "lt", "eq", "ne" ] }, "value": { "type": "string", "description": "用于决定应用促销活动的价格范围的值。", "pattern": "^\\d+(\\.\\d{1,4})?$" } }, "required": [ "operator", "value" ] }, "price_conditions_promocode": { "type": [ "array", "null" ], "description": "包含条件的对象数组，用于设置对整个购物车应用促销活动的价格范围。
\n系统会将用户购物车中所有商品的总价与条件中指定的价格范围进行比较。如果购物车价格满足指定条件，则会对购物车中的所有商品应用[赠品](/zh/api/shop-builder/operation/create-promo-code/#!path=bonus&t=request)和[折扣](/zh/api/shop-builder/operation/create-promo-code/#!path=discount&t=request)
\n如果传入此数组，请将[discounted_items](/zh/api/shop-builder/operation/create-promo-code/#!path=discounted_items&t=request)数组的值设置为`null`。", "items": { "$ref": "#/components/schemas/price_conditions_items" } }, "item_price_conditions_promocode": { "type": [ "array", "null" ], "description": "包含条件的对象数组，用于设置对购物车中特定商品应用促销活动的价格范围。
\n系统会将用户购物车中每个商品的价格与条件中指定的价格范围进行比较。只有购物车中价格满足条件的商品才会应用[赠品](/zh/api/shop-builder/operation/create-promo-code/#!path=bonus&t=request)和[折扣](/zh/api/shop-builder/operation/create-promo-code/#!path=discount&t=request)
\n如果传入此数组，请将[discounted_items](/zh/api/shop-builder/operation/create-promo-code/#!path=discounted_items&t=request)数组的值设置为`null`。", "items": { "$ref": "#/components/schemas/price_conditions_items" } }, "excluded_promotions": { "type": "array", "items": { "type": "integer" }, "example": [ 12, 789 ], "description": "应用此促销活动时要排除的促销活动ID列表。
示例：`[12, 789]`" }, "Promotions_200-get-promocode-promotion-model": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "bonus": { "$ref": "#/components/schemas/Promotions_coupon_bonus" }, "is_enabled": { "$ref": "#/components/schemas/Promotions_coupon-is_enabled" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" }, "discount": { "type": [ "object", "null" ], "properties": { "percent": { "$ref": "#/components/schemas/Promotions_promotion_discount_percent" } }, "example": { "discount": { "percent": "10.99" } } }, "discounted_items": { "$ref": "#/components/schemas/Promotions_discounted_items" }, "total_limit_state": { "$ref": "#/components/schemas/Promotions_promocode_total_limit_state" }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-get" }, "price_conditions": { "$ref": "#/components/schemas/price_conditions_promocode" }, "item_price_conditions": { "$ref": "#/components/schemas/item_price_conditions_promocode" }, "excluded_promotions": { "$ref": "#/components/schemas/excluded_promotions" } } }, "Promotions_is_enabled": { "type": "boolean", "example": true, "description": "是否启用了促销活动。" }, "price_conditions_discount": { "type": [ "array", "null" ], "description": "具有设置促销价格范围的条件的对象数组。
促销仅适用于价格符合数组中所有条件的商品。如果传递此数组，请设置[items](/zh/api/shop-builder/operation/create-item-promotion/#!path=items&t=request)对象为`null`。", "items": { "$ref": "#/components/schemas/price_conditions_items" } }, "Promotions_promotion_limits": { "type": "object", "description": "促销活动限制。", "properties": { "per_user": { "type": [ "integer", "null" ], "description": "针对单独用户的促销活动限制。" }, "recurrent_schedule": { "$ref": "#/components/schemas/promotion_recurrent_schedule_response" } } }, "price_conditions_bonus": { "type": [ "array", "null" ], "description": "包含条件的对象数组，用于设置应用促销活动的价格范围。
促销活动仅应用于价格符合数组中所有条件的商品。如果传递此数组，请将[condition](/zh/api/shop-builder/operation/create-bonus-promotion/#!path=condition&t=request)对象的值设置为`null`。", "items": { "$ref": "#/components/schemas/price_conditions_items" } }, "Promotions_200-get-bonus-promotion-model": { "type": "object", "properties": { "id": { "type": "integer", "description": "促销活动ID。项目内的唯一促销活动标识符。" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "type": "object", "description": "促销活动名称。应包含键/值对，\n其中键是\"^[a-z]{2}-[A-Z]{2}$\"格式的区域设置，值是字符串。", "additionalProperties": { "type": "string" }, "example": { "en-US": "Summer season bonus", "de-DE": "Sommersaison Bonus" } }, "is_enabled": { "type": "boolean", "default": true }, "condition": { "type": [ "array", "null" ], "description": "要应用促销必须在购买项中包含的一组商品。如果此参数为`null`，则促销将应用于项目内的任何购买。", "items": { "type": "object", "properties": { "sku": { "type": "string", "description": "商品SKU。", "default": "elven_sword" } } } }, "bonus": { "type": [ "array", "null" ], "items": { "description": "将作为赠品添加到用户购买中的商品列表。", "type": "object", "properties": { "sku": { "type": "string", "description": "商品SKU。", "default": "elven_shield" }, "quantity": { "type": "number", "description": "商品数量。", "default": 1 } } } }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-get" }, "limits": { "$ref": "#/components/schemas/Promotions_promotion_limits_response" }, "excluded_promotions": { "$ref": "#/components/schemas/excluded_promotions" }, "price_conditions": { "$ref": "#/components/schemas/price_conditions_bonus" } } }, "Coupon_rewards": { "type": "object", "properties": { "bonus": { "type": "array", "items": { "$ref": "#/components/schemas/Promotions_200-coupon-bonus-reward" } }, "is_selectable": { "type": "boolean", "description": "如为`true`，用户应在核销优惠券前选择一个赠品。" } } }, "Promotions_discounted_items_verify": { "type": [ "array", "null" ], "description": "通过兑换码享受折扣的商品列表。", "items": { "description": "特定商品的折扣。", "type": "object", "properties": { "sku": { "type": "string", "example": "game_01", "description": "唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。" }, "name": { "type": "string", "example": "Game name", "description": "商品名称。" }, "type": { "type": "string", "example": "unit", "description": "商品类型。可能值：
  • virtual_good — 虚拟物品
  • virtual_currency — 虚拟货币
  • bundle — 捆绑包
  • unit — 游戏Key套餐
" }, "description": { "type": "string", "example": "Game description", "description": "Item description." }, "image_url": { "type": "string", "example": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "description": "图片URL。" }, "unit_items": { "$ref": "#/components/schemas/unit_items" }, "discount": { "type": "object", "nullable": false, "properties": { "percent": { "$ref": "#/components/schemas/Promotions_cart_item_discount" } } } } } }, "Promo_code_rewards_verify": { "type": "object", "properties": { "bonus": { "type": "array", "items": { "$ref": "#/components/schemas/Promotions_200-promo-code-bonus-reward" } }, "discount": { "$ref": "#/components/schemas/Promotions_200-coupon-discount-reward" }, "discounted_items": { "$ref": "#/components/schemas/Promotions_discounted_items_verify" }, "is_selectable": { "type": "boolean", "description": "如果为`true`，则用户应在核销兑换码前选择赠品。" } } }, "sku": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z0-9_\\-–.]*$", "example": "booster_mega_1", "description": "唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。" }, "Promotions_unique_catalog_offer_items": { "type": "array", "description": "使用专属商品目录优惠后可用的商品SKU列表。", "items": { "$ref": "#/components/schemas/sku" } }, "Promotions_200-get-unique-catalog-offer-promotion-model": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "items": { "$ref": "#/components/schemas/Promotions_unique_catalog_offer_items" }, "is_enabled": { "$ref": "#/components/schemas/Promotions_coupon-is_enabled" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" }, "total_limit_state": { "$ref": "#/components/schemas/Promotions_coupon_total_limit_state" } } }, "Promotions_coupon_date_start": { "type": [ "string", "null" ], "format": "date-time", "default": "2020-04-15T18:16:00+05:00", "description": "促销活动开始日期。" }, "Promotions_coupon_date_end": { "type": [ "string", "null" ], "format": "date-time", "default": "2020-04-15T18:16:00+05:00", "description": "促销活动结束日期。可以是`null`。如果`date_end` 为`null`，则促销活动无时间限制。" }, "User-limit-promo-code": { "type": "object", "properties": { "per_user": { "type": "object", "properties": { "total": { "type": "integer", "example": 10, "description": "用户可使用兑换码的最大次数。" }, "available": { "type": "integer", "example": 9, "description": "用户可使用兑换码的剩余次数。" } } } } }, "User-limit-coupon": { "type": "object", "properties": { "per_user": { "type": "object", "properties": { "total": { "type": "integer", "example": 10, "description": "用户可以使用优惠券的最大次数。" }, "available": { "type": "integer", "example": 9, "description": "用户可以使用优惠券的剩余次数。" } } } } }, "Code-limit-promo-code": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Promotions_coupon_code" }, "per_code": { "type": "object", "properties": { "total": { "type": "integer", "description": "兑换码可使用的最大次数。" }, "available": { "type": "integer", "description": "兑换码的剩余可用次数。" }, "used": { "type": "integer", "description": "兑换码被使用的次数。" }, "reserved": { "type": "integer", "description": "兑换码的预留次数。" } } } } }, "personalized-catalog_user-attribute_conditions_model-get": { "allOf": [ { "$ref": "#/components/schemas/user-attribute_conditions_model-get" }, { "description": "Conditions for validating user attributes.\nDetermine item availability in the catalog based on whether user attributes match all specified conditions.\n" } ] }, "user-attribute_personalized-catalog": { "type": "object", "properties": { "rule_id": { "type": "number", "description": "规则ID。" }, "name": { "type": "string", "description": "规则的可读名称。用于在发布商帐户中显示规则。" }, "is_enabled": { "type": "boolean", "description": "如果已启用规则。" }, "is_satisfied_for_unauth": { "type": "boolean", "description": "是否向未经授权的用户显示该商品。如为`true`，无论商品目录显示规则如何，该商品都会向未经授权的用户显示。默认为`false`。" }, "attribute_conditions": { "$ref": "#/components/schemas/personalized-catalog_user-attribute_conditions_model-get" }, "items": { "type": "array", "items": { "type": "object", "description": "用户的属性值满足条件的情况下显示给用户的商品。", "properties": { "item_id": { "type": "number", "description": "商品ID。" }, "sku": { "type": "string", "description": "商品SKU。" }, "name": { "type": "string", "description": "商品名称。" }, "type": { "type": "string", "description": "商品类型。", "enum": [ "virtual_good", "virtual_currency", "bundle", "physical_good", "unit" ] }, "bundle_type": { "type": "string", "description": "捆绑包类型。当商品类型为捆绑包时返回。", "enum": [ "standard", "virtual_currency_package" ] } } } } }, "required": [ "rule_id", "name", "is_enabled", "attribute_conditions", "items" ] }, "personalized-catalog_user-attribute_conditions_model-post": { "allOf": [ { "$ref": "#/components/schemas/user-attribute_conditions_model-post" }, { "description": "Conditions for validating user attributes.\nDetermine item availability in the catalog based on whether user attributes match all specified conditions.\n" } ] }, "user-attribute_personalized-catalog-body-required": { "type": "object", "properties": { "name": { "type": "string", "description": "规则的可读名称。用于在发布商帐户中显示规则。", "minLength": 1, "maxLength": 255, "pattern": "^\\S" }, "is_enabled": { "type": "boolean", "description": "如果已启用规则。" }, "is_satisfied_for_unauth": { "type": "boolean", "description": "是否向未经授权的用户显示该商品。如为`true`，无论商品目录显示规则如何，该商品都会向未经授权的用户显示。默认为`false`。" }, "attribute_conditions": { "$ref": "#/components/schemas/personalized-catalog_user-attribute_conditions_model-post" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "type": "object", "description": "Items which are shown to a user if their attribute values meet conditions.", "properties": { "item_id": { "type": "number", "description": "商品ID。" } }, "required": [ "item_id" ] }, { "type": "object", "description": "Items which are shown to a user if their attribute values meet conditions.", "properties": { "sku": { "type": "string", "description": "商品SKU。" } }, "required": [ "sku" ] } ] } } }, "required": [ "name", "is_enabled", "attribute_conditions", "items" ] }, "422-invalid-request": { "type": "object", "properties": { "statusCode": { "type": "number", "description": "响应状态码。", "example": 422 }, "errorCode": { "type": "number", "description": "错误代码。", "example": 1102 }, "errorMessage": { "type": "string", "description": "可读的错误消息。", "example": "[0401-1102]: Unprocessable Entity. The property `external_id` is required" }, "transactionId": { "type": "string", "description": "请求的唯一ID。", "example": "da145238620011eb8e24fe6913ff226a" } } }, "user-attribute_personalized-catalog_all": { "type": "object", "properties": { "rule_id": { "type": "number", "description": "规则ID。" }, "name": { "type": "string", "description": "规则的可读名称。用于在发布商帐户中显示规则。" }, "is_enabled": { "type": "boolean", "description": "如果已启用规则。" }, "is_satisfied_for_unauth": { "type": "boolean", "description": "是否向未经授权的用户显示该商品。如为`true`，无论商品目录显示规则如何，该商品都会向未经授权的用户显示。默认为`false`。" } }, "required": [ "rule_id", "name", "is_enabled" ] }, "user-attribute_personalized-catalog-body": { "type": "object", "properties": { "name": { "type": "string", "description": "规则的可读名称。用于在发布商帐户中显示规则。", "minLength": 1, "maxLength": 255, "pattern": "^\\S" }, "is_enabled": { "type": "boolean", "description": "如果已启用规则。" }, "is_satisfied_for_unauth": { "type": "boolean", "description": "是否向未经授权的用户显示该商品。如为`true`，无论商品目录显示规则如何，该商品都会向未经授权的用户显示。默认为`false`。" }, "attribute_conditions": { "$ref": "#/components/schemas/personalized-catalog_user-attribute_conditions_model-post" }, "items": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "type": "object", "description": "Items which are shown to a user if their attribute values meet conditions.", "properties": { "item_id": { "type": "number", "description": "商品ID。" } }, "required": [ "item_id" ] }, { "type": "object", "description": "Items which are shown to a user if their attribute values meet conditions.", "properties": { "sku": { "type": "string", "description": "商品SKU。" } }, "required": [ "sku" ] } ] } } } }, "User-limit_user-external-id": { "description": "用户外部ID。", "type": "string", "minLength": 1, "pattern": "^\\S+$" }, "User-limit_user": { "type": "object", "properties": { "user_external_id": { "$ref": "#/components/schemas/User-limit_user-external-id" } }, "required": [ "user_external_id" ] }, "User-limit_user_flexible": { "type": [ "object", "null" ], "properties": { "user_external_id": { "$ref": "#/components/schemas/User-limit_user-external-id" } } }, "User-limit-promotion": { "type": "object", "properties": { "per_user": { "type": "object", "properties": { "total": { "type": "integer", "example": 10, "description": "用户可以使用促销活动的最大次数。" }, "available": { "type": "integer", "example": 9, "description": "用户可以使用促销活动的剩余次数。" } } } } }, "User-limit_available_flexible": { "type": "integer", "minimum": 0, "description": "在已应用的限制内，用户还可购买的商品数量或还可使用促销活动的次数。" }, "User-limit_available": { "type": "integer", "minimum": 1, "description": "在已应用的限制内，用户还可购买的商品数量或还可使用促销活动的次数。" }, "two-letter-locale": { "type": [ "object", "null" ], "description": "两个小写字母的语言代码。", "title": "two-letter", "properties": { "en": { "type": [ "string", "null" ], "description": "英语" }, "ar": { "type": [ "string", "null" ], "description": "阿拉伯语" }, "bg": { "type": [ "string", "null" ], "description": "保加利亚语" }, "cn": { "type": [ "string", "null" ], "description": "中文（简体）" }, "cs": { "type": [ "string", "null" ], "description": "捷克语" }, "de": { "type": [ "string", "null" ], "description": "德语" }, "es": { "type": [ "string", "null" ], "description": "西班牙语（西班牙）" }, "fr": { "type": [ "string", "null" ], "description": "法语" }, "he": { "type": [ "string", "null" ], "description": "希伯来语" }, "it": { "type": [ "string", "null" ], "description": "意大利语" }, "ja": { "type": [ "string", "null" ], "description": "日语" }, "ko": { "type": [ "string", "null" ], "description": "韩语" }, "pl": { "type": [ "string", "null" ], "description": "波兰语" }, "pt": { "type": [ "string", "null" ], "description": "葡萄牙语" }, "ro": { "type": [ "string", "null" ], "description": "罗马尼亚语" }, "ru": { "type": [ "string", "null" ], "description": "俄语" }, "th": { "type": [ "string", "null" ], "description": "泰语" }, "tr": { "type": [ "string", "null" ], "description": "土耳其语" }, "tw": { "type": [ "string", "null" ], "description": "中文（繁体）" }, "vi": { "type": [ "string", "null" ], "description": "越南语" }, "km": { "type": [ "string", "null" ], "description": "高棉语" }, "id": { "type": [ "string", "null" ], "description": "印度尼西亚语" }, "lo": { "type": [ "string", "null" ], "description": "老挝语" }, "my": { "type": [ "string", "null" ], "description": "缅甸语" }, "ph": { "type": [ "string", "null" ], "description": "菲律宾语" }, "ne": { "type": [ "string", "null" ], "description": "尼泊尔语" } } }, "five-letter-locale": { "type": [ "object", "null" ], "description": "五个字符的区域设置代码。", "title": "five-letter", "properties": { "en-US": { "type": [ "string", "null" ], "description": "英语" }, "ar-AE": { "type": [ "string", "null" ], "description": "阿拉伯语" }, "bg-BG": { "type": [ "string", "null" ], "description": "保加利亚语" }, "zh-CN": { "type": [ "string", "null" ], "description": "中文（简体）" }, "cs-CZ": { "type": [ "string", "null" ], "description": "捷克语" }, "de-DE": { "type": [ "string", "null" ], "description": "德语" }, "es-ES": { "type": [ "string", "null" ], "description": "西班牙语（西班牙）" }, "fr-FR": { "type": [ "string", "null" ], "description": "法语" }, "he-IL": { "type": [ "string", "null" ], "description": "希伯来语" }, "it-IT": { "type": [ "string", "null" ], "description": "意大利语" }, "ja-JP": { "type": [ "string", "null" ], "description": "日语" }, "ko-KR": { "type": [ "string", "null" ], "description": "韩语" }, "pl-PL": { "type": [ "string", "null" ], "description": "波兰语" }, "pt-BR": { "type": [ "string", "null" ], "description": "葡萄牙语（巴西）" }, "ro-RO": { "type": [ "string", "null" ], "description": "罗马尼亚语" }, "ru-RU": { "type": [ "string", "null" ], "description": "俄语" }, "th-TH": { "type": [ "string", "null" ], "description": "泰语" }, "tr-TR": { "type": [ "string", "null" ], "description": "土耳其语" }, "zh-TW": { "type": [ "string", "null" ], "description": "中文（繁体）" }, "vi-VN": { "type": [ "string", "null" ], "description": "越南语" }, "km-KH": { "type": [ "string", "null" ], "description": "高棉语" }, "id-ID": { "type": [ "string", "null" ], "description": "印度尼西亚语" }, "lo-LA": { "type": [ "string", "null" ], "description": "老挝语" }, "my-MM": { "type": [ "string", "null" ], "description": "缅甸语" }, "ph-PH": { "type": [ "string", "null" ], "description": "菲律宾语" }, "ne-NP": { "type": [ "string", "null" ], "description": "尼泊尔语" } } }, "name-localization-object": { "type": [ "object", "null" ], "description": "包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，`en`）或五个字符的语言代码（例如，`en-US`）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：`en`和`en-US`），将存储最后提供的值。您可以在[文档](/zh/doc/shop-builder/references/supported-languages/)中找到支持语言的完整列表。", "anyOf": [ { "$ref": "#/components/schemas/two-letter-locale" }, { "$ref": "#/components/schemas/five-letter-locale" } ] }, "description-localization-object": { "type": [ "object", "null" ], "description": "包含本地化商品描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，`en`）或五个字符的区域设置代码（例如，`en-US`）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：`en`和`en-US`），将存储最后提供的值。您可以在[文档](/zh/doc/shop-builder/references/supported-languages/)中找到支持语言的完整列表。", "anyOf": [ { "$ref": "#/components/schemas/two-letter-locale" }, { "$ref": "#/components/schemas/five-letter-locale" } ] }, "long-description-localization-object": { "type": [ "object", "null" ], "description": "包含商品详细本地化描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，`en`）或五个字符的区域设置代码（例如，`en-US`）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：`en`和`en-US`），将存储最后提供的值。您可以在[文档](/zh/doc/shop-builder/references/supported-languages/)中找到支持语言的完整列表。", "anyOf": [ { "$ref": "#/components/schemas/two-letter-locale" }, { "$ref": "#/components/schemas/five-letter-locale" } ] }, "Value-points-item-model": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z0-9_\\-–.]*$", "example": "booster_mega_1", "description": "唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "long_description": { "$ref": "#/components/schemas/long-description-localization-object" }, "media_list": { "type": "array", "example": [ { "type": "image", "url": "https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg" } ], "description": "商品的附加资源，例如屏幕截图、游戏视频等。", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "example": "image", "description": "媒体类型：`image`/`video`。" }, "url": { "type": "string", "example": "https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg", "description": "资源文件。" } } } }, "type": { "type": "string", "description": "商品类型。" }, "image_url": { "type": "string" }, "is_enabled": { "type": "boolean" }, "order": { "type": "integer", "example": 1, "description": "定义排列顺序。" }, "is_clan": { "$ref": "#/components/schemas/is_clan" } } }, "is_enabled": { "type": "boolean", "example": true }, "media_list": { "type": "array", "example": [ { "type": "image", "url": "https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg" } ], "description": "商品的附加资源，例如屏幕截图、游戏视频等。", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "example": "image", "description": "媒体类型：`image`/`video`。" }, "url": { "type": "string", "example": "https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg", "description": "资源文件。" } } } }, "order": { "type": "integer", "example": 1, "description": "定义排列顺序。" }, "admin_value_points-create": { "properties": { "description": { "$ref": "#/components/schemas/description-localization-object" }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "long_description": { "$ref": "#/components/schemas/long-description-localization-object" }, "media_list": { "$ref": "#/components/schemas/media_list" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "sku": { "$ref": "#/components/schemas/sku" }, "is_clan": { "$ref": "#/components/schemas/is_clan" } }, "type": "object", "required": [ "sku", "name" ] }, "422-rc-vp-invalid-request": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-1102]: Unprocessable Entity. The property `property_name` is required" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } }, "Value-point-item-model": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[a-zA-Z0-9_\\-–.]*$", "example": "booster_mega_1", "description": "唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "long_description": { "$ref": "#/components/schemas/long-description-localization-object" }, "media_list": { "type": "array", "example": [ { "type": "image", "url": "https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg" } ], "description": "商品的附加资源，例如屏幕截图、游戏视频等。", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ], "example": "image", "description": "媒体类型：`image`/`video`。" }, "url": { "type": "string", "example": "https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg", "description": "资源文件。" } } } }, "type": { "type": "string", "description": "商品类型。" }, "image_url": { "type": "string" }, "is_enabled": { "type": "boolean" }, "order": { "type": "integer", "example": 1, "description": "定义排列顺序。" }, "can_delete": { "type": "boolean", "description": "是否可以删除该累充积分。如为`false`，则无法删除该累充积分，因为有一个或多个累充奖励链正在使用它。要删除该累充积分，请先[删除](https://developers.xsolla.com/zh/api/shop-builder/operation/admin-delete-reward-chain/)所有包含它的累充奖励链。\n\n如为`true`，则该累充积分未用于任何累充奖励链，可以[删除](https://developers.xsolla.com/zh/api/shop-builder/operation/admin-delete-value-point/)。" }, "is_clan": { "$ref": "#/components/schemas/is_clan" } } }, "admin-item-value-point-reward": { "type": "object", "properties": { "item_id": { "$ref": "#/components/schemas/item_id" }, "sku": { "$ref": "#/components/schemas/sku" }, "amount": { "type": "integer", "description": "累充积分数量。" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" } } }, "item-value-point-reward-set": { "type": "array", "items": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "amount": { "type": "integer", "description": "累充积分数量。" } }, "required": [ "sku", "amount" ] } }, "item-value-point-reward-set-for-patch": { "type": "array", "items": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "amount": { "type": "integer", "description": "累充积分数量。", "minimum": 0 } }, "required": [ "sku", "amount" ], "maxItems": 100 } }, "image_url": { "type": [ "string", "null" ], "example": "https://image.example.com", "description": "图片URL。" }, "date_start": { "type": "string", "format": "date-time", "example": "2020-04-15T18:16:00+05:00", "description": "累充奖励链的开始日期。" }, "date_end": { "type": [ "string", "null" ], "format": "date-time", "example": "2020-04-15T18:16:00+05:00", "description": "累充奖励链促销活动的结束日期。可以是`null`。如果`date_end`为`null`，则累充奖励链无时间限制。" }, "clan_type": { "type": [ "string", "null" ], "description": "公会类型。", "enum": [ "clan", "guild", "faction", "community", "team", "squad", "alliance", "association", "coalition", "union", "group", "civilizations", "dynasty", "order", "league", "brotherhood", "kingdom", "organization", "house", "empire", "tribe", "cartel", null ] }, "top_contributors": { "type": [ "object", "null" ], "properties": { "name": { "type": "string", "example": "Rocket", "description": "在授权过程中向艾克索拉发送的用户ID。用户ID用于将用户与您的艾克索拉登录管理器项目相关联，并显示为昵称。如果使用按[用户ID](https://developers.xsolla.com/zh/solutions/web-shop/create-web-shop/set-up-authentication/?tabs=100-UserIDAuth&link=100-UserIDAuth)授权，建议在[Webhook响应](https://developers.xsolla.com/zh/webhooks/operation/user-validation-in-webshop/)中传入name参数。该参数包含将用作昵称的用户名。" }, "contributed_amount": { "type": "integer", "example": 100, "description": "用户获得的累充积分数量。" } } }, "value-point-description": { "type": [ "string", "null" ], "description": "累充积分描述。" }, "value-point-long-description": { "type": [ "string", "null" ], "description": "累充积分详细描述。" }, "interval_type_weekly": { "type": "string", "description": "累充奖励链定期重置的频率。", "enum": [ "weekly" ] }, "interval_type_monthly": { "type": "string", "description": "累充奖励链定期重置的频率。", "enum": [ "monthly" ] }, "interval_type_hourly_rc": { "type": "string", "description": "累充奖励链定期重置的频率。", "enum": [ "hourly" ] }, "reset_next_date": { "type": "integer", "description": "计算得出的累充奖励链下次重置日期和时间（Unix时间戳）。

例如，累充奖励链从2024年3月1日吉隆坡时间01:00（GMT+8）开始按月重置。下一次累充奖励链重置日期和时间为2024年4月1日吉隆坡时间01:00（GMT+8），相当于2024年3月31日17:00（GMT+0），对应的Unix时间戳为`1711904400000`。

示例：`1711904400000`" }, "recurrent_schedule_client_side": { "type": [ "object", "null" ], "description": "累充奖励链的重置周期。", "properties": { "interval_type": { "oneOf": [ { "title": "interval_type = weekly", "$ref": "#/components/schemas/interval_type_weekly" }, { "title": "interval_type = monthly", "$ref": "#/components/schemas/interval_type_monthly" }, { "title": "interval_type = hourly", "$ref": "#/components/schemas/interval_type_hourly_rc" } ] }, "reset_next_date": { "$ref": "#/components/schemas/reset_next_date" } } }, "popup_header-two-letter-locale": { "type": [ "object", "null" ], "description": "包含公会累充奖励链提示弹窗本地化标题的对象。使用两个小写字母的[语言代码](https://developers.xsolla.com/zh/doc/pay-station/features/localization/)。", "properties": { "en": { "type": [ "string", "null" ], "example": "How to unlock rewards" }, "ar": { "type": [ "string", "null" ], "example": null }, "bg": { "type": [ "string", "null" ], "example": null }, "cn": { "type": [ "string", "null" ], "example": null }, "cs": { "type": [ "string", "null" ], "example": null }, "de": { "type": [ "string", "null" ], "example": "Wie man Belohnungen freischaltet" }, "es": { "type": [ "string", "null" ], "example": "Cómo desbloquear recompensas" }, "fr": { "type": [ "string", "null" ], "example": "Comment débloquer des récompenses" }, "he": { "type": [ "string", "null" ], "example": null }, "it": { "type": [ "string", "null" ], "example": "Come sbloccare ricompense" }, "ja": { "type": [ "string", "null" ], "example": "報酬をアンロックする方法" }, "ko": { "type": [ "string", "null" ], "example": null }, "pl": { "type": [ "string", "null" ], "example": null }, "pt": { "type": [ "string", "null" ], "example": null }, "ro": { "type": [ "string", "null" ], "example": null }, "ru": { "type": [ "string", "null" ], "example": null }, "th": { "type": [ "string", "null" ], "example": null }, "tr": { "type": [ "string", "null" ], "example": null }, "tw": { "type": [ "string", "null" ], "example": null }, "vi": { "type": [ "string", "null" ], "example": null } } }, "popup_instruction-two-letter-locale": { "type": [ "object", "null" ], "description": "包含公会累充奖励链提示弹窗本地化说明的对象。使用两个小写字母的[语言代码](https://developers.xsolla.com/zh/doc/pay-station/features/localization/)。", "properties": { "en": { "type": [ "string", "null" ], "example": "You must be a clan member to get clan rewards. You join a clan when a clan member invites you to the clan, and you accept the invite. You can also create your own clan." }, "ar": { "type": [ "string", "null" ], "example": null }, "bg": { "type": [ "string", "null" ], "example": null }, "cn": { "type": [ "string", "null" ], "example": null }, "cs": { "type": [ "string", "null" ], "example": null }, "de": { "type": [ "string", "null" ], "example": "Du musst ein Clanmitglied sein, um Clananreize zu erhalten. Du trittst einem Clan bei, wenn ein Clanmitglied dich einlädt, und du die Einladung annimmst. Du kannst auch deinen eigenen Clan erstellen." }, "es": { "type": [ "string", "null" ], "example": "Debes ser miembro de un clan para obtener las recompensas del clan. Te unes a un clan cuando un miembro del clan te invita al clan y aceptas la invitación. También puedes crear tu propio clan." }, "fr": { "type": [ "string", "null" ], "example": "Vous devez être membre d'un clan pour obtenir les récompenses du clan. Vous rejoignez un clan lorsque qu'un membre du clan vous invite au clan et que vous acceptez l'invitation. Vous pouvez également créer votre propre clan." }, "he": { "type": [ "string", "null" ], "example": null }, "it": { "type": [ "string", "null" ], "example": "Devi essere un membro del clan per ottenere le ricompense del clan. Ti unisci a un clan quando un membro del clan ti invita al clan e accetti l'invito. Puoi anche creare il tuo clan." }, "ja": { "type": [ "string", "null" ], "example": "クランリワードを受け取るには、クランメンバーでなければなりません。 クランメンバーがあなたをクランに招待し、招待を受け入れると、クランに参加できます。 あなた自身のクランを作成することもできます。" }, "ko": { "type": [ "string", "null" ], "example": null }, "pl": { "type": [ "string", "null" ], "example": null }, "pt": { "type": [ "string", "null" ], "example": null }, "ro": { "type": [ "string", "null" ], "example": null }, "ru": { "type": [ "string", "null" ], "example": null }, "th": { "type": [ "string", "null" ], "example": null }, "tr": { "type": [ "string", "null" ], "example": null }, "tw": { "type": [ "string", "null" ], "example": null }, "vi": { "type": [ "string", "null" ], "example": null } } }, "popup_image_url": { "type": [ "string", "null" ], "example": "https://image.example.com", "description": "公会累充奖励链提示弹出窗口的图片。", "format": "uri" }, "client-reward-chain-item-model": { "type": "object", "properties": { "reward_chain_id": { "type": "integer", "example": 9, "description": "累充奖励链ID。" }, "name": { "type": "string", "example": "Weekly quest", "description": "累充奖励链名称。" }, "description": { "type": [ "string", "null" ], "example": "Major weekly quest", "description": "Reward chain description." }, "long_description": { "type": [ "string", "null" ], "example": "You can get a lot of additional items just by shopping during the week", "description": "累充奖励链详细描述。" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "order": { "$ref": "#/components/schemas/order" }, "date_start": { "$ref": "#/components/schemas/date_start" }, "date_end": { "$ref": "#/components/schemas/date_end" }, "clan_type": { "$ref": "#/components/schemas/clan_type" }, "top_contributors": { "type": "array", "items": { "$ref": "#/components/schemas/top_contributors" } }, "value_point": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/value-point-sku" }, "name": { "$ref": "#/components/schemas/value-point-name" }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "description": { "$ref": "#/components/schemas/value-point-description" }, "long_description": { "$ref": "#/components/schemas/value-point-long-description" }, "amount": { "$ref": "#/components/schemas/value-point-amount" }, "is_clan": { "$ref": "#/components/schemas/is_clan" } } }, "steps": { "type": "array", "items": { "type": "object", "description": "累充奖励链步骤。", "properties": { "step_id": { "type": "integer", "example": 10, "description": "步骤ID。" }, "name": { "type": "string", "example": "Level 1", "description": "步骤名称。" }, "is_claimed": { "type": "boolean", "example": false, "description": "该步骤奖励是否已领取。" }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "price": { "type": "object", "properties": { "amount": { "type": "integer", "example": 100, "description": "用户在该步骤中领取的累充积分数量。" } } }, "reward": { "type": "array", "items": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "name": { "type": "string", "example": "Super box", "description": "商品名称。" }, "type": { "type": "string", "example": "bundle", "description": "商品类型。" }, "description": { "type": "string", "example": "Super box with items", "description": "Item description." }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "quantity": { "type": "integer", "example": 2, "description": "商品数量。" } } } } } } }, "recurrent_schedule": { "$ref": "#/components/schemas/recurrent_schedule_client_side" }, "popup_header": { "$ref": "#/components/schemas/popup_header-two-letter-locale" }, "popup_instruction": { "$ref": "#/components/schemas/popup_instruction-two-letter-locale" }, "popup_image_url": { "$ref": "#/components/schemas/popup_image_url" } } }, "Pagination_has-more": { "type": "boolean", "example": true, "description": "用作指示还有更多页面。" }, "reward_chain_id": { "type": "integer", "example": 9, "description": "唯一累充奖励链ID。" }, "periods": { "type": "array", "nullable": false, "description": "累充奖励链有效期。若指定了多个时间段，则`date_from`和`date_until`均为必需。", "items": { "type": "object", "properties": { "date_from": { "type": "string", "format": "date-time", "nullable": false, "example": "2020-08-11T10:00:00+03:00", "description": "指定累充奖励链的开始日期。" }, "date_until": { "type": [ "string", "null" ], "format": "date-time", "example": "2020-08-11T20:00:00+03:00", "description": "指定累充奖励链的结束日期。仅在指定单个有效期时可为`null`。" } }, "required": [ "date_from" ] } }, "day_of_week": { "type": "integer", "description": "在一周中的哪一天重置累充奖励链，其中`1`表示星期一，`7`表示星期日。", "minimum": 1, "maximum": 7 }, "time": { "type": "string", "description": "所需时区中重置累充奖励链的时间（四舍五入到小时）。

例如，累充奖励链重置的设定时间为吉隆坡时区(GMT+8)的01:00。在这种情况下，`time`参数的值为`01:00:00+08:00`。", "pattern": "((0[0-9]|1[0-9]|2[0-3]):00:00)(\\+|-)(0[0-9]|1[0-9]|2[0-3]):([0-5][0-9])", "example": "01:00:00+08:00" }, "displayable_reset_start_date": { "description": "累充奖励链首次重置的日期和时间。

例如，累充奖励链首次重置的日期和时间为2024年3月1日吉隆坡时间01:00，即ISO 8601格式下的`2024-03-01T01:00:00+08:00`。

示例：`2024-03-01T01:00:00+08:00`", "type": "string", "format": "date-time" }, "displayable_reset_next_date": { "description": "计算得出的累充奖励链下次重置日期和时间(ISO 8601)。

例如，累充奖励链从2024年3月1日吉隆坡时间01:00开始按月重置。下一次累充奖励链重置日期和时间为2024年4月1日吉隆坡时间01:00，即ISO 8601格式下的`2024-04-01T01:00:00+08:00`。

示例：`2024-04-01T01:00:00+08:00`", "type": "string", "format": "date-time" }, "day_of_month": { "type": "integer", "description": "在一个月中的哪一天重置累充奖励链。如果该月天数少于指定日期序号，则累充奖励链会在该月最后一天重置。", "minimum": 1, "maximum": 31 }, "reward_chain_hours_interval": { "type": "integer", "description": "累充奖励链重置的小时间隔。

计时从date_start参数指定的时间开始。

例如，若`date_start = \"2025-11-15T18:15:00+05:00\"`且`hours_interval = 2`，则累充奖励链将从`\"2025-11-15T20:15:00+05:00\"`开始每2小时重置一次。", "minimum": 1, "maximum": 10000 }, "admin_recurrent_schedule": { "type": [ "object", "null" ], "description": "累充奖励链的重置周期。", "oneOf": [ { "type": "object", "title": "interval_type = weekly", "description": "Weekly reset of the reward chain.", "properties": { "interval_type": { "$ref": "#/components/schemas/interval_type_weekly" }, "day_of_week": { "$ref": "#/components/schemas/day_of_week" }, "time": { "$ref": "#/components/schemas/time" }, "reset_next_date": { "$ref": "#/components/schemas/reset_next_date" }, "displayable_reset_start_date": { "$ref": "#/components/schemas/displayable_reset_start_date" }, "displayable_reset_next_date": { "$ref": "#/components/schemas/displayable_reset_next_date" } } }, { "type": "object", "title": "interval_type = monthly", "description": "Monthly reset of the reward chain.", "properties": { "interval_type": { "$ref": "#/components/schemas/interval_type_monthly" }, "day_of_month": { "$ref": "#/components/schemas/day_of_month" }, "time": { "$ref": "#/components/schemas/time" }, "reset_next_date": { "$ref": "#/components/schemas/reset_next_date" }, "displayable_reset_start_date": { "$ref": "#/components/schemas/displayable_reset_start_date" }, "displayable_reset_next_date": { "$ref": "#/components/schemas/displayable_reset_next_date" } } }, { "type": "object", "title": "interval_type = hourly", "description": "Reset of the reward chain performed at the specified time interval in hours.", "properties": { "interval_type": { "$ref": "#/components/schemas/interval_type_hourly_rc" }, "hours_interval": { "$ref": "#/components/schemas/reward_chain_hours_interval" }, "time": { "$ref": "#/components/schemas/time" }, "reset_next_date": { "$ref": "#/components/schemas/reset_next_date" }, "displayable_reset_start_date": { "$ref": "#/components/schemas/displayable_reset_start_date" }, "displayable_reset_next_date": { "$ref": "#/components/schemas/displayable_reset_next_date" } } } ] }, "chain_user-attribute_conditions_model-get": { "allOf": [ { "$ref": "#/components/schemas/user-attribute_conditions_model-get" }, { "description": "Conditions for validating user attributes.\nDetermine chain availability based on whether user attributes match all specified conditions.\n" } ] }, "chain_is_always_visible": { "description": "累充奖励链是否对所有用户可见。如果为`true`，则无论用户的身份认证状态或属性如何，始终显示该链。\n\n如需配置个性化，您需要传入`false`。累充奖励链的显示逻辑如下：\n* 如果传入`false`，并在`attribute_conditions`数组中指定可见性条件，则该累充奖励链会被视为个性化累充奖励链，并且仅向符合指定条件的授权用户显示。\n* 如果传入`false`，但未传入`attribute_conditions`数组或该数组为空，则该累充奖励链会向未授权用户显示；如果未找到与授权用户匹配的累充奖励链，也会显示该链。", "type": "boolean", "default": true, "example": true }, "is_reset_after_end": { "description": "是否在结束日期后重置累充奖励链（所有用户的累充积分和进度）：\n* 如为`true`，累充奖励链将在结束日期后重置。\n* 如为`false`，累充奖励链在结束日期后不重置。\n\n
\n\n
提示

\n以下情况不能设置为true：
\n
    \n
  • recurrent_schedule中已设置重置周期。
    • \n
  • periods.date_until中传入了null值。
    • \n
\n
", "type": "boolean", "default": false, "example": false }, "admin-get-reward-chain-item-basic-model": { "type": "object", "description": "一个累充奖励链。", "properties": { "reward_chain_id": { "$ref": "#/components/schemas/reward_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "long_description": { "$ref": "#/components/schemas/long-description-localization-object" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "periods": { "$ref": "#/components/schemas/periods" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "value_point": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/value-point-sku" }, "name": { "$ref": "#/components/schemas/value-point-name" }, "type": { "type": "string", "example": "value_point" }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "description": { "$ref": "#/components/schemas/value-point-description" }, "long_description": { "$ref": "#/components/schemas/value-point-long-description" }, "amount": { "$ref": "#/components/schemas/value-point-amount" }, "is_clan": { "$ref": "#/components/schemas/is_clan" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "media_list": { "$ref": "#/components/schemas/media_list" }, "order": { "$ref": "#/components/schemas/order" } } }, "recurrent_schedule": { "$ref": "#/components/schemas/admin_recurrent_schedule" }, "attribute_conditions": { "$ref": "#/components/schemas/chain_user-attribute_conditions_model-get" }, "is_always_visible": { "$ref": "#/components/schemas/chain_is_always_visible" }, "is_reset_after_end": { "$ref": "#/components/schemas/is_reset_after_end" } } }, "admin-get-reward-chain-item-clan-basic-model": { "allOf": [ { "$ref": "#/components/schemas/admin-get-reward-chain-item-basic-model" }, { "type": "object", "description": "Clan reward chain.", "properties": { "value_point": { "type": "object", "description": "A value point configured for a clan reward chain.", "properties": { "sku": { "$ref": "#/components/schemas/value-point-sku" }, "name": { "$ref": "#/components/schemas/value-point-name" }, "type": { "type": "string", "example": "value_point" }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "description": { "$ref": "#/components/schemas/value-point-description" }, "long_description": { "$ref": "#/components/schemas/value-point-long-description" }, "amount": { "$ref": "#/components/schemas/value-point-amount" }, "is_clan": { "$ref": "#/components/schemas/is_clan" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "media_list": { "$ref": "#/components/schemas/media_list" }, "order": { "$ref": "#/components/schemas/order" } }, "required": [ "sku" ] }, "popup_header": { "$ref": "#/components/schemas/popup_header-two-letter-locale" }, "popup_instruction": { "$ref": "#/components/schemas/popup_instruction-two-letter-locale" }, "popup_image_url": { "$ref": "#/components/schemas/popup_image_url" }, "clan_type": { "$ref": "#/components/schemas/clan_type" } } } ] }, "step_price_amount": { "type": "integer", "example": 100, "description": "以累充积分表示的步骤价格。" }, "reward_step_price": { "type": "object", "properties": { "amount": { "$ref": "#/components/schemas/step_price_amount" } }, "required": [ "amount" ] }, "reward_item_quantity": { "type": "integer", "example": 2, "description": "商品数量。" }, "reward-chain-step-reward_user-attribute_conditions_model-post": { "allOf": [ { "$ref": "#/components/schemas/user-attribute_conditions_model-post" }, { "description": "Conditions for validating user attributes.\nDetermine reward availability for reward chain steps based on whether user attributes match all specified conditions.\n" } ] }, "create_reward_step": { "type": "object", "description": "累充奖励链步骤。", "properties": { "name": { "$ref": "#/components/schemas/name-localization-object" }, "price": { "$ref": "#/components/schemas/reward_step_price" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "reward": { "type": "array", "items": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "quantity": { "$ref": "#/components/schemas/reward_item_quantity" }, "attribute_conditions": { "$ref": "#/components/schemas/reward-chain-step-reward_user-attribute_conditions_model-post" } }, "required": [ "sku", "quantity" ] } } }, "required": [ "name", "price", "reward" ] }, "recurrent_schedule_create_update": { "type": [ "object", "null" ], "description": "累充奖励链的重置周期。", "oneOf": [ { "type": "object", "title": "interval_type = weekly", "description": "Weekly type of reward chain refresh.", "properties": { "interval_type": { "$ref": "#/components/schemas/interval_type_weekly" }, "day_of_week": { "$ref": "#/components/schemas/day_of_week" }, "time": { "$ref": "#/components/schemas/time" } }, "required": [ "interval_type", "time", "day_of_week" ] }, { "type": "object", "title": "interval_type = monthly", "description": "Monthly type of refresh of reward chain.", "properties": { "interval_type": { "$ref": "#/components/schemas/interval_type_monthly" }, "day_of_month": { "$ref": "#/components/schemas/day_of_month" }, "time": { "$ref": "#/components/schemas/time" } }, "required": [ "interval_type", "time", "day_of_month" ] }, { "type": "object", "title": "interval_type = hourly", "description": "Reset of the reward chain performed at the specified time interval in hours.", "properties": { "interval_type": { "$ref": "#/components/schemas/interval_type_hourly_rc" }, "hours_interval": { "$ref": "#/components/schemas/reward_chain_hours_interval" } }, "required": [ "interval_type", "hours_interval" ] } ] }, "chain_user-attribute_conditions_model-post": { "allOf": [ { "$ref": "#/components/schemas/user-attribute_conditions_model-post" }, { "description": "Conditions for validating user attributes.\nDetermine chain availability based on whether user attributes match all specified conditions.\n" } ] }, "create-reward-chain-model": { "type": "object", "description": "一个累充奖励链。", "properties": { "name": { "$ref": "#/components/schemas/name-localization-object" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "long_description": { "$ref": "#/components/schemas/long-description-localization-object" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "order": { "$ref": "#/components/schemas/order" }, "periods": { "$ref": "#/components/schemas/periods" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "value_point": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" } }, "required": [ "sku" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/create_reward_step" } }, "recurrent_schedule": { "$ref": "#/components/schemas/recurrent_schedule_create_update" }, "attribute_conditions": { "$ref": "#/components/schemas/chain_user-attribute_conditions_model-post" }, "is_always_visible": { "$ref": "#/components/schemas/chain_is_always_visible" }, "is_reset_after_end": { "$ref": "#/components/schemas/is_reset_after_end" } }, "required": [ "name", "value_point", "periods", "steps", "is_enabled" ] }, "create-clan-reward-chain-model": { "allOf": [ { "$ref": "#/components/schemas/create-reward-chain-model" }, { "type": "object", "description": "Clan reward chain.", "properties": { "value_point": { "type": "object", "description": "A value point configured for a clan reward chain.", "properties": { "sku": { "$ref": "#/components/schemas/sku" } }, "required": [ "sku" ] }, "popup_header": { "$ref": "#/components/schemas/popup_header-two-letter-locale" }, "popup_instruction": { "$ref": "#/components/schemas/popup_instruction-two-letter-locale" }, "popup_image_url": { "$ref": "#/components/schemas/popup_image_url" }, "clan_type": { "$ref": "#/components/schemas/clan_type" } }, "required": [ "name", "value_point", "periods", "steps", "is_enabled", "popup_header", "popup_instruction" ] } ] }, "step_id": { "type": [ "integer", "null" ], "example": 10, "description": "唯一步骤ID。" }, "reward-chain-step-reward_user-attribute_conditions_model-get": { "allOf": [ { "$ref": "#/components/schemas/user-attribute_conditions_model-get" }, { "description": "Conditions for validating user attributes.\nDetermine reward availability for reward chain steps based on whether user attributes match all specified conditions.\n" } ] }, "reward_step_short": { "type": "object", "description": "累充奖励链步骤。", "properties": { "step_id": { "$ref": "#/components/schemas/step_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "price": { "$ref": "#/components/schemas/reward_step_price" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "reward": { "type": "array", "items": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "quantity": { "$ref": "#/components/schemas/reward_item_quantity" }, "attribute_conditions": { "$ref": "#/components/schemas/reward-chain-step-reward_user-attribute_conditions_model-get" } } } } } }, "admin-get-reward-chain-item-full-model": { "type": "object", "description": "一个累充奖励链。", "properties": { "reward_chain_id": { "$ref": "#/components/schemas/reward_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "long_description": { "$ref": "#/components/schemas/long-description-localization-object" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "periods": { "$ref": "#/components/schemas/periods" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "value_point": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "long_description": { "$ref": "#/components/schemas/long-description-localization-object" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "type": { "type": "string" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "media_list": { "$ref": "#/components/schemas/media_list" }, "order": { "$ref": "#/components/schemas/order" }, "is_clan": { "$ref": "#/components/schemas/is_clan" } } }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/reward_step_short" } }, "recurrent_schedule": { "$ref": "#/components/schemas/admin_recurrent_schedule" }, "attribute_conditions": { "$ref": "#/components/schemas/chain_user-attribute_conditions_model-get" }, "is_always_visible": { "$ref": "#/components/schemas/chain_is_always_visible" }, "is_reset_after_end": { "$ref": "#/components/schemas/is_reset_after_end" } } }, "admin-get-reward-chain-item-clan-full-model": { "allOf": [ { "$ref": "#/components/schemas/admin-get-reward-chain-item-full-model" }, { "type": "object", "description": "Clan reward chain.", "properties": { "value_point": { "type": "object", "description": "A value point configured for a clan reward chain.", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "long_description": { "$ref": "#/components/schemas/long-description-localization-object" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "type": { "type": "string" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "media_list": { "$ref": "#/components/schemas/media_list" }, "order": { "$ref": "#/components/schemas/order" }, "is_clan": { "$ref": "#/components/schemas/is_clan" } }, "required": [ "sku" ] }, "popup_header": { "$ref": "#/components/schemas/popup_header-two-letter-locale" }, "popup_instruction": { "$ref": "#/components/schemas/popup_instruction-two-letter-locale" }, "popup_image_url": { "$ref": "#/components/schemas/popup_image_url" }, "clan_type": { "$ref": "#/components/schemas/clan_type" }, "top_contributors": { "$ref": "#/components/schemas/top_contributors" } } } ] }, "modify_reward_step": { "type": "object", "description": "累充奖励链步骤。", "properties": { "step_id": { "$ref": "#/components/schemas/step_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "price": { "$ref": "#/components/schemas/reward_step_price" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "reward": { "type": "array", "items": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "quantity": { "$ref": "#/components/schemas/reward_item_quantity" }, "attribute_conditions": { "$ref": "#/components/schemas/reward-chain-step-reward_user-attribute_conditions_model-post" } }, "required": [ "sku", "quantity" ] } } }, "required": [ "name", "price", "reward", "step_id" ] }, "update-reward-chain-model": { "type": "object", "description": "一个累充奖励链。", "properties": { "name": { "$ref": "#/components/schemas/name-localization-object" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "long_description": { "$ref": "#/components/schemas/long-description-localization-object" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "order": { "$ref": "#/components/schemas/order" }, "periods": { "$ref": "#/components/schemas/periods" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/modify_reward_step" } }, "recurrent_schedule": { "$ref": "#/components/schemas/recurrent_schedule_create_update" }, "attribute_conditions": { "$ref": "#/components/schemas/chain_user-attribute_conditions_model-post" }, "is_always_visible": { "$ref": "#/components/schemas/chain_is_always_visible" }, "is_reset_after_end": { "$ref": "#/components/schemas/is_reset_after_end" } }, "required": [ "name", "periods", "steps", "is_enabled" ] }, "update-clan-reward-chain-model": { "allOf": [ { "$ref": "#/components/schemas/create-reward-chain-model" }, { "type": "object", "description": "Clan reward chain.", "properties": { "popup_header": { "$ref": "#/components/schemas/popup_header-two-letter-locale" }, "popup_instruction": { "$ref": "#/components/schemas/popup_instruction-two-letter-locale" }, "popup_image_url": { "$ref": "#/components/schemas/popup_image_url" }, "clan_type": { "$ref": "#/components/schemas/clan_type" } }, "required": [ "name", "periods", "steps", "is_enabled", "popup_header", "popup_instruction" ] } ] }, "daily_chain_type": { "type": "string", "enum": [ "calendar_hard", "rolling_skippable", "rolling_unskippable" ], "description": "决定用户可领取奖励时间的每日奖励类型。\n\n可能值：\n- `calendar_hard` — 每24小时解锁下一步骤奖励。下一步骤奖励可用后，之前未领取的奖励将永久失效。\n- `rolling_skippable` — 基于`date_start`每24小时解锁下一步骤奖励。进度按顺序推进：只有领取前一个奖励后，才会解锁新的奖励。如果用户跳过一天或多天，则会从上次停留的位置继续；错过的天数不会发放多份奖励。\n- `rolling_unskippable` — 基于`date_start`每24小时解锁下一步骤奖励。进度按顺序推进：只有领取前一个奖励后，才会解锁新的奖励。不过，如果用户跳过一天，进度会被重置，必须从第一步重新开始。" }, "calendar_hard_date_start": { "type": "string", "format": "date-time", "example": "2020-04-15T18:16:00+05:00", "description": "每日奖励开始日期。" }, "calendar_hard_is_recurrent": { "type": "boolean", "example": true, "default": false, "description": "每日奖励是否循环。如果为`true`，每日奖励将在结束日期后自动重置。下个周期的`start_date`和`end_date`基于每日奖励步骤总数和首次`start_date`的时间设定自动计算。" }, "calendar-hard-daily-chain-base": { "type": "object", "description": "`calendar_hard`每日奖励的基础属性。", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/daily_chain_type" }, { "enum": [ "calendar_hard" ] } ] }, "date_start": { "$ref": "#/components/schemas/calendar_hard_date_start" }, "is_recurrent": { "$ref": "#/components/schemas/calendar_hard_is_recurrent" } } }, "daily_chain_id": { "type": "integer", "example": 9, "description": "唯一每日奖励ID。" }, "daily_chain_date_end": { "type": [ "string", "null" ], "format": "date-time", "example": "2020-04-15T18:16:00+05:00", "description": "每日奖励结束日期。可以为`null`。类型设置为`calendar_hard`时将根据添加的步骤数量自动设置此日期，因此可以将其保留为`null`。" }, "daily_chain_number_of_step": { "type": "integer", "example": 3, "description": "每日奖励中配置的步骤数量。这里的每个步骤代表每日奖励中的一天。" }, "admin-calendar-hard-daily-chain-short-model": { "allOf": [ { "$ref": "#/components/schemas/calendar-hard-daily-chain-base" }, { "type": "object", "description": "A `calendar_hard` daily reward (short version).", "properties": { "id": { "$ref": "#/components/schemas/daily_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "date_end": { "$ref": "#/components/schemas/daily_chain_date_end" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "number_of_steps": { "$ref": "#/components/schemas/daily_chain_number_of_step" } } } ] }, "daily_rolling_chain_date_start": { "type": "string", "format": "date-time", "example": "2020-04-15T18:16:00+05:00", "description": "每日奖励的开始日期和时间。此时间点同时定义用户可领取奖励的每日重置时间。" }, "rolling_date_end": { "type": [ "string", "null" ], "format": "date-time", "example": "2020-04-15T18:16:00+05:00", "description": "每日奖励的结束日期。" }, "rolling_is_recurrent": { "type": "boolean", "example": true, "default": false, "description": "每日奖励是否循环。如为`true`，用户完成所有步骤后奖励将重置，可从第1步重新开始。循环仅在`date_start`和`date_end`定义的活动期间内有效。" }, "rolling-skippable-daily-chain-base": { "type": "object", "description": "`rolling_skippable`类型每日奖励的基础属性。", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/daily_chain_type" }, { "enum": [ "rolling_skippable" ] } ] }, "date_start": { "$ref": "#/components/schemas/daily_rolling_chain_date_start" }, "date_end": { "$ref": "#/components/schemas/rolling_date_end" }, "is_recurrent": { "$ref": "#/components/schemas/rolling_is_recurrent" } } }, "admin-rolling-skippable-daily-chain-short-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-skippable-daily-chain-base" }, { "type": "object", "description": "A `rolling_skippable` daily reward (short version).", "properties": { "id": { "$ref": "#/components/schemas/daily_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "number_of_steps": { "$ref": "#/components/schemas/daily_chain_number_of_step" } } } ] }, "rolling-unskippable-daily-chain-base": { "type": "object", "description": "`rolling_unskippable`类型每日奖励的基础属性。", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/daily_chain_type" }, { "enum": [ "rolling_unskippable" ] } ] }, "date_start": { "$ref": "#/components/schemas/daily_rolling_chain_date_start" }, "date_end": { "$ref": "#/components/schemas/rolling_date_end" }, "is_recurrent": { "$ref": "#/components/schemas/rolling_is_recurrent" } } }, "admin-rolling-unskippable-daily-chain-short-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-unskippable-daily-chain-base" }, { "type": "object", "description": "A `rolling_unskippable` daily reward (short version).", "properties": { "id": { "$ref": "#/components/schemas/daily_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "number_of_steps": { "$ref": "#/components/schemas/daily_chain_number_of_step" } } } ] }, "admin-daily-chain-short-model": { "oneOf": [ { "$ref": "#/components/schemas/admin-calendar-hard-daily-chain-short-model" }, { "$ref": "#/components/schemas/admin-rolling-skippable-daily-chain-short-model" }, { "$ref": "#/components/schemas/admin-rolling-unskippable-daily-chain-short-model" } ], "discriminator": { "propertyName": "type", "mapping": { "calendar_hard": "#/components/schemas/admin-calendar-hard-daily-chain-short-model", "rolling_skippable": "#/components/schemas/admin-rolling-skippable-daily-chain-short-model", "rolling_unskippable": "#/components/schemas/admin-rolling-unskippable-daily-chain-short-model" } } }, "daily_chain_step_number": { "type": "integer", "example": 2, "description": "步骤编号。", "nullable": false, "minimum": 1 }, "modify-daily-chain-item-model": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "quantity": { "type": "integer", "description": "此sku的每日奖励步骤数量", "minimum": 1 } }, "required": [ "sku", "quantity" ] }, "create-daily-chain-step-model": { "type": "object", "properties": { "step_number": { "$ref": "#/components/schemas/daily_chain_step_number" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/modify-daily-chain-item-model" } } }, "required": [ "step_number", "items" ] }, "create-calendar-hard-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/calendar-hard-daily-chain-base" }, { "type": "object", "description": "A daily reward for `calendar_hard` type.", "properties": { "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/create-daily-chain-step-model" } } }, "required": [ "name", "date_start", "steps", "is_enabled", "type" ] } ] }, "create-rolling-skippable-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-skippable-daily-chain-base" }, { "type": "object", "description": "A daily reward for `rolling_skippable` type.", "properties": { "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/create-daily-chain-step-model" } } }, "required": [ "name", "date_start", "steps", "is_enabled", "type" ] } ] }, "create-rolling-unskippable-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-unskippable-daily-chain-base" }, { "type": "object", "description": "A daily reward for `rolling_unskippable` type.", "properties": { "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/create-daily-chain-step-model" } } }, "required": [ "name", "date_start", "steps", "is_enabled", "type" ] } ] }, "daily-chain-error-model": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-1102]: Unprocessable Entity. The property `property_name` is required" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" }, "errorMessageExtended": { "type": [ "object", "null" ] } } }, "daily_chain_step_id": { "type": [ "integer", "null" ], "example": 10, "description": "每日奖励步骤唯一标识符", "minimum": 1 }, "item_type": { "type": "string", "description": "商品类型：`virtual_good`/`virtual_currency`/`bundle`/`unit`。" }, "admin-daily-chain-item-model": { "type": "object", "properties": { "item_id": { "$ref": "#/components/schemas/item_id" }, "sku": { "$ref": "#/components/schemas/sku" }, "type": { "$ref": "#/components/schemas/item_type" }, "name": { "$ref": "#/components/schemas/two-letter-locale" }, "description": { "$ref": "#/components/schemas/long-description-localization-object" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "quantity": { "type": "integer", "description": "商品数量。", "minimum": 1, "example": 1 } } }, "admin-daily-chain-step-model": { "type": "object", "description": "一个每日奖励步骤。", "properties": { "step_id": { "$ref": "#/components/schemas/daily_chain_step_id" }, "step_number": { "$ref": "#/components/schemas/daily_chain_step_number" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/admin-daily-chain-item-model" } } } }, "admin-calendar-hard-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/calendar-hard-daily-chain-base" }, { "type": "object", "description": "A calendar_hard daily reward for admin responses.", "properties": { "id": { "$ref": "#/components/schemas/daily_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "date_end": { "$ref": "#/components/schemas/daily_chain_date_end" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "number_of_steps": { "$ref": "#/components/schemas/daily_chain_number_of_step" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/admin-daily-chain-step-model" } } } } ] }, "admin-rolling-skippable-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-skippable-daily-chain-base" }, { "type": "object", "description": "A rolling_skippable daily reward for admin responses.", "properties": { "id": { "$ref": "#/components/schemas/daily_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "number_of_steps": { "$ref": "#/components/schemas/daily_chain_number_of_step" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/admin-daily-chain-step-model" } } } } ] }, "admin-rolling-unskippable-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-unskippable-daily-chain-base" }, { "type": "object", "description": "A `rolling_unskippable` daily reward for admin responses.", "properties": { "id": { "$ref": "#/components/schemas/daily_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "number_of_steps": { "$ref": "#/components/schemas/daily_chain_number_of_step" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/admin-daily-chain-step-model" } } } } ] }, "admin-daily-chain-long-model": { "oneOf": [ { "$ref": "#/components/schemas/admin-calendar-hard-daily-chain-model" }, { "$ref": "#/components/schemas/admin-rolling-skippable-daily-chain-model" }, { "$ref": "#/components/schemas/admin-rolling-unskippable-daily-chain-model" } ], "discriminator": { "propertyName": "type", "mapping": { "calendar_hard": "#/components/schemas/admin-calendar-hard-daily-chain-model", "rolling_skippable": "#/components/schemas/admin-rolling-skippable-daily-chain-model", "rolling_unskippable": "#/components/schemas/admin-rolling-unskippable-daily-chain-model" } } }, "daily_chain_update_step_id": { "type": [ "integer", "null" ], "example": 10, "description": "每日奖励步骤唯一标识符。更新时指定以保留用户进度。", "minimum": 1 }, "modify-daily-chain-step-model": { "type": "object", "properties": { "step_id": { "$ref": "#/components/schemas/daily_chain_update_step_id" }, "step_number": { "$ref": "#/components/schemas/daily_chain_step_number" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/modify-daily-chain-item-model" } } }, "required": [ "step_number", "items" ] }, "update-calendar-hard-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/calendar-hard-daily-chain-base" }, { "type": "object", "description": "A daily reward for `calendar_hard` type.", "properties": { "id": { "$ref": "#/components/schemas/daily_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/modify-daily-chain-step-model" } } }, "required": [ "name", "date_start", "steps", "is_enabled", "type" ] } ] }, "update-rolling-skippable-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-skippable-daily-chain-base" }, { "type": "object", "description": "A daily reward for `rolling_skippable` type.", "properties": { "id": { "$ref": "#/components/schemas/daily_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/modify-daily-chain-step-model" } } }, "required": [ "name", "date_start", "steps", "is_enabled", "type" ] } ] }, "update-rolling-unskippable-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-unskippable-daily-chain-base" }, { "type": "object", "description": "A daily reward for `rolling_unskippable` type.", "properties": { "id": { "$ref": "#/components/schemas/daily_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/modify-daily-chain-step-model" } } }, "required": [ "name", "date_start", "steps", "is_enabled", "type" ] } ] }, "client-daily-chain-item-model": { "type": "object", "properties": { "item_id": { "$ref": "#/components/schemas/item_id" }, "sku": { "$ref": "#/components/schemas/sku" }, "type": { "$ref": "#/components/schemas/item_type" }, "name": { "type": "string", "description": "商品名称。" }, "description": { "type": [ "string", "null" ], "description": "Item description." }, "bundle_type": { "type": [ "string", "null" ], "enum": [ "standard", "virtual_currency_package" ] }, "image_url": { "$ref": "#/components/schemas/image_url" }, "is_free": { "$ref": "#/components/schemas/value-is_free" }, "quantity": { "type": "integer", "description": "商品数量。", "minimum": 1, "example": 1 }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/client-daily-chain-item-model" } } } }, "client-daily-chain-step-model": { "type": "object", "description": "每日奖励步骤。", "properties": { "step_number": { "$ref": "#/components/schemas/daily_chain_step_number" }, "status": { "type": "string", "example": "claimed", "enum": [ "claimed", "claimable", "blocked", "claim_in_future" ], "description": "定义步骤的当前领取状态。\n\n可能值：\n- `claimed` — 该步骤已领取。\n- `claimable` — 该步骤可领取。\n- `blocked` — 该步骤不可领取：\n - 对于未授权用户：所有步骤均被锁定。\n - 对于`calendar_hard`：该步骤未领取，且当前已过期。\n - 对于`rolling_skippable`：该步骤会被锁定，直到前一步骤被领取。\n- `claim_in_future` — 该步骤未领取，且该步骤在未来可用。" }, "unlocked_date": { "type": "integer", "format": "int64", "description": "步骤解锁时间的Unix时间戳（秒）。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/client-daily-chain-item-model" } } } }, "client-calendar-hard-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/calendar-hard-daily-chain-base" }, { "type": "object", "description": "A calendar_hard daily reward for client responses.", "properties": { "id": { "type": "integer", "example": 9, "description": "每日奖励ID。" }, "name": { "type": "string", "example": "Weekly quest", "description": "Daily reward name." }, "description": { "type": [ "string", "null" ], "example": "Major weekly quest", "description": "Daily reward description." }, "order": { "$ref": "#/components/schemas/order" }, "date_end": { "$ref": "#/components/schemas/daily_chain_date_end" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/client-daily-chain-step-model" } } } } ] }, "client-rolling-skippable-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-skippable-daily-chain-base" }, { "type": "object", "description": "A rolling_skippable daily reward for client responses.", "properties": { "id": { "type": "integer", "example": 9, "description": "每日奖励ID。" }, "name": { "type": "string", "example": "Weekly quest", "description": "Daily reward name." }, "description": { "type": [ "string", "null" ], "example": "Major weekly quest", "description": "Daily reward description." }, "order": { "$ref": "#/components/schemas/order" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/client-daily-chain-step-model" } } } } ] }, "client-rolling-unskippable-daily-chain-model": { "allOf": [ { "$ref": "#/components/schemas/rolling-unskippable-daily-chain-base" }, { "type": "object", "description": "A `rolling_unskippable` daily reward for client responses.", "properties": { "id": { "type": "integer", "example": 9, "description": "每日奖励ID。" }, "name": { "type": "string", "example": "Weekly quest", "description": "Daily reward name." }, "description": { "type": [ "string", "null" ], "example": "Major weekly quest", "description": "Daily reward description." }, "order": { "$ref": "#/components/schemas/order" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/client-daily-chain-step-model" } } } } ] }, "client-daily-chain-model": { "oneOf": [ { "$ref": "#/components/schemas/client-calendar-hard-daily-chain-model" }, { "$ref": "#/components/schemas/client-rolling-skippable-daily-chain-model" }, { "$ref": "#/components/schemas/client-rolling-unskippable-daily-chain-model" } ], "discriminator": { "propertyName": "type", "mapping": { "calendar_hard": "#/components/schemas/client-calendar-hard-daily-chain-model", "rolling_skippable": "#/components/schemas/client-rolling-skippable-daily-chain-model", "rolling_unskippable": "#/components/schemas/client-rolling-unskippable-daily-chain-model" } } }, "offer_chain_date_start": { "type": "string", "format": "date-time", "example": "2020-04-15T18:16:00+05:00", "description": "优惠链开始日期。" }, "offer_chain_date_end": { "type": [ "string", "null" ], "format": "date-time", "example": "2020-04-15T18:16:00+05:00", "description": "优惠链结束日期。可为`null`，若`date_end`为`null`则无时间限制。" }, "offer_chain_step_number": { "type": "integer", "example": 2, "description": "步骤编号。", "nullable": false, "minimum": 1 }, "offer_chain_is_free": { "type": "boolean", "description": "是否为免费步骤：" }, "offer_chain_step_price_amount": { "type": "number", "example": 99.99, "description": "步骤的真实货币价格。" }, "offer_chain_step_price_currency": { "type": "string", "example": "USD", "description": "商品价格币种。符合[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母代码。" }, "offer_chain_step_price": { "type": [ "object", "null" ], "properties": { "amount": { "$ref": "#/components/schemas/offer_chain_step_price_amount" }, "currency": { "$ref": "#/components/schemas/offer_chain_step_price_currency" } }, "required": [ "amount", "currency" ] }, "client-offer-chain-item-model": { "type": "object", "properties": { "item_id": { "$ref": "#/components/schemas/item_id" }, "sku": { "$ref": "#/components/schemas/sku" }, "type": { "$ref": "#/components/schemas/item_type" }, "name": { "type": "string", "description": "商品名称。" }, "description": { "type": [ "string", "null" ], "description": "Item description." }, "bundle_type": { "type": [ "string", "null" ], "enum": [ "standard", "virtual_currency_package" ] }, "image_url": { "$ref": "#/components/schemas/image_url" }, "is_free": { "$ref": "#/components/schemas/value-is_free" }, "quantity": { "type": "integer", "description": "商品数量。", "minimum": 1, "example": 1 }, "order": { "$ref": "#/components/schemas/order" }, "content": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/client-offer-chain-item-model" } } } }, "client-offer-chain-step-model": { "type": "object", "description": "优惠链步骤。", "properties": { "step_number": { "$ref": "#/components/schemas/offer_chain_step_number" }, "is_free": { "$ref": "#/components/schemas/offer_chain_is_free" }, "is_claimed": { "type": "boolean", "example": false, "description": "是否已领取或购买了该步骤奖励。" }, "step_price": { "$ref": "#/components/schemas/offer_chain_step_price" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/client-offer-chain-item-model" } }, "step_vp_rewards": { "type": [ "array", "null" ], "description": "来自奖励系统的累充积分数组，作为奖励发放。", "items": { "type": "object", "properties": { "item_id": { "$ref": "#/components/schemas/item_id" }, "sku": { "$ref": "#/components/schemas/value-point-sku" }, "amount": { "$ref": "#/components/schemas/value-point-amount" }, "name": { "$ref": "#/components/schemas/value-point-name" }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "is_clan": { "$ref": "#/components/schemas/is_clan" } } } }, "step_loyalty_rewards": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string", "example": "First Loyalty Point", "description": "忠诚积分名称。" }, "sku": { "type": "string", "example": "0c745ef0-4243-46e1-aa90-54dee07da622", "description": "忠诚积分SKU。" }, "description": { "type": "string", "example": "First Loyalty Point Desc", "description": "Loyalty point description." }, "image_url": { "$ref": "#/components/schemas/image_url" }, "amount": { "type": "integer", "example": 1, "description": "忠诚积分数量。" } } } } } }, "offer_chain_reset_next_date": { "type": "integer", "description": "计算得出的优惠链下次重置的日期和时间，Unix时间戳格式。

例如：月度优惠链重置从2024-03-01 01:00（吉隆坡时间，GMT+8）开始，下次重置为2024-04-01 01:00（吉隆坡时间，GMT+8），对应GMT+0为2024-03-31 17:00，Unix时间戳为`1711904400000`。

示例：`1711904400000`" }, "offer_chain_recurrent_schedule_client_side": { "type": [ "object", "null" ], "description": "优惠链的重置周期。", "properties": { "interval_type": { "type": "string", "description": "优惠链重置频率。", "enum": [ "weekly", "monthly", "hourly" ] }, "reset_next_date": { "$ref": "#/components/schemas/offer_chain_reset_next_date" } } }, "client-offer-chain-model": { "type": "object", "description": "一个优惠链。", "properties": { "id": { "type": "integer", "example": 9, "description": "优惠链ID。" }, "name": { "type": "string", "example": "Weekly quest", "description": "优惠链名称。" }, "description": { "type": [ "string", "null" ], "example": "Major weekly quest", "description": "Offer chain description." }, "order": { "$ref": "#/components/schemas/order" }, "date_start": { "$ref": "#/components/schemas/offer_chain_date_start" }, "date_end": { "$ref": "#/components/schemas/offer_chain_date_end" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/client-offer-chain-step-model" } }, "recurrent_schedule": { "$ref": "#/components/schemas/offer_chain_recurrent_schedule_client_side" }, "next_step_number": { "type": [ "integer", "null" ], "description": "下一步优惠链步骤编号，若优惠链已完成则为`null`。", "example": 1 } } }, "offer-chain-error-model": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-1102]: Unprocessable Entity. The property `property_name` is required" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" }, "errorMessageExtended": { "type": [ "object", "null" ] } } }, "offer_chain_id": { "type": "integer", "example": 9, "description": "优惠链唯一ID。" }, "offer_chain_interval_type_weekly": { "type": "string", "description": "优惠链重置频率。", "enum": [ "weekly" ] }, "offer_chain_day_of_week": { "type": "integer", "description": "每周优惠链重置日，`1`为周一，`7`为周日。", "minimum": 1, "maximum": 7 }, "offer_chain_time": { "type": "string", "description": "在指定时区中重置优惠链的时间（四舍五入到小时）。

例如：吉隆坡时区（GMT+8）重置时间设置为01:00，则`time`参数值为`01:00:00+08:00`。", "pattern": "((0[0-9]|1[0-9]|2[0-3]):00:00)(\\+|-)(0[0-9]|1[0-9]|2[0-3]):([0-5][0-9])", "example": "01:00:00+08:00" }, "offer_chain_displayable_reset_start_date": { "description": "首次优惠链重置的日期和时间。

例如：首次重置为2024-03-01 01:00（吉隆坡时间），使用ISO 8601格式即`2024-03-01T01:00:00+08:00`。

示例：`2024-03-01T01:00:00+08:00`", "type": "string", "format": "date-time" }, "offer_chain_displayable_reset_next_date": { "description": "下次优惠链重置的计算时间，遵循ISO 8601格式。

例如：月度优惠链重置从2024-03-01 01:00（吉隆坡时间）开始，下次重置为2024-04-01 01:00（吉隆坡时间），使用ISO 8601格式即`2024-04-01T01:00:00+08:00`。

示例：`2024-04-01T01:00:00+08:00`", "type": "string", "format": "date-time" }, "offer_chain_interval_type_monthly": { "type": "string", "description": "优惠链重置频率。", "enum": [ "monthly" ] }, "offer_chain_day_of_month": { "type": "integer", "description": "每月优惠链重置日，若当月天数不足，则在该月最后一天重置。", "minimum": 1, "maximum": 31 }, "offer_chain_interval_type_hourly": { "type": "string", "description": "优惠链重置频率。", "enum": [ "hourly" ] }, "offer_chain_hours_interval": { "type": "integer", "description": "优惠链重置的小时间隔。

计时从date_start参数指定的时间开始。

例如，若`date_start = \"2025-11-15T18:15:00+05:00\"`且`hours_interval = 2`，则优惠链将从`\"2025-11-15T20:15:00+05:00\"`开始每2小时重置一次。", "minimum": 1, "maximum": 10000 }, "offer_chain_recurrent_schedule": { "type": [ "object", "null" ], "description": "重复性优惠链的重置周期。", "oneOf": [ { "type": [ "object", "null" ], "title": "interval_type = weekly", "description": "Weekly reset of the offer chain.", "properties": { "interval_type": { "$ref": "#/components/schemas/offer_chain_interval_type_weekly" }, "day_of_week": { "$ref": "#/components/schemas/offer_chain_day_of_week" }, "time": { "$ref": "#/components/schemas/offer_chain_time" }, "reset_next_date": { "$ref": "#/components/schemas/offer_chain_reset_next_date" }, "displayable_reset_start_date": { "$ref": "#/components/schemas/offer_chain_displayable_reset_start_date" }, "displayable_reset_next_date": { "$ref": "#/components/schemas/offer_chain_displayable_reset_next_date" } } }, { "type": "object", "title": "interval_type = monthly", "description": "Monthly reset of the offer chain.", "properties": { "interval_type": { "$ref": "#/components/schemas/offer_chain_interval_type_monthly" }, "day_of_month": { "$ref": "#/components/schemas/offer_chain_day_of_month" }, "time": { "$ref": "#/components/schemas/offer_chain_time" }, "reset_next_date": { "$ref": "#/components/schemas/offer_chain_reset_next_date" }, "displayable_reset_start_date": { "$ref": "#/components/schemas/offer_chain_displayable_reset_start_date" }, "displayable_reset_next_date": { "$ref": "#/components/schemas/offer_chain_displayable_reset_next_date" } } }, { "type": "object", "title": "interval_type = hourly", "description": "Reset of the offer chain performed at the specified time interval in hours.", "properties": { "interval_type": { "$ref": "#/components/schemas/offer_chain_interval_type_hourly" }, "hours_interval": { "$ref": "#/components/schemas/offer_chain_hours_interval" } } } ] }, "admin-offer-chain-short-model": { "type": "object", "description": "一个优惠链。", "properties": { "id": { "$ref": "#/components/schemas/offer_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "date_start": { "$ref": "#/components/schemas/offer_chain_date_start" }, "date_end": { "$ref": "#/components/schemas/offer_chain_date_end" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "recurrent_schedule": { "$ref": "#/components/schemas/offer_chain_recurrent_schedule" }, "is_always_visible": { "$ref": "#/components/schemas/chain_is_always_visible" }, "attribute_conditions": { "$ref": "#/components/schemas/chain_user-attribute_conditions_model-get" } } }, "offer_chain_recurrent_schedule_create_update": { "type": [ "object", "null" ], "description": "优惠链的重置周期。", "oneOf": [ { "type": [ "object", "null" ], "title": "interval_type = weekly", "description": "Weekly reset of the offer chain.", "properties": { "interval_type": { "$ref": "#/components/schemas/offer_chain_interval_type_weekly" }, "day_of_week": { "$ref": "#/components/schemas/offer_chain_day_of_week" }, "time": { "$ref": "#/components/schemas/offer_chain_time" } }, "required": [ "interval_type", "time", "day_of_week" ] }, { "type": "object", "title": "interval_type = monthly", "description": "Monthly reset of the offer chain.", "properties": { "interval_type": { "$ref": "#/components/schemas/offer_chain_interval_type_monthly" }, "day_of_month": { "$ref": "#/components/schemas/offer_chain_day_of_month" }, "time": { "$ref": "#/components/schemas/offer_chain_time" } }, "required": [ "interval_type", "time", "day_of_month" ] }, { "type": "object", "title": "interval_type = hourly", "description": "Reset of the offer chain performed at the specified time interval in hours.", "properties": { "interval_type": { "$ref": "#/components/schemas/offer_chain_interval_type_hourly" }, "hours_interval": { "$ref": "#/components/schemas/offer_chain_hours_interval" } }, "required": [ "interval_type", "hours_interval" ] } ] }, "modify-offer-chain-item-model": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "quantity": { "type": "integer", "description": "此步骤的奖励品数量。", "minimum": 1 }, "order": { "description": "优惠链步骤奖励顺序。", "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "sku", "quantity" ] }, "create-offer-chain-step-model": { "type": "object", "properties": { "step_number": { "$ref": "#/components/schemas/offer_chain_step_number" }, "is_free": { "$ref": "#/components/schemas/offer_chain_is_free" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/modify-offer-chain-item-model" } } }, "required": [ "step_number", "is_free", "items" ] }, "create-offer-chain-model": { "type": "object", "description": "一个优惠链。", "properties": { "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "date_start": { "$ref": "#/components/schemas/offer_chain_date_start" }, "date_end": { "$ref": "#/components/schemas/offer_chain_date_end" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "recurrent_schedule": { "$ref": "#/components/schemas/offer_chain_recurrent_schedule_create_update" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/create-offer-chain-step-model" } }, "is_always_visible": { "$ref": "#/components/schemas/chain_is_always_visible" }, "attribute_conditions": { "$ref": "#/components/schemas/chain_user-attribute_conditions_model-post" } }, "required": [ "name", "date_start", "steps", "is_enabled" ] }, "offer_chain_step_id": { "type": [ "integer", "null" ], "example": 10, "description": "链步骤的唯一ID。", "minimum": 1 }, "admin-offer-chain-item-model": { "type": "object", "properties": { "item_id": { "$ref": "#/components/schemas/item_id" }, "sku": { "$ref": "#/components/schemas/sku" }, "type": { "$ref": "#/components/schemas/item_type" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "image_url": { "$ref": "#/components/schemas/image_url" }, "is_free": { "$ref": "#/components/schemas/value-is_free" }, "quantity": { "type": "integer", "description": "商品数量。", "minimum": 1, "example": 1 }, "order": { "$ref": "#/components/schemas/order" } } }, "admin-offer-chain-step-model": { "type": "object", "description": "优惠链步骤。", "properties": { "step_id": { "$ref": "#/components/schemas/offer_chain_step_id" }, "step_number": { "$ref": "#/components/schemas/offer_chain_step_number" }, "is_free": { "$ref": "#/components/schemas/offer_chain_is_free" }, "step_price": { "$ref": "#/components/schemas/offer_chain_step_price" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/admin-offer-chain-item-model" } } } }, "admin-offer-chain-long-model": { "type": "object", "description": "一个优惠链。", "properties": { "id": { "$ref": "#/components/schemas/offer_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "date_start": { "$ref": "#/components/schemas/offer_chain_date_start" }, "date_end": { "$ref": "#/components/schemas/offer_chain_date_end" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "recurrent_schedule": { "$ref": "#/components/schemas/offer_chain_recurrent_schedule" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/admin-offer-chain-step-model" } }, "is_always_visible": { "$ref": "#/components/schemas/chain_is_always_visible" }, "attribute_conditions": { "$ref": "#/components/schemas/chain_user-attribute_conditions_model-get" } } }, "update_step_id": { "type": [ "integer", "null" ], "example": 10, "description": "链步骤的唯一ID。更新时指定以保留用户进度。", "minimum": 1 }, "modify-offer-chain-step-model": { "type": "object", "properties": { "step_id": { "$ref": "#/components/schemas/update_step_id" }, "step_number": { "$ref": "#/components/schemas/offer_chain_step_number" }, "is_free": { "$ref": "#/components/schemas/offer_chain_is_free" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/modify-offer-chain-item-model" } } }, "required": [ "step_number", "is_free", "items" ] }, "modify-offer-chain-model": { "type": "object", "description": "一个优惠链。", "properties": { "id": { "$ref": "#/components/schemas/offer_chain_id" }, "name": { "$ref": "#/components/schemas/name-localization-object" }, "order": { "$ref": "#/components/schemas/order" }, "description": { "$ref": "#/components/schemas/description-localization-object" }, "date_start": { "$ref": "#/components/schemas/offer_chain_date_start" }, "date_end": { "$ref": "#/components/schemas/offer_chain_date_end" }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "recurrent_schedule": { "$ref": "#/components/schemas/offer_chain_recurrent_schedule_create_update" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/modify-offer-chain-step-model" } }, "is_always_visible": { "$ref": "#/components/schemas/chain_is_always_visible" }, "attribute_conditions": { "$ref": "#/components/schemas/chain_user-attribute_conditions_model-post" } }, "required": [ "name", "date_start", "steps", "is_enabled" ] }, "bundle_type": { "type": "string", "description": "捆绑包类型。当商品类型为捆绑包时返回。", "enum": [ "standard", "virtual_currency_package", "partner_side_content" ] }, "unit_type": { "type": "string", "example": "game", "description": "单元类型：`game`。" }, "drm_name": { "type": "string", "example": "Steam", "description": "游戏Key DRM名称。" }, "drm_sku": { "type": "string", "example": "steam", "description": "DRM唯一ID。" }, "Upsell-model": { "type": "object", "description": "追加销售类型。", "properties": { "type": { "type": "string", "enum": [ "fixed_list" ], "example": true }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "items": { "type": "array", "example": [ "game_sku" ], "default": null, "description": "商品SKU数组。", "items": { "type": "string" } } }, "required": [ "is_enabled", "type", "items" ] }, "Upsell-model-not-fixed-list": { "type": "object", "description": "追加销售类型。", "properties": { "type": { "type": "string", "enum": [ "most_sellable", "only_promotions" ], "example": true }, "is_enabled": { "$ref": "#/components/schemas/is_enabled" }, "items": { "type": "array", "example": [ null ], "default": null, "description": "空的商品SKU数组。", "items": { "type": "string" } } }, "required": [ "is_enabled", "type" ] }, "Upsell-422-invalid-request": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-1102]: Unprocessable entity. The property `is_enabled` is required" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } }, "Virtual-Items-Currency_admin-groups-response": { "type": "array", "example": [ { "external_id": "horror", "name": { "en": "Horror" } } ], "default": [], "description": "商品所属分组。", "items": { "type": "object", "properties": { "external_id": { "type": "string", "example": "horror" }, "name": { "type": "object", "description": "商品名称。应包含键/值对，\n其中键是\"^[a-z]{2}\"格式的区域设置，值是字符串。", "example": { "en": "Horror", "de": "Horror" }, "default": { "en": "Horror" }, "additionalProperties": { "type": "string" } } } } }, "Virtual-Items-Currency_client-attributes": { "type": "array", "description": "与商品对应的属性及其值的列表。可用于商品目录筛选。", "example": { "value": { "external_id": "genre", "name": "Жанр", "values": [ { "external_id": "genre_e3364991f92e751689a68b96598a5a5a84010b85", "value": "Casual" }, { "external_id": "genre_eba07bfd0f982940773cba3744d97264dd58acd7", "value": "Strategy" }, { "external_id": "genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8", "value": "Mobile" } ] } }, "default": [], "items": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/admin-attribute-external_id" }, "name": { "type": "object", "description": "属性名称。", "example": "Genre", "additionalProperties": { "type": [ "string", "null" ] } }, "values": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "$ref": "#/components/schemas/value-external_id" }, "value": { "type": "string", "description": "属性值。", "example": "Strategy" } } } } } } }, "item-periods-response": { "type": "array", "description": "商品销售期。", "items": { "type": "object", "properties": { "date_from": { "type": [ "string", "null" ], "format": "date-time", "example": "2020-08-11T10:00:00+03:00", "description": "指定商品开始可购的日期。" }, "date_until": { "type": [ "string", "null" ], "format": "date-time", "example": "2020-08-11T20:00:00+03:00", "description": "指定商品停止可购的日期。可为`null`。" } } } }, "item-custom-attributes-response": { "type": "object", "description": "包含商品属性和值的JSON对象。", "format": "json" }, "Upsell_item": { "type": "object", "properties": { "sku": { "type": "string", "example": "big_rocket", "description": "唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。" }, "name": { "type": "string", "example": "Big Rocket", "description": "商品名称。" }, "groups": { "$ref": "#/components/schemas/Virtual-Items-Currency_admin-groups-response" }, "attributes": { "$ref": "#/components/schemas/Virtual-Items-Currency_client-attributes" }, "type": { "type": "string", "example": "virtual_good", "description": "商品类型：`virtual_good`/`virtual_currency`/`bundle`。" }, "description": { "type": "string", "example": "Big Rocket - description", "description": "Item description." }, "image_url": { "type": "string", "example": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png", "description": "图片URL。" }, "is_free": { "$ref": "#/components/schemas/value-is_free" }, "price": { "type": [ "object", "null" ], "description": "商品价格。", "properties": { "amount": { "type": "string", "example": "100.99", "description": "商品折后价格。" }, "amount_without_discount": { "type": "string", "example": "100.99", "description": "商品价格。" }, "currency": { "type": "string", "example": "USD", "description": "商品价格币种。符合[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母代码。" } } }, "virtual_prices": { "type": "array", "description": "虚拟价格。", "items": { "type": "object", "description": "虚拟价格。", "properties": { "amount": { "type": "integer", "example": 100, "description": "以虚拟货币表示的商品折后价格。" }, "amount_without_discount": { "type": "integer", "example": 200, "description": "商品价格。" }, "sku": { "type": "string", "example": "vc_test", "description": "虚拟货币商品SKU。" }, "is_default": { "type": "boolean", "example": true, "description": "价格是否为商品默认价格。" }, "image_url": { "type": "string", "example": "http://image.png", "description": "虚拟货币图片。" }, "name": { "type": "string", "example": "SHOTGUN FOR TRUE RAIDERS", "description": "虚拟货币名称。" }, "type": { "type": "string", "example": "virtual_currency", "description": "虚拟货币类型。" }, "description": { "type": "string", "example": "Big Rocket - description", "description": "Virtual currency description." } } } }, "can_be_bought": { "$ref": "#/components/schemas/Can_be_bought" }, "virtual_item_type": { "type": "string", "example": "non-consumable", "description": "虚拟物品的类型。\n\n可能值：\n- `consumable` — 使用后会从物品库中消失的商品（例如弹药）。\n- `non_consumable` — 可无限期保留在物品库中的商品。\n- `non_renewing_subscription` — 时效性商品，可表示在限定时间内对服务或内容的访问权限。\"", "enum": [ "consumable", "non_consumable", "non_renewing_subscription" ] }, "promotions": { "$ref": "#/components/schemas/Catalog_item_promotions" }, "limits": { "$ref": "#/components/schemas/Catalog_item_limits" }, "periods": { "$ref": "#/components/schemas/item-periods-response" }, "custom_attributes": { "$ref": "#/components/schemas/item-custom-attributes-response" }, "vp_rewards": { "$ref": "#/components/schemas/client-item-value-point-reward" } } }, "Upsell_item-list": { "type": "object", "properties": { "has_more": { "$ref": "#/components/schemas/Pagination_has-more" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Upsell_item" } } } } }, "examples": { "Promotions_200-admin-promotions": { "value": { "promotions": [ { "id": 1, "promotion_periods": [ { "date_from": "2020-01-01T00:00:00+03:00", "date_until": null } ], "name": { "en": "promotion_1" }, "type": "item_bonus", "is_enabled": true, "bonus": [ { "item": { "description": null, "image_url": null, "sku": "com.xsolla.diamonds_pack_1", "name": { "en": "Diamonds pack", "ru": "Пак кристаллов" }, "type": "bundle", "bundle_type": "virtual_currency_package", "content": [] }, "quantity": 1 } ], "condition": [ { "item": { "description": null, "image_url": null, "sku": "com.xsolla.virtual_good_bonus_2", "name": { "en": "VG name", "ru": "Название VG" }, "type": "virtual_good" } } ], "discount": null }, { "id": 2, "promotion_periods": [ { "date_from": "2020-01-01T00:00:00+03:00", "date_until": "2030-01-01T00:00:00+03:00" } ], "name": { "en": "promotion_2" }, "type": "item_discount", "is_enabled": false, "bonus": [], "condition": [ { "item": { "description": null, "image_url": null, "sku": "com.xsolla.virtual_good_bonus_2", "name": { "en": "VG name", "ru": "Название VG" }, "type": "virtual_good" } } ], "discount": { "percent": "10.99" } }, { "id": 3, "promotion_periods": [ { "date_from": "2020-01-01T00:00:00+03:00", "date_until": "2030-01-01T00:00:00+03:00" } ], "name": { "en": "promotion_3" }, "type": "coupon_bonus", "is_enabled": true, "bonus": [ { "item": { "description": null, "image_url": null, "sku": "com.xsolla.virtual_good_bonus_2", "name": { "en": "VG name", "ru": "Название VG" }, "type": "virtual_good" }, "quantity": 2 } ], "condition": [ { "item": { "external_id": "coupon_2", "name": { "en": "Coupon name", "ru": "Название купона" }, "is_enabled": true, "redeem_total_limit": null, "redeem_user_limit": null, "redeem_code_limit": 1 } } ], "discount": null }, { "id": 4, "promotion_periods": [ { "date_from": "2018-01-01T00:00:00+03:00", "date_until": "2031-01-01T00:00:00+03:00" } ], "name": { "en": "promotion_4" }, "type": "promocode_bonus_discount", "is_enabled": false, "bonus": [ { "item": { "description": null, "image_url": null, "sku": "com.xsolla.virtual_good_bonus_2", "name": { "en": "VG name", "ru": "Название VG" }, "type": "virtual_good" }, "quantity": 2 } ], "condition": [ { "item": { "external_id": "coupon_3", "name": { "en": "Coupon name", "ru": "Название купона" }, "is_enabled": true, "redeem_total_limit": null, "redeem_user_limit": null, "redeem_code_limit": 1 } } ], "discount": { "percent": "12.99" } }, { "id": 5, "promotion_periods": [ { "date_from": "2020-01-01T00:00:00+03:00", "date_until": null } ], "name": { "en": "promotion_5" }, "type": "cart_bonus", "is_enabled": true, "bonus": [ { "item": { "description": null, "image_url": null, "sku": "com.xsolla.virtual_good_bonus_4", "name": { "en": "VG name", "ru": "Название VG" }, "type": "virtual_good" }, "quantity": 1 } ], "condition": null, "discount": null } ], "total_promotions_count": 5, "active_promotions_count": 3, "inactive_promotions_count": 2 } }, "422-activate-deactivate-promotion": { "value": { "statusCode": 422, "errorCode": 9505, "errorMessage": "[0401-9505]: Error was occurred while promotion was being updated", "transactionId": "da145238620011eb8e24fe6913ff226a" } }, "Promotions_200-get-coupon-rewards": { "value": { "bonus": [ { "item": { "sku": "com.xsolla.game_1", "name": { "en": "Game name" }, "type": "unit", "description": "Game description", "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "unit_items": [ { "sku": "com.xsolla.game_key_01", "name": "Game name", "type": "game_key", "is_free": false, "drm_name": "Steam", "drm_sku": "steam_key_01" }, { "sku": "game_key_02", "name": "Game name", "type": "game_key", "drm_name": "Origin", "drm_sku": "origin_key_02" } ] }, "quantity": 1 }, { "item": { "sku": "com.xsolla.game_2", "name": { "en": "Game name" }, "type": "unit", "description": "Game description", "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "unit_items": [ { "sku": "com.xsolla.game_key_01", "type": "game_key", "name": "Game name", "drm_name": "Steam", "drm_sku": "steam_key_01" } ] }, "quantity": 2 } ], "discount": { "percent": "10.00" }, "is_selectable": true } }, "Promotions_200-admin-coupons": { "value": { "items": [ { "external_id": "coupon_44056_1", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "is_enabled": true, "bonus": [ { "sku": "com.xsolla.elven_sword_1", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_1", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_1", "quantity": 2 } ], "redeem_user_limit": null, "redeem_total_limit": null, "redeem_code_limit": 1, "total_limit_state": null }, { "external_id": "summer2021", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "Coupon name", "de-DE": "Gutscheintitel" }, "is_enabled": true, "bonus": [ { "sku": "com.xsolla.diamonds_1", "quantity": 100 } ], "redeem_user_limit": null, "redeem_total_limit": 100, "redeem_code_limit": 1, "total_limit_state": { "available": 50, "reserved": 10, "used": 40 } } ], "total_promotions_count": 2, "active_promotions_count": 2, "inactive_promotions_count": 0 } }, "Promotions_200-coupon-code-list": { "value": { "codes": [ { "code": "CODE001" }, { "code": "CODE002" }, { "code": "CODE003" }, { "code": "CODE004" }, { "code": "CODE005" } ], "total_count": 5 } }, "Promotions_200-get-promocode-rewards": { "value": { "bonus": [ { "item": { "sku": "com.xsolla.game_1", "name": "Game name", "type": "unit", "description": "Game description", "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "unit_items": [ { "sku": "com.xsolla.game_key_01", "name": "Game name", "type": "game_key", "is_free": false, "drm_name": "Steam", "drm_sku": "steam_key_01" }, { "sku": "com.xsolla.game_key_02", "name": "Game name", "type": "game_key", "drm_name": "Origin", "drm_sku": "origin_key_02" } ] }, "quantity": 1 }, { "item": { "sku": "com.xsolla.game_2", "name": "Game name", "type": "unit", "description": "Game description", "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "unit_items": [ { "sku": "com.xsolla.game_key_01", "type": "game_key", "name": "Game name", "drm_name": "Steam", "drm_sku": "steam_key_01" } ] }, "quantity": 2 } ], "discount": { "percent": "10.00" }, "is_selectable": true, "discounted_items": [ { "sku": "com.xsolla.elven_sword_1", "discount": { "percent": "10.00" } } ] } }, "Promotions_200-admin-promocodes": { "value": { "items": [ { "external_id": "promocode_100_crystals", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "is_enabled": true, "bonus": [ { "sku": "com.xsolla.elven_sword_1", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_1", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_1", "quantity": 2 } ], "redeem_user_limit": null, "redeem_total_limit": null, "redeem_code_limit": 1, "total_limit_state": null, "discount": null, "discounted_items": null }, { "external_id": "summer2021", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "Coupon name", "de-DE": "Gutscheintitel" }, "is_enabled": true, "bonus": [ { "sku": "com.xsolla.diamonds_1", "quantity": 100 } ], "redeem_user_limit": null, "redeem_total_limit": 100, "redeem_code_limit": null, "total_limit_state": { "available": 50, "reserved": 10, "used": 40 }, "discount": { "percent": "10.99" }, "discounted_items": [ { "sku": "com.xsolla.elven_sword_1", "discount": { "percent": "10.00" } } ], "price_conditions": [ { "operator": "ge", "value": "10.0000" }, { "operator": "le", "value": "50.0000" } ], "excluded_promotions": [ 23, 45 ] } ], "total_promotions_count": 2, "active_promotions_count": 2, "inactive_promotions_count": 0 } }, "Promotions_200-admin-unique-catalog-offers": { "value": { "items": [ { "external_id": "new_year_bonus", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "items": [ "booster", "booster_mega" ], "is_enabled": true, "redeem_user_limit": 1, "redeem_total_limit": null, "redeem_code_limit": 1, "total_limit_state": null }, { "external_id": "secret_store", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": null } ], "name": { "en-US": "Secret store", "ru-RU": "Тайный магазин" }, "items": [ "helmet", "armor", "sword" ], "is_enabled": true, "redeem_user_limit": 1, "redeem_total_limit": 100, "redeem_code_limit": 1, "total_limit_state": { "available": 50, "reserved": 10, "used": 40 } } ], "total_promotions_count": 2, "active_promotions_count": 2, "inactive_promotions_count": 0 } }, "404-coupon-not-found": { "value": { "statusCode": 404, "errorCode": 9802, "errorMessage": "[0401-9802]: Coupon not found", "transactionId": "x-x-x-x-transactionId-mock-x-x-x" } }, "404-user-not-found": { "value": { "statusCode": 404, "errorCode": 5008, "errorMessage": "[0401-5008]: Could not find User", "transactionId": "transaction id" } }, "Promotions_422-invalid-coupon": { "value": { "statusCode": 422, "errorCode": 1102, "errorMessage": "[0401-1102]: Unprocessable Entity. The property `external_id` is required" } }, "code-limit": { "value": { "promotion_id": 1, "items": [ { "code": "WINTER2023", "per_code": { "total": 10, "available": 7, "used": 2, "reserved": 1 } }, { "code": "SUMMER2023", "per_code": { "total": 5, "available": 0, "used": 3, "reserved": 2 } } ], "total_items_count": 2, "has_more": false } }, "401-complex-auth-header-not-found": { "value": { "statusCode": 401, "errorCode": 1501, "errorMessage": "[0401-1501]: Authorization failed: Authorization header not sent", "transactionId": "x-x-x-x-transactionId-mock-x-x-x" } }, "401-complex-auth-incorrect-credentials": { "value": { "statusCode": 401, "errorCode": 1013, "errorMessage": "[0401-1013]: Token not found.", "transactionId": "x-x-x-x-transactionId-mock-x-x-x" } }, "422-user_external_id_invalid": { "value": { "statusCode": 404, "errorCode": 1102, "errorMessage": "[0401-1102]: Unprocessable Entity", "transactionId": "transaction id", "errorMessageExtended": [ { "property": "user_external_id", "message": "Must be at least 1 characters long" }, { "property": "user_external_id", "message": "Does not match the regex pattern ^\\S+$" } ] } }, "404-promotion-by-id-not-found": { "value": { "statusCode": 404, "errorCode": 1101, "errorMessage": "[0401-1101]: Promotion not found", "transactionId": "transaction id" } }, "422-promotion-without-user-limit": { "value": { "statusCode": 422, "errorCode": 4509, "errorMessage": "[0401-4509]: Promotion does not have configured user limits.", "transactionId": "transaction id" } }, "422-promotion-out-of-range-available-user-limit": { "value": { "statusCode": 422, "errorCode": 4511, "errorMessage": "[0401-4511]: Available promotion limit is out of range.", "transactionId": "transaction id" } }, "200-value-points-reward-chain_admin_get-value-point-list": { "value": { "items": [ { "sku": "com.xsolla.reward_vp_1", "name": { "en": "Reward VP 1" }, "type": "value_point", "is_enabled": true, "description": { "en": "Points for reward system" }, "long_description": { "en": "Points given to users to get new rewards in a reward chain." }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 1, "is_clan": false }, { "sku": "com.xsolla.reward_vp_2", "name": { "en": "Reward VP 2" }, "type": "value_point", "is_enabled": false, "description": { "en": "Value points for reward system." }, "long_description": { "en": "Value points given to users to get new rewards in a reward chain." }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 2, "is_clan": false }, { "sku": "com.xsolla.clan_value_point_1", "name": { "en": "Clan Reward VP 1" }, "is_enabled": true, "description": { "en": "Value points for clan reward system." }, "long_description": { "en": "Value points given to clans to get new rewards in a reward chain." }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 3, "is_clan": true } ] } }, "422-property-sku-is-required": { "value": { "statusCode": 422, "errorCode": 1102, "errorMessage": "[0401-1102]: Unprocessable Entity. The property `sku` is required", "transactionId": "da145238620011eb8e24fe6913ff226a" } }, "200-value-points-reward-chain_admin_get-value-point": { "value": { "sku": "com.xsolla.reward_vp_1", "name": { "en": "Reward VP 1" }, "type": "value_point", "is_enabled": true, "description": { "en": "Points for reward system" }, "long_description": { "en": "Points given to users to get new rewards in a reward chain." }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 1, "is_clan": false, "can_delete": false } }, "200-value-points-rewards-list": { "value": { "items": [ { "item_id": 14232, "sku": "com.xsolla.booster_1", "name": { "en": "Booster" }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "amount": 100 }, { "item_id": 14232, "sku": "com.xsolla.booster_mega", "name": { "en": "Mega Booster" }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "amount": 200 } ] } }, "200-client-get-reward-chains-list": { "value": { "has_more": false, "total_items_count": 1, "items": [ { "reward_chain_id": 10, "name": "Weekly quest", "description": "Big weekly quest", "long_description": "You can get a lot of additional items just by shopping during the week", "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2023-04-25T18:16:00+05:00", "value_point": { "sku": "com.xsolla.value_point_1", "name": "Value point", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "description": null, "long_description": null, "amount": 130 }, "clan_type": null, "top_contributors": [], "steps": [ { "step_id": 1, "name": "Level 1", "is_claimed": true, "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "price": { "amount": 100 }, "reward": [ { "sku": "com.xsolla.box_1", "name": "Super box", "type": "bundle", "description": "Super box with items", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 1 }, { "sku": "com.xsolla.box_2", "name": "Mega box", "type": "bundle", "description": "Mega box with items", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 1 } ] }, { "step_id": 2, "name": "Level 2", "is_claimed": false, "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "price": { "amount": 200 }, "reward": [ { "sku": "com.xsolla.box_1", "name": "Super box", "type": "bundle", "description": "Super box with items", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 2 }, { "sku": "com.xsolla.box_2", "name": "Mega box", "type": "bundle", "description": "Mega box with items", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 2 } ] } ], "recurrent_schedule": { "interval_type": "weekly", "reset_next_date": 1746057600 }, "popup_header": null, "popup_instruction": null, "popup_image_url": null }, { "reward_chain_id": 12, "name": "Weekly clan quest", "description": "Major weekly clan quest.", "long_description": "You and your clan members can get additional items for shopping during a certain month.", "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 2, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2023-10-15T18:16:00+05:00", "value_point": { "sku": "com.xsolla.clan_value_point_1", "name": "Clan Reward VP 1", "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "description": "Value points for clan reward system.", "long_description": "Value points given to clans to get new rewards in a reward chain.", "amount": 80 }, "clan_type": "guild", "top_contributors": [ { "name": "Rabbit", "contributed_amount": 100 }, { "name": "Rocket", "contributed_amount": 80 }, { "name": "Rain", "contributed_amount": 40 } ], "steps": [ { "step_id": 1, "name": "Level 1", "is_claimed": true, "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "price": { "amount": 100 }, "reward": [ { "sku": "com.xsolla.box_1", "name": "Super box", "type": "bundle", "description": "Super box with items", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 1 }, { "sku": "com.xsolla.box_2", "name": "Mega box", "type": "bundle", "description": "Mega box with items", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 1 } ] }, { "step_id": 2, "name": "Level 2", "is_claimed": false, "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "price": { "amount": 200 }, "reward": [ { "sku": "com.xsolla.box_1", "name": "Super box", "type": "bundle", "description": "Super box with items", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 2 }, { "sku": "com.xsolla.box_2", "name": "Mega box", "type": "bundle", "description": "Mega box with items", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 2 } ] } ], "recurrent_schedule": { "interval_type": "monthly", "reset_next_date": 1746057600 }, "popup_header": { "en": "How to unlock rewards" }, "popup_instruction": { "en": "You should be a clan member to get clan rewards. You join a clan when a clan member invited you to the clan, and you accepted the invite. You can create your own clan." }, "popup_image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png" } ] } }, "200-client-get-user-reward-chain-balance": { "summary": "Reward chain example", "value": { "sku": "com.xsolla.value_point_1", "name": "Value point", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "description": null, "long_description": null, "amount": 130, "is_clan": false } }, "200-client-get-user-clan-reward-chain-balance": { "summary": "Clan reward chain example", "value": { "sku": "com.xsolla.clan_value_point_1", "name": "Clan Reward VP 1", "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "description": "Value points for clan reward system.", "long_description": "Value points given to clans to get new rewards in a reward chain.", "amount": 80, "is_clan": true } }, "200-client-update-user-clan": { "value": { "reward": [ { "sku": "com.xsolla.box_1", "name": "Super box", "type": "bundle", "description": "Super box with items", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 1, "bundle_type": "standard" }, { "sku": "com.xsolla.potion_1", "name": "Mega potion", "type": "virtual_good", "description": "Mega potion", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "quantity": 1 } ] } }, "200-reward-chain-list": { "value": { "has_more": true, "items": [ { "name": { "en": "Reward chain" }, "reward_chain_id": 1, "description": { "en": "Reward chain description" }, "long_description": { "en": "Reward chain long description" }, "is_enabled": true, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "periods": [ { "date_from": "2026-01-01T01:00:00+05:00", "date_until": "2026-01-31T23:59:59+05:00" }, { "date_from": "2026-02-01T01:00:00+05:00", "date_until": "2026-02-28T23:59:59+05:00" } ], "value_point": { "sku": "com.xsolla.reward_vp_1", "name": { "en": "Reward VP 1" }, "type": "value_point", "is_enabled": true, "description": "Value points for standard reward system.", "long_description": "Value points given to users to get new rewards in a reward chain.", "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 1, "is_clan": false }, "recurrent_schedule": null, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "ork", "type": "string", "can_be_missing": false } ], "is_always_visible": true, "is_reset_after_end": true }, { "name": { "en": "Clan reward chain" }, "reward_chain_id": 2, "description": { "en": "Clan reward chain description." }, "long_description": { "en": "Clan reward chain long description." }, "is_enabled": true, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "periods": [ { "date_from": "2026-01-01T01:00:00+05:00", "date_until": "2026-01-31T23:59:59+05:00" }, { "date_from": "2026-02-01T01:00:00+05:00", "date_until": "2026-02-28T23:59:59+05:00" } ], "value_point": { "sku": "com.xsolla.clan_value_point_1", "name": { "en": "Clan Reward VP 1" }, "is_enabled": true, "description": "Value points for clan reward system.", "long_description": "Value points given to clans to get new rewards in a reward chain.", "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 1, "is_clan": true }, "recurrent_schedule": { "day_of_month": null, "day_of_week": 2, "displayable_reset_next_date": "2026-01-06T01:00:00+05:00", "displayable_reset_start_date": "2026-01-01T01:00:00+05:00", "interval_type": "weekly", "reset_next_date": 1767643200, "time": "01:00:00+05:00" }, "popup_header": { "en": "How to unlock rewards" }, "popup_instruction": { "en": "You must be a clan member in order to get clan rewards. You join a clan when a clan member invites you to the clan, and you accept the invite. You can also create your own clan." }, "popup_image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "clan_type": "guild" } ] } }, "200-reward-chain": { "summary": "Reward chain example", "value": { "reward_chain_id": 1, "name": { "en": "Reward chain" }, "description": { "en": "Reward chain description" }, "long_description": { "en": "Reward chain long description" }, "is_enabled": true, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "periods": [ { "date_from": "2026-01-01T01:00:00+05:00", "date_until": "2026-01-31T23:59:59+05:00" }, { "date_from": "2026-02-01T01:00:00+05:00", "date_until": "2026-02-28T23:59:59+05:00" } ], "value_point": { "sku": "com.xsolla.reward_vp_1", "name": { "en": "Reward VP 1" }, "type": "value_point", "is_enabled": true, "description": { "en": "Value points for reward system." }, "long_description": { "en": "Value points given to users to get new rewards in a reward chain." }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 1, "is_clan": false }, "steps": [ { "name": { "en": "First step of the reward chain" }, "step_id": 1, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_1", "quantity": 5 }, { "sku": "com.xsolla.item_2", "quantity": 1 } ], "price": { "amount": 10 } }, { "name": { "en": "Second step of the reward chain" }, "step_id": 2, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_3", "quantity": 5 }, { "sku": "com.xsolla.item_4", "quantity": 1 } ], "price": { "amount": 15 } } ], "recurrent_schedule": { "day_of_week": 2, "displayable_reset_next_date": "2026-01-06T01:00:00+05:00", "displayable_reset_start_date": "2026-01-01T01:00:00+05:00", "interval_type": "weekly", "reset_next_date": 1767643200, "time": "01:00:00+05:00" }, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "ork", "type": "string", "can_be_missing": false } ], "is_always_visible": true, "is_reset_after_end": true } }, "200-clan-reward-chain": { "summary": "Clan reward chain example", "value": { "reward_chain_id": 1, "name": { "en": "Clan reward chain" }, "description": { "en": "Clan reward chain description." }, "long_description": { "en": "Clan reward chain long description." }, "is_enabled": true, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2021-04-15T18:16:00+05:00" } ], "value_point": { "sku": "com.xsolla.clan_value_point_1", "name": { "en": "Clan Reward VP 1" }, "is_enabled": true, "description": { "en": "Value points for clan reward system." }, "long_description": { "en": "Value points given to clans to get new rewards in a certain reward chain." }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 1, "is_clan": true }, "steps": [ { "name": { "en": "First step of the reward chain" }, "step_id": 1, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_1", "quantity": 5 }, { "sku": "com.xsolla.item_2", "quantity": 1 } ], "price": { "amount": 10 } }, { "name": { "en": "Second step of the reward chain" }, "step_id": 2, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_3", "quantity": 5 }, { "sku": "com.xsolla.item_4", "quantity": 1 } ], "price": { "amount": 15 } } ], "recurrent_schedule": { "day_of_week": 2, "displayable_reset_next_date": "2023-03-07T11:00:00+08:00", "displayable_reset_start_date": "2023-02-28T11:00:00+08:00", "interval_type": "weekly", "reset_next_date": 1677553200, "time": "11:00:00+08:00" }, "popup_header": { "en": "How to unlock rewards" }, "popup_instruction": { "en": "You must be a clan member in order to get clan rewards. You join a clan when a clan member invites you to the clan, and you accept the invite. You can also create your own clan." }, "popup_image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "clan_type": "guild" } }, "200-admin-daily-chain-list": { "summary": "Daily reward list example", "value": { "has_more": false, "total_items_count": 3, "items": [ { "id": 1, "name": { "en": "Daily reward", "ru": "Ежедневная награда" }, "description": { "en": "Daily reward short description" }, "order": 1, "number_of_steps": 10, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "is_enabled": false, "is_recurrent": true, "type": "calendar_hard" }, { "id": 2, "name": { "en": "Monthly daily reward", "ru": "Ежедневные награды в цепочке на месяц" }, "description": { "en": "Monthly daily reward short description" }, "order": 2, "number_of_steps": 13, "date_start": "2025-04-15T00:00:00+08:00", "date_end": "2025-04-28T15:00:00+08:00", "is_enabled": false, "is_recurrent": true, "type": "calendar_hard" }, { "id": 3, "name": { "en": "Login reward" }, "description": { "en": "Login reward short description" }, "order": 3, "number_of_steps": 7, "date_start": "2023-05-01T18:16:00+05:00", "date_end": "2025-05-31T18:16:00+05:00", "is_enabled": true, "is_recurrent": true, "type": "rolling_skippable" }, { "id": 4, "name": { "en": "Daily reward", "ru": "Ежедневная награда" }, "description": { "en": "Daily reward short description" }, "order": 4, "number_of_steps": 10, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "is_enabled": true, "is_recurrent": true, "type": "calendar_hard" }, { "id": 5, "name": { "en": "Unskippable login reward" }, "description": { "en": "Unskippable login reward short description" }, "order": 3, "number_of_steps": 7, "date_start": "2025-11-01T10:00:00+05:00", "date_end": "2025-11-30T10:00:00+05:00", "is_enabled": true, "is_recurrent": true, "type": "rolling_unskippable" } ] } }, "422-admin-daily-chain-error-too-many-steps": { "summary": "Too many steps", "description": "Daily reward steps max amount limit of 30 items is exceeded. Try specifying less steps.", "value": { "statusCode": 422, "errorCode": 6203, "errorMessage": "[0401-6203]: Chain step count exceeds the allowed limit", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "step_count": 31, "max_steps": 30 } } }, "422-admin-daily-chain-error-incorrect-steps-order": { "summary": "Incorrect steps order", "description": "Daily reward steps numbers sequence is incorrect. Correct step numbers should be sequential without any gaps or duplicates.", "value": { "statusCode": 422, "errorCode": 6210, "errorMessage": "[0401-6210]: Chain step numbers are invalid", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "incorrect_step_numbers": { "duplicates": [ 2, 7 ], "out_of_range": [ 7, 8 ], "missing": [ 3, 4, 5, 6 ] } } } }, "422-admin-daily-chain-error-item-limit-exceeded": { "summary": "Item limit exceeded", "description": "Daily reward step item count exceeds the allowed limit for some steps. Currently only 1 item per step is allowed.", "value": { "statusCode": 422, "errorCode": 6208, "errorMessage": "[0401-6208]: Chain step item count exceeds the allowed limit for some steps", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "max_items": 1, "steps_exceeded_limits": [ { "step_number": 1, "items_count": 2 }, { "step_number": 4, "items_count": 3 } ] } } }, "422-admin-daily-chain-error-incorrect-items": { "summary": "Incorrect step items", "description": "Specified items are not allowed, disabled or not found. Only enabled items of following types are allowed: virtual item, bundle, virtual currency package.", "value": { "statusCode": 422, "errorCode": 6211, "errorMessage": "[0401-6211]: Chain steps items are not allowed or not found", "transactionId": "x-x-xX-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "invalid_items": { "not_found": [ "vg_deleted_item_1", "vg_deleted_item_2", "not_existing_sku_404_1", "not_existing_sku_404_2" ], "disabled": [ "vg_disabled_item_1", "vg_disabled_item_2", "vc_disabled_1" ], "invalid_item_type": { "allowed_item_type_list": [ "virtual_good", "bundle" ], "sku_map": { "vc_enabled_shown_in_store_1": "virtual_currency", "vc_disabled_1": "virtual_currency", "unit_enabled_shown_in_store_1": "unit", "gk_steam_enabled_shown_in_store_1": "game_key" } } } } } }, "422-admin-daily-chain-error-invalid-dates": { "summary": "Invalid date format", "description": "Please, ensure dates format is valid.", "value": { "statusCode": 422, "errorCode": 6204, "errorMessage": "[0401-6204]: Period of a chain is invalid. Please, check the dates in your request", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 1, "invalid_format_dates": { "date_start": "2023-04-15 17:16:00Z", "date_end": "2025-04-25 19:16:00Z" } } } }, "422-admin-daily-chain-error-incorrect-period": { "summary": "Incorrect period of a daily reward", "description": "Please ensure start date is earlier than end date.", "value": { "statusCode": 422, "errorCode": 6204, "errorMessage": "[0401-6204]: Period of a chain is invalid. Please, check the dates in your request", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 1, "invalid_periods": [ { "start": "2025-04-25T18:16:00+05:00", "end": "2023-04-15T18:16:00+05:00" } ] } } }, "200-admin-daily-chain": { "summary": "Daily reward example", "value": { "id": 3, "name": { "en": "Daily reward", "ru": "Ежедневная награда" }, "description": { "en": "Daily reward short description" }, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "order": 1, "is_recurrent": false, "number_of_steps": 3, "steps": [ { "step_id": 7, "step_number": 1, "items": [ { "item_id": 9010, "sku": "telescope", "name": { "en": "Telescope", "ru": "Телескоп" }, "type": "virtual_good", "description": { "en": "Allows to see the stars", "ru": "Позволяет увидеть звезды" }, "image_url": "https://picture.bundle-picture.png", "quantity": 1 }, { "item_id": 9012, "sku": "health_potion", "name": { "en": "Healing potion", "ru": "Зелье лечения" }, "type": "virtual_good", "description": { "en": "Heal 10% of your health", "ru": "Лечит 10% здоровья" }, "image_url": "https://picture.bundle-picture.png", "quantity": 2 } ] }, { "step_id": 6, "step_number": 2, "items": [ { "item_id": 9010, "sku": "telescope", "name": { "en": "Telescope", "ru": "Телескоп" }, "type": "virtual_good", "description": { "en": "Allows to see the stars", "ru": "Позволяет увидеть звезды" }, "image_url": "https://picture.bundle-picture.png", "quantity": 5 } ] }, { "step_id": 5, "step_number": 3, "items": [ { "item_id": 9010, "sku": "telescope", "name": { "en": "Telescope", "ru": "Телескоп" }, "type": "virtual_good", "description": { "en": "Allows to see the stars", "ru": "Позволяет увидеть звезды" }, "image_url": "https://picture.bundle-picture.png", "quantity": 2 } ] } ], "is_enabled": true, "type": "calendar_hard" } }, "404-daily-chain-not-found": { "summary": "Daily reward is not found", "description": "未找到每日奖励。", "value": { "statusCode": 404, "errorCode": 6201, "errorMessage": "[0401-6201]: Chain not found", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 4 } } }, "422-admin-daily-chain-error-invalid-chain-step-ids": { "summary": "Daily reward step IDs not found", "description": "Some of step IDs was not found. Please, double check if specified daily reward step IDs actually exist.", "value": { "statusCode": 404, "errorCode": 6206, "errorMessage": "[0401-6206]: Chain step IDs not found", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 1, "chain_step_id_list": [ 404000 ] } } }, "422-admin-daily-chain-error-chain-id-mismatch": { "summary": "Daily reward ID mismatch", "description": "Daily reward ID specified in the body does not match the URL.", "value": { "statusCode": 422, "errorCode": 6205, "errorMessage": "[0401-6205]: Chain ID mismatch. Please, check the chain ID in your request body and URL", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "url_chain_id": 1, "body_chain_id": 2 } } }, "422-admin-daily-chain-error-duplicate-step-ids": { "summary": "Duplicate daily reward step IDs", "description": "Please, ensure that daily reward step IDs are unique in the request body.", "value": { "statusCode": 422, "errorCode": 6207, "errorMessage": "[0401-6207]: Duplicate chain step IDs detected in the request body", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_step_id_list": [ 8, 9, 10 ], "chain_id": 3 } } }, "422-admin-daily-chain-error-activated": { "summary": "Active daily reward cannot be updated", "description": "Active daily reward have to be deactivated before being updated.", "value": { "statusCode": 422, "errorCode": 6209, "errorMessage": "[0401-6209]: Active chain cannot be updated. Please deactivate it first", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 2 } } }, "200-client-daily-chain-list": { "summary": "User's daily reward list example", "value": { "has_more": false, "total_items_count": 3, "items": [ { "id": 101, "name": "Active daily reward", "description": null, "date_start": "2025-04-01T18:16:00+05:00", "date_end": "2025-04-03T18:16:00+05:00", "order": 1, "steps": [ { "step_number": 1, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 1 } ], "status": "claimed", "unlocked_date": 1711978560 }, { "step_number": 2, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 2 } ], "status": "claimable", "unlocked_date": 1712064960 }, { "step_number": 3, "items": [ { "item_id": 9011, "sku": "free_item", "name": "Free item", "type": "virtual_good", "description": "store_item_0_lost_telescope_2_short_description", "image_url": "https://picture.bundle-picture.png", "is_free": true, "quantity": 1 } ], "status": "claim_in_future", "unlocked_date": 1712151360 } ], "type": "calendar_hard" }, { "id": 102, "name": "Active daily reward 2", "description": null, "date_start": "2025-05-01T18:16:00+05:00", "date_end": "2025-05-03T18:16:00+05:00", "order": 1, "steps": [ { "step_number": 1, "items": [ { "item_id": 9011, "sku": "free_item", "name": "Free item", "type": "virtual_good", "description": "store_item_0_lost_telescope_2_short_description", "image_url": "https://picture.bundle-picture.png", "is_free": true, "quantity": 3 } ], "status": "claimable", "unlocked_date": 1714560960 }, { "step_number": 2, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 3 } ], "status": "claim_in_future", "unlocked_date": 1714647360 } ], "type": "calendar_hard" }, { "id": 103, "name": "Active daily reward 3", "description": null, "date_start": "2025-04-01T18:16:00+05:00", "date_end": "2025-04-03T18:16:00+05:00", "order": 1, "steps": [ { "step_number": 1, "items": [ { "item_id": 9011, "sku": "free_item", "name": "Free item", "type": "virtual_good", "description": "store_item_0_lost_telescope_2_short_description", "image_url": "https://picture.bundle-picture.png", "is_free": true, "quantity": 3 } ], "status": "claimable", "unlocked_date": 1711978560 }, { "step_number": 2, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 3 } ], "status": "blocked", "unlocked_date": 1712064960 }, { "step_number": 3, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 3 } ], "status": "blocked", "unlocked_date": 1712151360 } ], "type": "calendar_hard" }, { "id": 104, "name": "Active daily rolling reward", "description": null, "date_start": "2025-04-01T10:00:00+05:00", "date_end": "2025-04-28T10:00:00+05:00", "order": 1, "steps": [ { "step_number": 1, "items": [ { "item_id": 1001, "sku": "item_one", "name": "Item One", "type": "virtual_good", "description": "Item one description", "image_url": "https://picture.bundle-picture.png", "is_free": true, "quantity": 1 } ], "status": "claimed", "unlocked_date": -1 }, { "step_number": 2, "items": [ { "item_id": 1002, "sku": "item_two", "name": "Item Two", "type": "virtual_good", "description": "Item two description", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 1 } ], "status": "claimable", "unlocked_date": 1712064960 }, { "step_number": 3, "items": [ { "item_id": 1003, "sku": "item_three", "name": "Item Three", "type": "virtual_good", "description": "Item three description", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 1 } ], "status": "claim_in_future", "unlocked_date": 1712151360 } ], "type": "rolling_skippable" } ] } }, "200-client-daily-chain": { "summary": "User's daily reward example", "value": { "id": 101, "name": "Active daily reward", "description": "Active daily reward description", "date_start": "2025-04-01T18:16:00+05:00", "date_end": "2025-04-03T18:16:00+05:00", "order": 1, "steps": [ { "step_number": 1, "items": [ { "item_id": 10001, "sku": "bundle_with_items", "name": "Bundle with awesome stuff!", "type": "bundle", "description": "Many stuff", "image_url": "https://picture.bundle-with-many-stuff.png", "bundle_type": "standard", "is_free": false, "content": [ { "item_id": 1, "sku": "d0df11c5-f7c4-4907-9ae1-7dd40cecab05", "name": "virtual_good_one", "type": "virtual_good", "description": "Virtual good one", "image_url": "https://picture.virtual-good-picture.png", "is_free": false, "quantity": 1 }, { "item_id": 2, "sku": "coins", "name": "Gold Coins", "type": "virtual_currency", "description": "Gold Coins", "image_url": "https://picture.gold_coins.png", "is_free": false, "quantity": 100 } ], "quantity": 1 } ], "status": "blocked", "unlocked_date": 1711978560 }, { "step_number": 2, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 1 } ], "status": "claimed", "unlocked_date": 1712064960 }, { "step_number": 3, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 2 } ], "status": "claimable", "unlocked_date": 1712151360 }, { "step_number": 4, "items": [ { "item_id": 9011, "sku": "free_item", "name": "Free item", "type": "virtual_good", "description": "store_item_0_lost_telescope_2_short_description", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 1 } ], "status": "claim_in_future", "unlocked_date": 1712237760 } ], "type": "calendar_hard" } }, "404-daily-chain-step-not-found": { "summary": "Daily reward step not found", "description": "Daily reward step was not found.", "value": { "statusCode": 404, "errorCode": 6304, "errorMessage": "[0401-6304]: Daily Chain Step not found", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "chain_id": 100, "step_number": 1 } } }, "422-daily-chain-claim-error-invalid-step": { "summary": "Can't claim step reward", "description": "Ensure the user has not previously claimed the reward and that the correct step in the daily reward is selected for claiming.\n", "value": { "statusCode": 422, "errorCode": 6405, "errorMessage": "[0401-6405]: This step is not available to be claimed by the user.", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "chain_id": 1, "step_number": 1 } } }, "200-client-offer-chain-list": { "summary": "User's offer chain list example", "value": { "has_more": false, "total_items_count": 3, "items": [ { "id": 101, "name": "Active offer chain", "description": null, "date_start": "2018-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "order": 1, "recurrent_schedule": null, "steps": [ { "step_number": 1, "is_free": false, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 1, "order": 0 } ], "is_claimed": false, "step_price": { "amount": 99.99, "currency": "USD" }, "step_vp_rewards": [ { "item_id": 6039, "sku": "test_value_point_39", "amount": 15, "name": "store_item_0_test_value_point_name", "image_url": "https://popmedia.blob.core.windows.net/popyourself/female/accessory/female_crossnecklace_2_silver-01.png", "is_clan": true } ] }, { "step_number": 2, "is_free": false, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 2, "order": 0 } ], "is_claimed": false, "step_price": { "amount": 199.98, "currency": "USD" }, "step_vp_rewards": [ { "item_id": 6039, "sku": "test_value_point_39", "amount": 30, "name": "store_item_0_test_value_point_name", "image_url": "https://popmedia.blob.core.windows.net/popyourself/female/accessory/female_crossnecklace_2_silver-01.png", "is_clan": true } ] }, { "step_number": 3, "is_free": true, "items": [ { "item_id": 9011, "sku": "free_item", "name": "Free item", "type": "virtual_good", "description": "store_item_0_lost_telescope_2_short_description", "image_url": "https://picture.bundle-picture.png", "is_free": true, "quantity": 1, "order": 0 } ], "is_claimed": false, "step_price": null, "step_vp_rewards": null } ], "next_step_number": 1 }, { "id": 102, "name": "Active offer chain 2", "description": null, "date_start": "2018-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "order": 1, "recurrent_schedule": null, "steps": [ { "step_number": 1, "is_free": true, "items": [ { "item_id": 9011, "sku": "free_item", "name": "Free item", "type": "virtual_good", "description": "store_item_0_lost_telescope_2_short_description", "image_url": "https://picture.bundle-picture.png", "is_free": true, "quantity": 3, "order": 0 } ], "is_claimed": false, "step_price": null, "step_vp_rewards": null }, { "step_number": 2, "is_free": true, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 3, "order": 0 } ], "is_claimed": false, "step_price": null, "step_vp_rewards": [ { "item_id": 6039, "sku": "test_value_point_39", "amount": 45, "name": "store_item_0_test_value_point_name", "image_url": "https://popmedia.blob.core.windows.net/popyourself/female/accessory/female_crossnecklace_2_silver-01.png", "is_clan": true } ] }, { "step_number": 3, "is_free": true, "items": [], "is_claimed": false, "step_price": null, "step_vp_rewards": null } ], "next_step_number": 1 }, { "id": 103, "name": "Active offer chain 3", "description": null, "date_start": "2018-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "order": 1, "recurrent_schedule": null, "steps": [ { "step_number": 1, "is_free": true, "items": [ { "item_id": 9011, "sku": "free_item", "name": "Free item", "type": "virtual_good", "description": "store_item_0_lost_telescope_2_short_description", "image_url": "https://picture.bundle-picture.png", "is_free": true, "quantity": 3, "order": 0 } ], "is_claimed": false, "step_price": null, "step_vp_rewards": null }, { "step_number": 2, "is_free": false, "items": [ { "item_id": 9012, "sku": "health_potion", "name": "Healing potion", "type": "virtual_good", "description": "Heal 10% of your health", "image_url": "https://picture.bundle-picture.png", "is_free": false, "quantity": 3, "order": 0 } ], "is_claimed": false, "step_price": { "amount": 299.97, "currency": "USD" }, "step_vp_rewards": [ { "item_id": 6039, "sku": "test_value_point_39", "amount": 45, "name": "store_item_0_test_value_point_name", "image_url": "https://popmedia.blob.core.windows.net/popyourself/female/accessory/female_crossnecklace_2_silver-01.png", "is_clan": true } ] }, { "step_number": 3, "is_free": true, "items": [], "is_claimed": false, "step_price": null, "step_vp_rewards": null } ], "next_step_number": 1 } ] } }, "200-client-offer-chain": { "summary": "User's offer chain example", "value": { "id": 4, "name": "Offer chain with bundles", "description": null, "date_start": "2010-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "order": 1, "recurrent_schedule": null, "steps": [ { "step_number": 1, "is_free": false, "items": [ { "item_id": 7008, "sku": "bundle_with_many_items", "name": "Bundle with many awesome stuff!", "type": "bundle", "description": "Many stuff", "image_url": "https://picture.bundle-with-many-stuff.png", "bundle_type": "standard", "is_free": false, "content": [ { "item_id": 1, "sku": "d0df11c5-f7c4-4907-9ae1-7dd40cecab05", "name": "Virtual Good Bundle", "type": "virtual_good", "description": "virtual_good_short_description_d0df11c5-f7c4-4907-9ae1-7dd40cecab05", "image_url": "https://popmedia.blob.core.windows.net/popyourself/female/accessory/female_crossnecklace_2_silver-01.png", "is_free": false, "quantity": 1 }, { "item_id": 7009, "sku": "vg-in-bundle-big-rocket", "name": "Big Rocket", "type": "virtual_good", "description": "Big Rocket - short description", "image_url": "https://picture.bigrocket.png", "is_free": false, "quantity": 1 }, { "item_id": 7010, "sku": "vc-in-bundle-gold-coins", "name": "Gold Coins", "type": "virtual_currency", "description": "Gold Coins - short description", "image_url": "https://picture.gold_coins.png", "is_free": true, "quantity": 100 }, { "item_id": 7011, "sku": "digital-content-drm-in-bundle-awesome-game", "name": "Some Game", "type": "virtual_good", "description": "Some Game - short description", "image_url": "https://picture.some_game.png", "is_free": true, "quantity": 1 }, { "item_id": 7012, "sku": "bundle-in-bundle-another-bundle", "name": "Some Bundle in Bundle", "type": "bundle", "description": "Bundle - short description", "image_url": "https://picture.bundle-picture.png", "bundle_type": "standard", "is_free": true, "content": [ { "item_id": 7010, "sku": "vc-in-bundle-gold-coins", "name": "Gold Coins", "type": "virtual_currency", "description": "Gold Coins - short description", "image_url": "https://picture.gold_coins.png", "is_free": true, "quantity": 1 } ], "quantity": 1 }, { "item_id": 7013, "sku": "lootbox-in-bundle-awesome-game", "name": "Some Lootbox", "type": "lootbox", "description": "Lootbox in bundle - short description", "image_url": "https://picture.lootbox-picture.png", "is_free": true, "quantity": 1 } ], "quantity": 5, "order": 0 } ], "is_claimed": false, "step_price": { "amount": 499.95, "currency": "USD" }, "step_vp_rewards": null }, { "step_number": 2, "is_free": true, "items": [ { "item_id": 7007, "sku": "bundle-empty", "name": "Empty bundle", "type": "bundle", "description": "No", "image_url": "https://picture.bundle-no-items.png", "bundle_type": "standard", "is_free": true, "content": [], "quantity": 10, "order": 0 } ], "is_claimed": false, "step_price": null, "step_vp_rewards": null } ], "next_step_number": 1 } }, "404-offer-chain-not-found": { "summary": "Chain not found", "description": "Offer chain step was not found.", "value": { "statusCode": 404, "errorCode": 6201, "errorMessage": "[0401-6201]: Chain not found", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 4 } } }, "404-offer-chain-step-not-found": { "summary": "Chain step not found", "description": "Offer chain step was not found.", "value": { "statusCode": 404, "errorCode": 6304, "errorMessage": "[0401-6304]: Offer Chain Step not found", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "chain_id": 100, "step_number": 1 } } }, "422-offer-chain-claim-error-invalid-step": { "summary": "Cannot claim step reward", "description": "The user must claim all previous steps, and the request must use a valid call – Create order for paid offer chain step, Claim free offer chain step for free ones.\n\nThis error is returned if one or more of the following conditions are not met:
  • The offer chain exists, is enabled, and not deleted.
  • The target step exists, is enabled, and marked as free.
  • The step has not already been claimed by the user. In case of a recurring chain, this check is based on the user progress of the current iteration.
  • All previous steps in the chain (by step number) have been claimed or purchased. In case of a recurring chain, this check also considers the user progress of the current iteration.
", "value": { "statusCode": 422, "errorCode": 6306, "errorMessage": "[0401-6306]: This step is not valid to claim by user.", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "chain_id": 1, "step_number": 1 } } }, "200-admin-offer-chain-list": { "summary": "Offer chain list example", "value": { "has_more": false, "items": [ { "id": 1, "name": { "en": "New personalized default offer chain", "ru": "Новая персонализированная цепочка предложений по умолчанию", "de": "Neue personalisierte Standard-Angebotskette", "fr": "Nouvelle chaîne d'offres personnalisée par défaut", "it": "Nuova catena di offerte personalizzata predefinita" }, "description": { "en": "Default personalized offer chain for users that do not meet the conditions of other personalized chains", "ru": "Персонализированная цепочка по умолчанию для пользователей, не подходящих под условия других персонализированных цепочек", "de": "Standard-personalisierte Angebotskette für Benutzer, die die Bedingungen anderer personalisierter Ketten nicht erfüllen", "fr": "Chaîne d'offres personnalisée par défaut pour les utilisateurs qui ne répondent pas aux conditions des autres chaînes personnalisées", "it": "Catena di offerte personalizzata predefinita per gli utenti che non soddisfano le condizioni di altre catene personalizzate" }, "order": 1, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "is_enabled": true, "recurrent_schedule": null, "is_always_visible": false }, { "id": 2, "name": { "en": "New personalized offer chain", "ru": "Новая персонализированная цепочка предложений", "de": "Neue personalisierte Angebotskette", "fr": "Nouvelle chaîne d'offres personnalisée", "it": "Nuova catena di offerte personalizzata" }, "description": { "en": "Personalized offer chain with user attribute conditions - for level 10 and above elves who reached level 10 no later than 2026-01-01 00:00:00, inclusive", "ru": "Персонализированная цепочка предложений с условиями по атрибутам пользователя - для эльфов уровня 10 и выше, достигших 10 уровня не позднее 2026-01-01 00:00:00 включительно", "de": "Personalisierte Angebotskette mit Benutzerattributbedingungen - für Elfen der Stufe 10 und höher, die Stufe 10 spätestens am 2026-01-01 00:00:00 erreicht haben, einschließlich", "fr": "Chaîne d'offres personnalisée avec des conditions d'attribut utilisateur - pour les elfes de niveau 10 et plus qui ont atteint le niveau 10 au plus tard le 2026-01-01 00:00:00, inclus", "it": "Catena di offerte personalizzata con condizioni di attributo utente - per elfi di livello 10 e superiore che hanno raggiunto il livello 10 non più tardi del 2026-01-01 00:00:00, inclusi" }, "order": 2, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "is_enabled": true, "recurrent_schedule": null, "is_always_visible": false, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "elf", "type": "string", "can_be_missing": false }, { "attribute": "level", "operator": "ge", "value": "10", "type": "number", "can_be_missing": false }, { "attribute": "10_level_up_date", "operator": "le", "value": "2026-01-01T00:00:00", "type": "date", "can_be_missing": false } ] }, { "id": 4, "name": { "en": "Weekly offer chain", "ru": "Еженедельная цепочка предложений", "de": "Wöchentliche Angebotskette", "fr": "Chaîne d'offres hebdomadaire", "it": "Catena di offerte settimanale" }, "description": { "en": "Offer chain that resets weekly on Wednesdays at 07:00 GMT+3", "ru": "Цепочка предложений, которая сбрасывается еженедельно по средам в 07:00 GMT+3", "de": "Angebotskette, die sich wöchentlich mittwochs um 07:00 Uhr GMT+3 zurücksetzt", "fr": "Chaîne d'offres qui se réinitialise chaque semaine le mercredi à 07h00 GMT+3", "it": "Catena di offerte che si resetta settimanalmente il mercoledì alle 07:00 GMT+3" }, "order": 3, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "is_enabled": false, "recurrent_schedule": { "interval_type": "weekly", "day_of_week": 3, "time": "07:00:00+03:00", "displayable_reset_start_date": "2018-12-05T07:00:00+03:00", "displayable_reset_next_date": "2018-12-05T07:00:00+03:00", "reset_next_date": 1543982400 }, "is_always_visible": true }, { "id": 5, "name": { "en": "Monthly offer chain", "ru": "Ежемесячная цепочка предложений", "de": "Monatliche Angebotskette", "fr": "Chaîne d'offres mensuelle", "it": "Catena di offerte mensile" }, "description": { "en": "Offer chain that resets monthly on the 28th at 15:00 GMT+8", "ru": "Цепочка предложений, которая сбрасывается ежемесячно 28-го числа в 15:00 GMT+8", "de": "Angebotskette, die sich monatlich am 28. um 15:00 Uhr GMT+8 zurücksetzt", "fr": "Chaîne d'offres qui se réinitialise mensuellement le 28 à 15h00 GMT+8", "it": "Catena di offerte che si resetta mensilmente il 28 alle 15:00 GMT+8" }, "order": 4, "date_start": "2025-04-15T00:00:00+08:00", "date_end": "2025-08-28T15:00:00+08:00", "is_enabled": true, "recurrent_schedule": { "interval_type": "monthly", "day_of_month": 28, "time": "15:00:00+08:00", "displayable_reset_start_date": "2025-05-28T15:00:00+08:00", "displayable_reset_next_date": "2025-05-28T15:00:00+08:00", "reset_next_date": 1748415600 }, "is_always_visible": true } ] } }, "422-admin-offer-chain-error-too-many-steps": { "summary": "Too many steps", "description": "The number of offer chain steps exceeds the allowed limit of 30. Try specifying fewer steps.", "value": { "statusCode": 422, "errorCode": 6203, "errorMessage": "[0401-6203]: Chain step count exceeds the allowed limit", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "step_count": 31, "max_steps": 30 } } }, "422-admin-offer-chain-error-incorrect-steps-order": { "summary": "Invalid steps order", "description": "The sequence of offer chain step numbers is incorrect. Step numbers must be sequential, without gaps or duplicates.", "value": { "statusCode": 422, "errorCode": 6210, "errorMessage": "[0401-6210]: Chain step numbers are invalid", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "incorrect_step_numbers": { "duplicates": [ 2, 7 ], "out_of_range": [ 7, 8 ], "missing": [ 3, 4, 5, 6 ] } } } }, "422-admin-offer-chain-error-item-limit-exceeded": { "summary": "Item limit exceeded", "description": "The number of items in one or more offer chain steps exceeds the allowed limit. Currently, only one item per step is allowed.", "value": { "statusCode": 422, "errorCode": 6208, "errorMessage": "[0401-6208]: Chain step item count exceeds the allowed limit for some steps", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "max_items": 1, "steps_exceeded_limits": [ { "step_number": 1, "items_count": 2 }, { "step_number": 4, "items_count": 3 } ] } } }, "422-admin-offer-chain-error-incorrect-items": { "summary": "Invalid step items", "description": "Specified items are either unavailable, or not found. Only enabled items of the following types are supported: virtual items, bundles, and virtual currency packages.", "value": { "statusCode": 422, "errorCode": 6211, "errorMessage": "[0401-6211]: Chain steps items are not allowed or not found", "transactionId": "x-x-xX-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "invalid_items": { "not_found": [ "vg_deleted_item_1", "vg_deleted_item_2", "not_existing_sku_404_1", "not_existing_sku_404_2" ], "disabled": [ "vg_disabled_item_1", "vg_disabled_item_2", "vc_disabled_1" ], "invalid_item_type": { "allowed_item_type_list": [ "virtual_good", "bundle" ], "sku_map": { "vc_enabled_shown_in_store_1": "virtual_currency", "vc_disabled_1": "virtual_currency", "unit_enabled_shown_in_store_1": "unit", "gk_steam_enabled_shown_in_store_1": "game_key" } } } } } }, "422-admin-offer-chain-error-invalid-dates": { "summary": "Invalid date format", "description": "The date format must be valid. Use ISO 8601 format.", "value": { "statusCode": 422, "errorCode": 6204, "errorMessage": "[0401-6204]: Period of a chain is invalid. Please, check the dates in your request", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 1, "invalid_format_dates": { "date_start": "2023-04-15 17:16:00Z", "date_end": "2025-04-25 19:16:00Z" } } } }, "422-admin-offer-chain-error-incorrect-period": { "summary": "Invalid chain period", "description": "The start date must be earlier than the end date.", "value": { "statusCode": 422, "errorCode": 6204, "errorMessage": "[0401-6204]: Period of a chain is invalid. Please, check the dates in your request", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 1, "invalid_periods": [ { "start": "2025-04-25T18:16:00+05:00", "end": "2023-04-15T18:16:00+05:00" } ] } } }, "200-admin-offer-chain": { "summary": "Offer chain example", "value": { "id": 3, "name": { "en": "Offer chain", "ru": "Цепочка", "de": "Angebotskette", "fr": "Chaîne d'offres", "it": "Catena di offerte" }, "description": { "en": "Personalized offer chain with user attribute conditions - for level 10 and above elves who reached level 10 no later than 2026-01-01 00:00:00, inclusive", "ru": "Персонализированная цепочка предложений - для эльфов 10 уровня и выше, достигших 10 уровня не позднее 2026-01-01 00:00:00 включительно", "de": "Personalisierte Angebotskette mit Benutzerattributbedingungen - für Elfen der Stufe 10 und höher, die Stufe 10 spätestens am 2026-01-01 00:00:00 erreicht haben, einschließlich", "fr": "Chaîne d'offres personnalisée avec des conditions d'attribut utilisateur - pour les elfes de niveau 10 et plus qui ont atteint le niveau 10 au plus tard le 2026-01-01 00:00:00, inclus", "it": "Catena di offerte personalizzata con condizioni di attributo utente - per elfi di livello 10 e superiore che hanno raggiunto il livello 10 non più tardi del 2026-01-01 00:00:00, inclusi" }, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "order": 1, "recurrent_schedule": null, "steps": [ { "step_id": 7, "step_number": 1, "is_free": false, "items": [ { "item_id": 9010, "sku": "telescope", "name": { "en": "Telescope", "ru": "Телескоп", "de": "Teleskop", "fr": "Télescope", "it": "Telescopio" }, "type": "virtual_good", "description": { "en": "Allows to see the stars", "ru": "Позволяет увидеть звезды", "de": "Ermöglicht das Betrachten der Sterne", "fr": "Permet de voir les étoiles", "it": "Permette di vedere le stelle" }, "image_url": "https://cdn.picture.vg.sku-telescope.png", "quantity": 1, "order": 1 }, { "item_id": 9012, "sku": "health_potion", "name": { "en": "Healing potion", "ru": "Зелье лечения", "de": "Heiltrank", "fr": "Potion de soin", "it": "Pozione curativa" }, "type": "virtual_good", "description": { "en": "Heal 10% of your health", "ru": "Лечит 10% здоровья", "de": "Heilt 10% deiner Gesundheit", "fr": "Soigne 10% de votre santé", "it": "Cura il 10% della tua salute" }, "image_url": "https://cdn.picture/vg-sku-health_potion.png", "quantity": 2, "order": 0 } ] }, { "step_id": 6, "step_number": 2, "is_free": false, "items": [ { "item_id": 9010, "sku": "telescope", "name": { "en": "Telescope", "ru": "Телескоп", "de": "Teleskop", "fr": "Télescope", "it": "Telescopio" }, "type": "virtual_good", "description": { "en": "Allows to see the stars", "ru": "Позволяет увидеть звезды", "de": "Ermöglicht das Betrachten der Sterne", "fr": "Permet de voir les étoiles", "it": "Permette di vedere le stelle" }, "image_url": "https://cdn.picture/vg-sku-telescope.png", "quantity": 5, "order": 0 } ] }, { "step_id": 5, "step_number": 3, "is_free": true, "items": [ { "item_id": 9010, "sku": "telescope", "name": { "en": "Telescope", "ru": "Телескоп", "de": "Teleskop", "fr": "Télescope", "it": "Telescopio" }, "type": "virtual_good", "description": { "en": "Allows to see the stars", "ru": "Позволяет увидеть звезды", "de": "Ermöglicht das Betrachten der Sterne", "fr": "Permet de voir les étoiles", "it": "Permette di vedere le stelle" }, "image_url": "https://cdn.picture/vg-sku-telescope.png", "quantity": 2, "order": 0 } ] } ], "is_enabled": true, "is_always_visible": false, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "elf", "type": "string", "can_be_missing": false }, { "attribute": "level", "operator": "ge", "value": "10", "type": "number", "can_be_missing": false }, { "attribute": "10_level_up_date", "operator": "le", "value": "2026-01-01T00:00:00", "type": "date", "can_be_missing": false } ] } }, "422-admin-offer-chain-error-invalid-chain-step-ids": { "summary": "Chain step IDs not found", "description": "Some of the step IDs were not found. Double-check that the specified chain step IDs exist. To do this, use the Get offer chain call.", "value": { "statusCode": 404, "errorCode": 6206, "errorMessage": "[0401-6206]: Chain step IDs not found", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 1, "chain_step_id_list": [ 404000 ] } } }, "422-admin-offer-chain-error-chain-id-mismatch": { "summary": "Chain ID mismatch", "description": "Offer chain ID in the request body does not match the ID in the URL.", "value": { "statusCode": 422, "errorCode": 6205, "errorMessage": "[0401-6205]: Chain ID mismatch. Please, check the chain ID in your request body and URL", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "url_chain_id": 1, "body_chain_id": 2 } } }, "422-admin-offer-chain-error-duplicate-step-ids": { "summary": "Duplicate chain step IDs", "description": "Chain step IDs must be unique in the request body.", "value": { "statusCode": 422, "errorCode": 6207, "errorMessage": "[0401-6207]: Duplicate chain step IDs detected in the request body", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_step_id_list": [ 8, 9, 10 ], "chain_id": 3 } } }, "422-admin-offer-chain-error-activated": { "summary": "Active offer chain cannot be updated", "description": "Active offer chain has to be deactivated before being updated. To do this, use the Toggle offer chain call.", "value": { "statusCode": 422, "errorCode": 6209, "errorMessage": "[0401-6209]: Active chain cannot be updated. Please deactivate it first", "transactionId": "x-x-x-x-transactionId-mock-x-x-x", "errorMessageExtended": { "project_id": 0, "chain_id": 2 } } } }, "responses": { "Promotions_200-get-promotions": { "description": "已成功获取促销活动列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "promotions": { "type": "array", "items": { "$ref": "#/components/schemas/Promotions_200-get-promotion-model" } }, "total_promotions_count": { "$ref": "#/components/schemas/total_promotions_count" }, "active_promotions_count": { "$ref": "#/components/schemas/active_promotions_count" }, "inactive_promotions_count": { "$ref": "#/components/schemas/inactive_promotions_count" } } }, "examples": { "response": { "$ref": "#/components/examples/Promotions_200-admin-promotions" } } } } }, "Promotions_401-invalid-basic-auth": { "description": "基本身份认证未通过或不正确。请确保您使用了基本身份认证或正确的凭据。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 401 }, "errorCode": { "type": "integer", "example": 1020 }, "errorMessage": { "type": "string", "example": "[0401-1020]: Error in Authentication method occurred" } } }, "examples": { "response": { "value": { "statusCode": 401, "errorCode": 1020, "errorMessage": "[0401-1020]: Error in Authentication method occurred" } } } } } }, "Promotions_422-activate-deactivate-promotion": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-9505]: Error was occurred while promotion was being updated" }, "transactionId": { "type": "string", "example": "da145238620011eb8e24fe6913ff226a" } } }, "examples": { "Error was occurred": { "$ref": "#/components/examples/422-activate-deactivate-promotion" } } } } }, "200-admin-get-redeemable-by-code": { "description": "成功收到促销活动。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin-promotions_200-get-redeemable-coupon-promotion-model" }, "examples": { "Promo Code Response": { "value": { "promotion_periods": [ { "date_from": "2023-05-01T01:00:00+05:00", "date_until": "2023-05-31T23:59:59+05:00" }, { "date_from": "2023-06-01T01:00:00+05:00", "date_until": "2023-06-30T23:59:59+05:00" } ], "bonus": [], "is_enabled": true, "external_id": "falls2023", "name": { "ru": "Скидка по промокоду на Epic Fall Hammer", "en": "Promo Code discount for Epic Fall Hammer" }, "redeem_total_limit": 2, "redeem_user_limit": 3, "redeem_code_limit": null, "total_limit_state": { "available": 1, "reserved": 1, "used": 0 }, "discount": { "percent": null }, "discounted_items": [ { "sku": "epic_fall_hammer_1", "discount": { "percent": "20.00" } } ] } }, "Coupon Response": { "value": { "promotion_periods": [ { "date_from": "2023-04-15T01:00:00+05:00", "date_until": "2023-04-30T23:59:59+05:00" }, { "date_from": "2023-05-15T01:00:00+05:00", "date_until": "2023-05-30T23:59:59+05:00" } ], "bonus": [ { "sku": "epic_fall_hammer_1", "quantity": 3 } ], "is_enabled": true, "external_id": "coupon_fall_hammer_2", "name": { "en": "This is a Coupon code for Epic Fall Hammer", "ru": "Eto kod kupona на Epic Fall Hammer" }, "redeem_total_limit": 99, "redeem_user_limit": 1, "redeem_code_limit": null } } } } } }, "401-invalid-basic-auth": { "description": "基本身份认证未通过或不正确。请确保您使用了基本身份认证或正确的凭据。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 401 }, "errorCode": { "type": "integer", "example": 1020 }, "errorMessage": { "type": "string", "example": "[0401-1020]: Error in Authentication method occurred" } } }, "examples": { "response": { "value": { "statusCode": 401, "errorCode": 1020, "errorMessage": "[0401-1020]: Error in Authentication method occurred" } } } } } }, "404-code-not-found": { "description": "未找到可核销代码。请确保提供的代码值正确无误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 9811 }, "errorMessage": { "type": "string", "example": "[0401-9811]: Code not found." } } }, "examples": { "response": { "value": { "statusCode": 404, "errorCode": 9811, "errorMessage": "[0401-9811]: Code not found." } } } } } }, "405-method-not-found": { "description": "可核销代码格式不正确。该代码只能包含字母和数字。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 405 }, "errorCode": { "type": "integer", "example": 0 }, "errorMessage": { "type": "string", "example": "Method is not allowed. Method must be one of: OPTIONS" } } }, "examples": { "response": { "value": { "statusCode": 405, "errorCode": 0, "errorMessage": "Method is not allowed. Method must be one of: OPTIONS" } } } } } }, "Promotions_200-coupon-redeemed": { "description": "优惠券已成功核销。", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string" }, "name": { "type": "string" } } } }, "name": { "type": [ "string", "null" ] }, "price": { "type": [ "object", "null" ], "description": "商品价格。", "properties": { "amount": { "type": "string", "example": "2.9900", "description": "商品折后价格。" }, "amount_without_discount": { "type": "string", "example": "2.9900", "description": "商品价格。" }, "currency": { "type": "string", "example": "USD", "description": "商品价格币种。符合[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母代码。" } } }, "type": { "type": "string" }, "virtual_item_type": { "type": "string", "example": "non-consumable", "description": "虚拟物品的类型。\n\n可能值：\n- `consumable` — 使用后会从物品库中消失的商品（例如弹药）。\n- `non_consumable` — 可无限期保留在物品库中的商品。\n- `non_renewing_subscription` — 时效性商品，可表示在限定时间内对服务或内容的访问权限。\"", "enum": [ "consumable", "non_consumable", "non_renewing_subscription" ] }, "virtual_prices": { "type": "array" }, "description": { "type": "string" }, "image_url": { "type": "string" }, "quantity": { "type": "integer" }, "is_free": { "type": "boolean" }, "attributes": { "type": "array" } } }, "example": [ { "attributes": [], "description": "Take it, take it all! All of Xsolla's riches in one Mega Booster.", "groups": [ { "external_id": "powerups", "name": "Power Ups" } ], "image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png", "is_free": false, "name": "Xsolla Booster Mega", "price": { "amount": "50.0000000000000000", "amount_without_discount": "100.0000000000000000", "currency": "USD" }, "quantity": 1, "sku": "com.xsolla.booster_mega_1", "type": "virtual_good", "virtual_item_type": "consumable", "virtual_prices": [] } ] } } }, "examples": { "response": { "value": { "items": [ { "attributes": [], "description": "Take it, take it all! All of Xsolla's riches in one Mega Booster.", "groups": [ { "external_id": "powerups", "name": "Power Ups" } ], "image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png", "is_free": true, "name": "Xsolla Booster Mega", "price": null, "quantity": 1, "sku": "com.xsolla.booster_mega_1", "type": "virtual_good", "virtual_item_type": "consumable", "virtual_prices": [] } ] } } } } } }, "Promotions_401-invalid-client-auth": { "description": "认证未通过或错误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 401 }, "errorCode": { "type": "integer", "example": 1501 }, "errorMessage": { "type": "string", "example": "[0401-1501]: Authorization failed: Provide authorization" } } }, "examples": { "response": { "value": { "statusCode": 401, "errorCode": 1501, "errorMessage": "[0401-1501]: Authorization failed: Provide authorization" } } } } } }, "Promotions_403-auth-header": { "description": "未发送Authorization请求头。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 403 }, "errorCode": { "type": "integer", "example": 0 }, "errorMessage": { "type": "string", "example": "未发送Authorization请求头。" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } }, "examples": { "response": { "value": { "statusCode": 403, "errorCode": 0, "errorMessage": "Authorization header not sent" } } } } } }, "Promotions_404-coupon": { "description": "输入有效的优惠券码。", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 4001 }, "errorMessage": { "type": "string", "example": "[0401-9807]: Enter valid coupon code." } }, "type": "object" } } } }, "Promotions_422-redeem-coupon": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-1102]: Unprocessable Entity. The property `coupon_code` is required" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } }, "examples": { "response": { "value": { "statusCode": 422, "errorCode": 1102, "errorMessage": "[0401-1102]: Unprocessable Entity. The property `coupon_code` is required" } } } } } }, "Promotions_200-coupon-rewards": { "description": "已成功获取优惠券奖励列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "bonus": { "type": "array", "items": { "$ref": "#/components/schemas/Promotions_200-coupon-bonus-reward" } }, "is_selectable": { "type": "boolean", "description": "如果为`true`，则用户应在核销优惠券前选择赠品。" }, "discount": { "$ref": "#/components/schemas/Promotions_200-coupon-discount-reward" } } }, "examples": { "response": { "$ref": "#/components/examples/Promotions_200-get-coupon-rewards" } } } } }, "Promotions_422-rewards": { "description": "请求无效。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Promotions_422_limit_error" }, { "$ref": "#/components/schemas/Promotions_422_reglock_error" } ] } } } }, "Promotions_200-get-coupons": { "description": "优惠券列表已成功收到。", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/admin-promotions_200-get-coupon-promotion-model" } }, "total_promotions_count": { "$ref": "#/components/schemas/total_promotions_count" }, "active_promotions_count": { "$ref": "#/components/schemas/active_promotions_count" }, "inactive_promotions_count": { "$ref": "#/components/schemas/inactive_promotions_count" } } }, "examples": { "response": { "$ref": "#/components/examples/Promotions_200-admin-coupons" } } } } }, "Promotions_422-invalid-coupon": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-1102]: Unprocessable Entity. The property `external_id` is required" } } }, "examples": { "response": { "value": { "statusCode": 422, "errorCode": 1102, "errorMessage": "[0401-1102]: Unprocessable Entity. The property `external_id` is required" } } } } } }, "Promotions_404-admin-coupon": { "description": "未找到优惠券。请确保`external_id`正确无误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 4001 }, "errorMessage": { "type": "string", "example": "[0401-9802]: Coupon not found" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } } } } }, "Promotions_422-admin-promotion-error": { "description": "从促销服务接收促销活动时出错。", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 9502 }, "errorMessage": { "type": "string", "example": "[0401-9502]: Error occurred while receiving the promotion from the promotion service" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } }, "type": "object" } } } }, "Promotions_200-coupon-code-list": { "description": "已成功接收优惠券码列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Promotions_coupon_code" } } } }, "total_count": { "type": "number", "description": "优惠券码总数。" } } }, "examples": { "response": { "$ref": "#/components/examples/Promotions_200-coupon-code-list" } } } } }, "Promotions_201-coupon-promocode-code-created": { "description": "代码创建成功。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Promotions_coupon_code" } } }, "examples": { "response": { "value": { "code": "WINTER2021" } } } } } }, "Promotions_422-coupon-promocode-same-code-exists": { "description": "无效的请求。代码已经存在。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 9803 }, "errorMessage": { "type": "string", "example": "[0401-9803]: The code already exists." }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } }, "examples": { "response": { "value": { "statusCode": 422, "errorCode": 9803, "errorMessage": "[0401-9803]: The code already exists.", "transactionId": "x-x-x-x-transactionId-mock-x-x-x" } } } } } }, "Promotions_404-admin-promocode": { "description": "未找到兑换码。请确保`external_id`正确无误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 4001 }, "errorMessage": { "type": "string", "example": "[0401-9802]: Promocode not found" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } } } } }, "Promotions_200-promo-code-redeemed": { "description": "兑换码已成功核销。", "content": { "application/json": { "schema": { "type": "object", "properties": { "cart_id": { "type": "string", "example": "cart_id", "description": "购物车ID。" }, "price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "example": "50.0000000000000000" }, "amount_without_discount": { "type": "string", "example": "100.0000000000000000" }, "currency": { "type": "string", "example": "USD" } }, "example": { "amount": "6150.0000000000000000", "amount_without_discount": "6150.0000000000000000", "currency": "USD" }, "description": "购物车价格。" }, "is_free": { "$ref": "#/components/schemas/value-is_free" }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string" }, "name": { "type": "string" } } } }, "name": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "description": { "type": "string" }, "image_url": { "type": "string" }, "quantity": { "type": "integer" }, "is_free": { "$ref": "#/components/schemas/value-is_free" }, "promotions": { "$ref": "#/components/schemas/Catalog_item_promotions" }, "can_be_bought": { "$ref": "#/components/schemas/Can_be_bought" }, "vp_rewards": { "$ref": "#/components/schemas/client-item-value-point-reward" }, "limits": { "$ref": "#/components/schemas/Catalog_item_limits" }, "periods": { "$ref": "#/components/schemas/item-periods" } } }, "example": [ { "attributes": [], "description": "Take it, take it all! All of Xsolla's riches in one Mega Booster.", "groups": [ { "external_id": "powerups", "name": "Power Ups" } ], "image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png", "is_free": false, "name": "Xsolla Booster Mega", "price": { "amount": "50.0000000000000000", "amount_without_discount": "100.0000000000000000", "currency": "USD" }, "quantity": 123, "sku": "com.xsolla.booster_mega_1", "type": "virtual_good", "virtual_item_type": "consumable", "virtual_prices": [], "promotions": [ { "name": "Bonus promotion", "date_start": "2020-04-15T16:16:00+03:00", "date_end": "2026-04-15T16:16:00+03:00", "discount": { "percent": "50.00" }, "bonus": [ { "quantity": 1, "name": "Xsolla Minigun", "image_url": "https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png", "sku": "com.xsolla.minigun_1", "type": "virtual_good" } ] } ], "can_be_bought": true, "vp_rewards": [ { "item_id": 175232, "sku": "com.xsolla.value_point_1", "amount": 130, "name": "Value point", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "is_clan": false }, { "item_id": 186321, "sku": "com.xsolla.clan_value_point_1", "amount": 50, "name": "Clan Reward VP 1", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "is_clan": true } ], "limits": { "per_user": { "available": 3, "recurrent_schedule": { "interval_type": "weekly", "reset_next_date": 1746057600 }, "total": 5 } }, "periods": [ { "date_from": "2020-08-11T10:00:00+03:00", "date_until": "2020-08-11T20:00:00+03:00" } ] } ] }, "rewards": { "$ref": "#/components/schemas/Promo_code_rewards" } } }, "examples": { "response": { "value": { "cart_id": "cart_id", "is_free": false, "items": [ { "attributes": [], "description": "Take it, take it all! All of Xsolla's riches in one Mega Booster.", "groups": [ { "external_id": "powerups", "name": "Power Ups" } ], "image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png", "is_free": false, "name": "Xsolla Booster Mega", "price": { "amount": "50.0000000000000000", "amount_without_discount": "100.0000000000000000", "currency": "USD" }, "quantity": 123, "sku": "com.xsolla.booster_mega_1", "type": "virtual_good", "virtual_item_type": "consumable", "virtual_prices": [], "promotions": [ { "name": "Bonus promotion", "date_start": "2020-04-15T16:16:00+03:00", "date_end": "2026-04-15T16:16:00+03:00", "discount": { "percent": "50.00" }, "bonus": [ { "quantity": 1, "name": "Xsolla Minigun", "image_url": "https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png", "sku": "com.xsolla.minigun_1", "type": "virtual_good" } ] } ], "can_be_bought": true, "vp_rewards": [ { "item_id": 175232, "sku": "com.xsolla.value_point_1", "amount": 130, "name": "Value point", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "is_clan": false }, { "item_id": 186321, "sku": "com.xsolla.clan_value_point_1", "amount": 50, "name": "Clan Reward VP 1", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "is_clan": true } ], "limits": { "per_user": { "available": 3, "recurrent_schedule": { "interval_type": "weekly", "reset_next_date": 1746057600 }, "total": 5 } }, "periods": [ { "date_from": "2020-08-11T10:00:00+03:00", "date_until": "2020-08-11T20:00:00+03:00" } ] }, { "attributes": [], "description": "Honshu Boshin Wakizashi - Modern Tactical Samurai / Ninja Sword - Hand Forged 1060 Carbon Steel - Full Tang, Fully Functional, Battle Ready - Black TPR, Steel Guard and Pommel.", "groups": [], "image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png", "is_free": true, "name": "Sword Xsolla Skin", "price": [], "quantity": 1, "sku": "com.xsolla.swords_1", "type": "virtual_good", "virtual_item_type": "non_consumable", "virtual_prices": [], "promotions": [ { "name": "Bonus promotion", "date_start": "2020-04-15T16:16:00+03:00", "date_end": "2026-04-15T16:16:00+03:00", "discount": { "percent": "50.00" }, "bonus": [ { "quantity": 1, "name": "Xsolla Minigun", "image_url": "https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png", "sku": "com.xsolla.minigun_1", "type": "virtual_good" } ] } ], "can_be_bought": true, "vp_rewards": [ { "item_id": 175232, "sku": "com.xsolla.value_point_1", "amount": 130, "name": "Value point", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg" }, { "item_id": 186321, "sku": "com.xsolla.clan_value_point_1", "amount": 50, "name": "Clan Reward VP 1", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "is_clan": true } ], "limits": { "per_user": { "available": 3, "recurrent_schedule": { "interval_type": "weekly", "reset_next_date": 1746057600 }, "total": 5 } }, "periods": [ { "date_from": "2020-08-11T10:00:00+03:00", "date_until": "2020-08-11T20:00:00+03:00" } ] } ], "price": { "amount": "6150.0000000000000000", "amount_without_discount": "12300.0000000000000000", "currency": "USD" }, "rewards": { "bonus": [ { "item": { "name": "Sword Xsolla Skin", "sku": "com.xsolla.swords_1", "type": "virtual_good", "virtual_item_type": "non_consumable", "description": "Honshu Boshin Wakizashi - Modern Tactical Samurai / Ninja Sword - Hand Forged 1060 Carbon Steel - Full Tang, Fully Functional, Battle Ready - Black TPR, Steel Guard and Pommel.", "image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png" }, "quantity": 1 } ], "discount": { "percent": null }, "discounted_items": [ { "sku": "com.xsolla.booster_mega_1", "discount": { "percent": "50.00" } } ], "is_selectable": false } } } } } } }, "Promotions_404-promo-code": { "description": "请输入有效的兑换码。", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 4001 }, "errorMessage": { "type": "string", "example": "[0401-9807]: Enter valid promo code." } }, "type": "object" } } } }, "Promotions_200-promo-code-canceled": { "description": "兑换码已成功取消。", "content": { "application/json": { "schema": { "type": "object", "properties": { "cart_id": { "type": "string", "example": "cart_id", "description": "购物车ID。" }, "price": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string", "default": "50.0000000000000000" }, "amount_without_discount": { "type": "string", "default": "100.0000000000000000" }, "currency": { "type": "string", "default": "USD" } }, "example": { "amount": "6150.0000000000000000", "amount_without_discount": "6150.0000000000000000", "currency": "USD" }, "description": "购物车价格。" }, "is_free": { "$ref": "#/components/schemas/value-is_free" }, "items": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string" }, "name": { "type": "string" } } } }, "name": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "virtual_item_type": { "type": "string", "example": "non-consumable", "description": "虚拟物品的类型。\n\n可能值：\n- `consumable` — 使用后会从物品库中消失的商品（例如弹药）。\n- `non_consumable` — 可无限期保留在物品库中的商品。\n- `non_renewing_subscription` — 时效性商品，可表示在限定时间内对服务或内容的访问权限。\"", "enum": [ "consumable", "non_consumable", "non_renewing_subscription" ] }, "virtual_prices": { "type": "array" }, "description": { "type": "string" }, "attributes": { "$ref": "#/components/schemas/client-attributes" }, "image_url": { "type": "string" }, "quantity": { "type": "integer" }, "is_free": { "$ref": "#/components/schemas/value-is_free" }, "price": { "type": [ "object", "null" ], "description": "商品价格。", "properties": { "amount": { "type": "string", "example": "2.9900", "description": "商品折后价格。" }, "amount_without_discount": { "type": "string", "example": "2.9900", "description": "商品价格。" }, "currency": { "type": "string", "example": "USD", "description": "商品价格币种。符合[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)标准的三字母代码。" } } }, "promotions": { "$ref": "#/components/schemas/Catalog_item_promotions" }, "can_be_bought": { "$ref": "#/components/schemas/Can_be_bought" }, "vp_rewards": { "$ref": "#/components/schemas/client-item-value-point-reward" }, "limits": { "$ref": "#/components/schemas/Catalog_item_limits" }, "periods": { "$ref": "#/components/schemas/item-periods" } } }, "example": [ { "attributes": [], "description": "Take it, take it all! All of Xsolla's riches in one Mega Booster.", "groups": [ { "external_id": "powerups", "name": "Power Ups" } ], "image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png", "is_free": false, "name": "Xsolla Booster Mega", "price": { "amount": "50.0000000000000000", "amount_without_discount": "100.0000000000000000", "currency": "USD" }, "quantity": 123, "sku": "com.xsolla.booster_mega_1", "type": "virtual_good", "virtual_item_type": "consumable", "virtual_prices": [], "promotions": [ { "name": "Bonus promotion", "date_start": "2020-04-15T16:16:00+03:00", "date_end": "2026-04-15T16:16:00+03:00", "discount": { "percent": "50.00" }, "bonus": [ { "quantity": 1, "name": "Xsolla Minigun", "image_url": "https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png", "sku": "com.xsolla.minigun_1", "type": "virtual_good" } ] } ], "can_be_bought": true, "vp_rewards": [ { "item_id": 175232, "sku": "com.xsolla.value_point_1", "amount": 130, "name": "Value point", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg" }, { "item_id": 186321, "sku": "com.xsolla.clan_value_point_1", "amount": 50, "name": "Clan Reward VP 1", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "is_clan": true } ], "limits": { "per_user": { "available": 3, "recurrent_schedule": { "interval_type": "weekly", "reset_next_date": 1746057600 }, "total": 5 } }, "periods": [ { "date_from": "2020-08-11T10:00:00+03:00", "date_until": "2020-08-11T20:00:00+03:00" } ] } ] } } }, "examples": { "response": { "value": { "cart_id": "cart_id", "is_free": false, "items": [ { "attributes": [], "description": "Take it, take it all! All of Xsolla's riches in one Mega Booster.", "groups": [ { "external_id": "powerups", "name": "Power Ups" } ], "image_url": "https://cdn.xsolla.net/img/misc/images/e9f2f4a634bc96ea03b5d5ceadd7c55f.png", "is_free": false, "name": "Xsolla Booster Mega", "price": { "amount": "50.0000000000000000", "amount_without_discount": "100.0000000000000000", "currency": "USD" }, "quantity": 123, "sku": "com.xsolla.booster_mega_1", "type": "virtual_good", "virtual_item_type": "consumable", "virtual_prices": [], "promotions": [ { "name": "Bonus promotion", "date_start": "2020-04-15T16:16:00+03:00", "date_end": "2026-04-15T16:16:00+03:00", "discount": { "percent": "50.00" }, "bonus": [ { "quantity": 1, "name": "Xsolla Minigun", "image_url": "https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png", "sku": "com.xsolla.minigun_1", "type": "virtual_good" } ] } ], "can_be_bought": true, "vp_rewards": [ { "item_id": 175232, "sku": "com.xsolla.value_point_1", "amount": 130, "name": "Value point", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg" }, { "item_id": 186321, "sku": "com.xsolla.clan_value_point_1", "amount": 50, "name": "Clan Reward VP 1", "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg", "is_clan": true } ], "limits": { "per_user": { "available": 3, "recurrent_schedule": { "interval_type": "weekly", "reset_next_date": 1746057600 }, "total": 5 } }, "periods": [ { "date_from": "2020-08-11T10:00:00+03:00", "date_until": "2020-08-11T20:00:00+03:00" } ] } ], "price": { "amount": "6150.0000000000000000", "amount_without_discount": "6150.0000000000000000", "currency": "USD" } } } } } } }, "Promotions_422-cancel-promo-code": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-1102]: Unprocessable Entity. The property `id` is required" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } }, "examples": { "response": { "value": { "statusCode": 422, "errorCode": 1102, "errorMessage": "[0401-1102]: Unprocessable Entity. The property `id` is required" } } } } } }, "Promotions_200-promocode-rewards": { "description": "已成功接收兑换码奖励列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Promo_code_rewards" }, "examples": { "response": { "$ref": "#/components/examples/Promotions_200-get-promocode-rewards" } } } } }, "Promotions_200-get-promocodes": { "description": "成功收到兑换码列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Promotions_200-get-promocode-promotion-model" } }, "total_promotions_count": { "$ref": "#/components/schemas/total_promotions_count" }, "active_promotions_count": { "$ref": "#/components/schemas/active_promotions_count" }, "inactive_promotions_count": { "$ref": "#/components/schemas/inactive_promotions_count" } } }, "examples": { "response": { "$ref": "#/components/examples/Promotions_200-admin-promocodes" } } } } }, "Promotions_200-promocode-code-list": { "description": "已成功接收兑换码促销活动的兑换码列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Promotions_coupon_code" } } } }, "total_count": { "type": "number", "description": "兑换码促销活动的兑换码总数。" } } }, "examples": { "response": { "$ref": "#/components/examples/Promotions_200-coupon-code-list" } } } } }, "Promotions_200-get-item-promotions": { "description": "已成功收到商品促销活动列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "promotions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "促销活动ID。项目内的唯一促销活动标识符。" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "is_enabled": { "$ref": "#/components/schemas/Promotions_is_enabled" }, "name": { "type": "object", "description": "促销活动名称。应包含键/值对，其中键是格式为\"^[a-z]{2}-[A-Z]{2}$\"的区域设置，值是字符串。", "additionalProperties": { "type": "string" }, "example": { "en-US": "Promotion", "ru-RU": "Акция" } }, "discount": { "type": "object", "properties": { "percent": { "type": [ "string", "null" ], "description": "百分比折扣。\n商品价格使用此百分比计算打折价格。", "default": "10.00" } } }, "items": { "type": [ "array", "null" ], "items": { "description": "适用折扣的商品列表。", "type": "object", "properties": { "sku": { "type": [ "string", "null" ], "description": "商品SKU。", "default": "elven_sword" } } } }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-get" }, "limits": { "$ref": "#/components/schemas/Promotions_promotion_limits_response" }, "excluded_promotions": { "$ref": "#/components/schemas/excluded_promotions" }, "price_conditions": { "$ref": "#/components/schemas/price_conditions_discount" } } } }, "total_promotions_count": { "$ref": "#/components/schemas/total_promotions_count" }, "active_promotions_count": { "$ref": "#/components/schemas/active_promotions_count" }, "inactive_promotions_count": { "$ref": "#/components/schemas/inactive_promotions_count" } } }, "examples": { "response": { "value": { "promotions": [ { "id": 1, "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "is_enabled": true, "discount": { "percent": "20.00" }, "items": [ { "sku": "com.xsolla.elven_sword_1" } ], "name": { "en-US": "Promotion", "ru-RU": "Акция" }, "limits": { "per_user": null, "per_item": null, "recurrent_schedule": null } }, { "id": 2, "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "is_enabled": true, "discount": { "percent": "10.00" }, "items": [ { "sku": "com.xsolla.elven_helmet_1" }, { "sku": "com.xsolla.elven_armor_1" } ], "name": { "en-US": "Promotion", "ru-RU": "Акция" }, "limits": { "per_user": { "total": 10 }, "per_item": null, "recurrent_schedule": { "per_user": { "interval_type": "daily", "time": "11:00:00+08:00", "reset_next_date": 1677553200, "displayable_reset_start_date": "2023-02-28T11:00:00+08:00", "displayable_reset_next_date": "2023-02-28T11:00:00+08:00" } } }, "excluded_promotions": [ 1, 3 ] }, { "id": 3, "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "is_enabled": true, "discount": { "percent": "10.00" }, "items": [ { "sku": "com.xsolla.elven_helmet_2" }, { "sku": "com.xsolla.elven_armor_2" } ], "name": { "en-US": "Promotion", "ru-RU": "Акция" }, "limits": { "per_user": { "total": 10 }, "per_item": null, "recurrent_schedule": { "per_user": { "interval_type": "daily", "time": "11:00:00+08:00", "reset_next_date": 1677553200, "displayable_reset_start_date": "2023-02-28T11:00:00+08:00", "displayable_reset_next_date": "2023-02-28T11:00:00+08:00" } } }, "price_conditions": [ { "operator": "gt", "value": "10.0000" }, { "operator": "lt", "value": "20.0000" } ] }, { "id": 4, "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "is_enabled": true, "discount": { "percent": "10.00" }, "items": null, "name": { "en-US": "Promotion", "ru-RU": "Акция" }, "limits": { "per_user": { "total": 10 }, "per_item": null, "recurrent_schedule": { "per_user": { "interval_type": "daily", "time": "11:00:00+08:00", "reset_next_date": 1677553200, "displayable_reset_start_date": "2023-02-28T11:00:00+08:00", "displayable_reset_next_date": "2023-02-28T11:00:00+08:00" } } }, "price_conditions": [ { "operator": "lt", "value": "20.0000" } ] } ], "total_promotions_count": 4, "active_promotions_count": 4, "inactive_promotions_count": 0 } } } } } }, "Promotions_201-create-promotion": { "description": "促销活动已成功创建。", "content": { "application/json": { "schema": { "type": "object", "properties": { "promotion_id": { "type": "integer", "description": "促销活动ID。项目内的唯一促销活动标识符。" } } }, "examples": { "response": { "value": { "promotion_id": 2384756 } } } } } }, "Promotions_422-admin-promotion-missed-items-property": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-1102]: Unprocessable Entity. The property `items` is required" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } }, "examples": { "response": { "value": { "statusCode": 422, "errorCode": 1102, "errorMessage": "[0401-1102]: Unprocessable Entity. The property `items` is required", "transactionId": "x-x-x-x-transactionId-mock-x-x-x" } } } } } }, "Promotions_404-admin-promotion": { "description": "未找到促销活动。请确保`promotion_id`正确无误。", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 9502 }, "errorMessage": { "type": "string", "example": "[0401-9502]: Can not find promotion with ID = 111425 in project 59080" } }, "type": "object" }, "examples": { "response": { "value": { "statusCode": 404, "errorCode": 9502, "errorMessage": "[0401-9502]: Can not find promotion with ID = 111425 in project 59080" } } } } } }, "Promotions_200-get-bonus-promotions": { "description": "已成功收到买赠促销活动列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "promotions": { "type": "array", "items": { "$ref": "#/components/schemas/Promotions_200-get-bonus-promotion-model" } }, "total_promotions_count": { "$ref": "#/components/schemas/total_promotions_count" }, "active_promotions_count": { "$ref": "#/components/schemas/active_promotions_count" }, "inactive_promotions_count": { "$ref": "#/components/schemas/inactive_promotions_count" } } }, "examples": { "response": { "value": { "promotions": [ { "id": 1, "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "is_enabled": true, "condition": [ { "sku": "com.xsolla.elven_boots_1" }, { "sku": "com.xsolla.elven_knife_1" } ], "bonus": [ { "sku": "com.xsolla.elven_sword_1", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_1", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_1", "quantity": 2 } ], "limits": { "per_user": null, "per_item": null, "recurrent_schedule": null } }, { "id": 2, "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "Summer season bonus", "de-DE": "Sommersaison Bonus" }, "is_enabled": true, "condition": null, "bonus": [ { "sku": "com.xsolla.diamonds_1", "quantity": 100 } ], "limits": { "per_user": { "total": 10 }, "per_item": null, "recurrent_schedule": { "per_user": { "interval_type": "daily", "time": "11:00:00+08:00", "reset_next_date": 1677553200, "displayable_reset_start_date": "2023-02-28T11:00:00+08:00", "displayable_reset_next_date": "2023-02-28T11:00:00+08:00" } } }, "price_conditions": [ { "operator": "gt", "value": "10.0000" }, { "operator": "lt", "value": "50.0000" } ], "excluded_promotions": [ 1 ] } ], "total_promotions_count": 2, "active_promotions_count": 2, "inactive_promotions_count": 0 } } } } } }, "Promotions_422-admin-promotion-missed-bonus-property": { "description": "请求无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 1102 }, "errorMessage": { "type": "string", "example": "[0401-1102]: Unprocessable Entity. The property `bonus` is required" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } }, "examples": { "response": { "value": { "statusCode": 422, "errorCode": 1102, "errorMessage": "[0401-1102]: Unprocessable Entity. The property `bonus` is required", "transactionId": "x-x-x-x-transactionId-mock-x-x-x" } } } } } }, "Promotions_200-admin-get-bonus-promotion": { "description": "已成功收到买赠促销活动。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Promotions_200-get-bonus-promotion-model" }, "examples": { "response": { "value": { "id": 1, "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "is_enabled": true, "condition": [ { "sku": "com.xsolla.elven_boots_1" }, { "sku": "com.xsolla.elven_knife_1" } ], "bonus": [ { "sku": "com.xsolla.elven_sword_1", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_1", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_1", "quantity": 2 } ], "limits": { "per_user": { "total": 10 }, "per_item": null, "recurrent_schedule": { "per_user": { "interval_type": "daily", "time": "11:00:00+08:00", "reset_next_date": 1677553200, "displayable_reset_start_date": "2023-02-28T11:00:00+08:00", "displayable_reset_next_date": "2023-02-28T11:00:00+08:00" } } }, "excluded_promotions": [ 23, 45 ], "price_conditions": [ { "operator": "gt", "value": "10.0000" }, { "operator": "lt", "value": "50.0000" } ] } } } } } }, "Promotions_200-verify-promo-code": { "description": "有关代码的信息。", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "代码类型：`promocode`/`coupon`。" }, "code": { "$ref": "#/components/schemas/Promotions_coupon_code" }, "rewards": { "oneOf": [ { "$ref": "#/components/schemas/Coupon_rewards" }, { "$ref": "#/components/schemas/Promo_code_rewards_verify" } ] } } }, "examples": { "coupon info": { "value": { "type": "coupon", "code": "WINTER2023", "rewards": { "bonus": [ { "item": { "sku": "com.xsolla.game_1", "name": "Game name", "type": "unit", "description": "Game description", "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "unit_items": [ { "sku": "com.xsolla.game_key_01", "name": "Game name", "type": "game_key", "is_free": false, "drm_name": "Steam", "drm_sku": "steam_key_1" }, { "sku": "com.xsolla.game_key_02", "name": "Game name", "type": "game_key", "drm_name": "Origin", "drm_sku": "origin_key_1" } ] }, "quantity": 1 }, { "item": { "sku": "com.xsolla.game_2", "name": "Game name", "type": "unit", "description": "Game description", "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "unit_items": [ { "sku": "com.xsolla.game_key_01", "type": "game_key", "name": "Game name", "drm_name": "Steam", "drm_sku": "steam_key_1" } ] }, "quantity": 2 } ], "is_selectable": true } } }, "promocode info": { "value": { "type": "promocode", "code": "SUMMER2023", "rewards": { "bonus": [ { "item": { "sku": "com.xsolla.game_2", "name": "Game name", "type": "unit", "description": "Game description", "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png", "unit_items": [ { "sku": "com.xsolla.game_key_01", "type": "game_key", "name": "Game name", "drm_name": "Steam", "drm_sku": "steam_key_1" } ] }, "quantity": 2 } ], "discount": { "percent": "10.00" }, "discounted_items": [ { "sku": "com.xsolla.elven_sword_1", "name": "Elven sword", "type": "virtual_good", "description": "sword", "image_url": null, "discount": { "percent": "10.00" } } ], "is_selectable": true } } } } } } }, "Promotions_404-verify-promo-code": { "description": "未找到代码。请确保`code`值正确无误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 9811 }, "errorMessage": { "type": "string", "example": "[0401-9811]: Code not found." }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } } } } }, "Promotions_422-verify-promo-code": { "description": "代码促销活动无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorCode": { "type": "integer" }, "statusCode": { "type": "integer" }, "errorMessage": { "type": "string" } } }, "examples": { "code redemption limit": { "value": { "errorCode": 9804, "statusCode": 422, "errorMessage": "[0401-9804]: You have reached the coupon redemption limit." } }, "regionally restricted": { "value": { "errorCode": 9808, "statusCode": 422, "errorMessage": "[0401-9808]: Coupon is not available in your region." } } } } } }, "Promotions_200-get-unique-catalog-offers": { "description": "已成功接收优惠券列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Promotions_200-get-unique-catalog-offer-promotion-model" } }, "total_promotions_count": { "$ref": "#/components/schemas/total_promotions_count" }, "active_promotions_count": { "$ref": "#/components/schemas/active_promotions_count" }, "inactive_promotions_count": { "$ref": "#/components/schemas/inactive_promotions_count" } } }, "examples": { "response": { "$ref": "#/components/examples/Promotions_200-admin-unique-catalog-offers" } } } } }, "Promotions_200-unique-catalog-offer-code-list": { "description": "已成功接收专属商品目录优惠的代码列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Promotions_coupon_code" } } } }, "total_count": { "type": "number", "description": "专属商品目录优惠代码总数。" } } }, "examples": { "response": { "$ref": "#/components/examples/Promotions_200-coupon-code-list" } } } } }, "200-admin-get-user-promo-code-limits": { "description": "已成功收到用户的兑换码限制。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User-limit-promo-code" }, "examples": { "response": { "value": { "per_user": { "total": 10, "available": 9 } } } } } } }, "Common_401-invalid-basic-auth": { "description": "基本身份认证未通过或不正确。请确保您使用了基本身份认证或正确的凭据。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 401 }, "errorCode": { "type": "integer", "example": 1020 }, "errorMessage": { "type": "string", "example": "[0401-1020]: Error in Authentication method occurred" } } }, "examples": { "response": { "value": { "statusCode": 401, "errorCode": 1020, "errorMessage": "[0401-1020]: Error in Authentication method occurred" } } } } } }, "200-admin-get-user-coupon-limits": { "description": "成功收到用户的优惠券限制。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User-limit-coupon" }, "examples": { "response": { "value": { "per_user": { "total": 10, "available": 9 } } } } } } }, "200-admin-get-code-promo-code-limits": { "description": "已成功收到代码的兑换码限制。", "content": { "application/json": { "schema": { "type": "object", "properties": { "promotion_id": { "type": "integer", "description": "促销活动ID。项目内的唯一促销活动标识符。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Code-limit-promo-code" } }, "total_items_count": { "type": "number", "description": "代码总数。" }, "has_more": { "type": "boolean", "description": "如果存在其他含代码的页面。" } } }, "examples": { "response": { "$ref": "#/components/examples/code-limit" } } } } }, "200-admin-get-code-coupon-limits": { "description": "成功收到代码的优惠券限额。", "content": { "application/json": { "schema": { "type": "object", "properties": { "promotion_id": { "type": "integer", "description": "促销活动ID。项目内的唯一促销活动标识符。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Code-limit-promo-code" } }, "total_items_count": { "type": "number", "description": "代码总数。" }, "has_more": { "type": "boolean", "description": "如果存在其他含代码的页面。" } } }, "examples": { "response": { "$ref": "#/components/examples/code-limit" } } } } }, "Common_401-complex": { "description": "身份认证未通过或错误。请确保您使用了身份认证或正确的凭据。", "content": { "application/json": { "schema": { "properties": { "statusCode": { "type": "integer", "example": 401 }, "errorCode": { "type": "integer", "example": 1501 }, "errorMessage": { "type": "string", "example": "[0401-1501]: Authorization failed: Authorization header not sent" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } }, "type": "object" }, "examples": { "Authorization header not sent": { "$ref": "#/components/examples/401-complex-auth-header-not-found" }, "Incorrect credentials": { "$ref": "#/components/examples/401-complex-auth-incorrect-credentials" } } } } }, "403-auth-header-not-sent": { "description": "未发送Authorization请求头。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 403 }, "errorCode": { "type": "integer", "example": 0 }, "errorMessage": { "type": "string", "example": "未发送Authorization请求头。" }, "transactionId": { "type": "string", "example": "x-x-x-x-transactionId-mock-x-x-x" } } }, "examples": { "response": { "value": { "statusCode": 403, "errorCode": 0, "errorMessage": "Authorization header not sent" } } } } } }, "Common_422-body-validation": { "description": "请求验证错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422-invalid-request" }, "examples": { "response": { "value": { "statusCode": 422, "errorCode": 1102, "errorMessage": "[0401-1102]: Unprocessable Entity. The property `name` is required", "transactionId": "da145238620011eb8e24fe6913ff226a" } } } } } }, "200-admin-get-user-promotion-limits": { "description": "已成功收到用户的促销活动限制。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User-limit-promotion" }, "examples": { "response": { "value": { "per_user": { "total": 10, "available": 9 } } } } } } }, "200-admin-get-value-points": { "description": "已成功收到累充积分列表。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-value-points-reward-chain_admin_get-value-point-list" } }, "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Value-points-item-model" } } } } } } }, "201-admin-create-value-point": { "description": "已成功创建累充积分。", "content": { "application/json": { "examples": { "response": { "value": { "sku": "com.xsolla.item_new", "item_id": 10 } } }, "schema": { "type": "object", "properties": { "sku": { "type": "string", "example": "new-sku" }, "item_id": { "type": "integer", "example": 10 } } } } } }, "422-admin-create-update-rc-vp-invalid-request": { "description": "请求无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/422-rc-vp-invalid-request" }, "examples": { "The property `sku` is required": { "$ref": "#/components/examples/422-property-sku-is-required" } } } } }, "200-admin-get-value-point": { "description": "已成功收到指定的累充积分。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-value-points-reward-chain_admin_get-value-point" } }, "schema": { "$ref": "#/components/schemas/Value-point-item-model" } } } }, "200-admin-get-list-value-point-rewards": { "description": "已成功收到包含累充积分奖励的商品列表。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-value-points-rewards-list" } }, "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/admin-item-value-point-reward" } } } } } } }, "sellable-item-by-sku_404": { "description": "未找到商品。请确保`project_id`和`sku`正确无误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 4001 }, "errorMessage": { "type": "string", "example": "[0401-4001]: Item with sku = 'electric_shiel' not found" } } } } } }, "200-client-get-reward-chains-list": { "description": "已成功获取用户的累充奖励链。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-client-get-reward-chains-list" } }, "schema": { "type": "object", "properties": { "has_more": { "type": "boolean", "example": true, "description": "用作指示还有更多页面。" }, "total_items_count": { "type": "integer", "example": 10, "description": "系统中累充奖励链的总数。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/client-reward-chain-item-model" } } } } } } }, "200-client-get-user-reward-chain-balance": { "description": "已成功获取用户的累充积分余额。", "content": { "application/json": { "examples": { "common": { "$ref": "#/components/examples/200-client-get-user-reward-chain-balance" }, "clan": { "$ref": "#/components/examples/200-client-get-user-clan-reward-chain-balance" } }, "schema": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/value-point-sku" }, "name": { "$ref": "#/components/schemas/value-point-name" }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "description": { "$ref": "#/components/schemas/value-point-description" }, "long_description": { "$ref": "#/components/schemas/value-point-long-description" }, "amount": { "type": "integer", "description": "累充积分数量。" }, "is_clan": { "$ref": "#/components/schemas/is_clan" } } } } } }, "404-reward-chain-step-not-found": { "description": "未找到奖励链步骤。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 9911 }, "errorMessage": { "type": "string", "example": "[0401-9911]: Reward chain step not found." } } }, "examples": { "response": { "value": { "statusCode": 404, "errorCode": 9911, "errorMessage": "[0401-9911]: Reward chain step not found." } } } } } }, "422-reward-chain-step-reward-can-not-claimed": { "description": "无法领取步骤奖励。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 422 }, "errorCode": { "type": "integer", "example": 9912 }, "errorMessage": { "type": "string", "example": "[0401-9912]: Can't claim the step reward." } } }, "examples": { "Reward chain step reward already claimed": { "value": { "statusCode": 422, "errorCode": 9912, "errorMessage": "[0401-9912]: Reward already claimed." } }, "Not enough VP to claim reward chain step reward": { "value": { "statusCode": 422, "errorCode": 9913, "errorMessage": "[0401-9913]: Not enough value points to claim step reward." } } } } } }, "200-client-update-user-clan": { "description": "成功更新了用户的公会。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-client-update-user-clan" } }, "schema": { "type": "object", "properties": { "reward": { "type": "array", "items": { "type": "object", "properties": { "sku": { "$ref": "#/components/schemas/sku" }, "name": { "type": "string", "example": "Super box", "description": "商品名称。" }, "type": { "type": "string", "example": "bundle", "description": "商品类型。" }, "description": { "type": "string", "example": "Super box with items", "description": "Item description." }, "image_url": { "$ref": "#/components/schemas/Common_admin-image_url" }, "quantity": { "type": "integer", "example": 2, "description": "商品数量。" }, "bundle_type": { "type": "string", "description": "捆绑包类型。如果商品类型为捆绑包，则返回。", "enum": [ "standard", "virtual_currency_package" ] } } } } } } } } }, "200-admin-get-list-reward-chains": { "description": "已成功接收累充奖励链列表。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-reward-chain-list" } }, "schema": { "type": "object", "properties": { "has_more": { "$ref": "#/components/schemas/Pagination_has-more" }, "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/admin-get-reward-chain-item-basic-model" }, { "$ref": "#/components/schemas/admin-get-reward-chain-item-clan-basic-model" } ] } } } } } } }, "201-admin-create-reward-chain": { "description": "已成功创建累充奖励链。", "content": { "application/json": { "examples": { "response": { "value": { "reward_chain_id": 10 } } }, "schema": { "type": "object", "properties": { "reward_chain_id": { "type": "integer", "example": 10 } } } } } }, "200-admin-get-reward-chain": { "description": "已成功收到指定的累充奖励链。", "content": { "application/json": { "examples": { "common": { "$ref": "#/components/examples/200-reward-chain" }, "clan": { "$ref": "#/components/examples/200-clan-reward-chain" } }, "schema": { "oneOf": [ { "$ref": "#/components/schemas/admin-get-reward-chain-item-full-model" }, { "$ref": "#/components/schemas/admin-get-reward-chain-item-clan-full-model" } ] } } } }, "404-admin-reward-chain-not-found": { "description": "未找到累充奖励链。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 4001 }, "errorMessage": { "type": "string", "example": "[0401-4001]: Reward chain not found" } } }, "examples": { "response": { "value": { "statusCode": 404, "errorCode": 9901, "errorMessage": "[0401-4001]: Reward chain not found" } } } } } }, "204-admin-update-reward-chain": { "description": "已成功更新累充奖励链。", "content": {} }, "204-admin-delete-reward-chain": { "description": "已成功删除累充奖励链。", "content": {} }, "204-admin-toggle-reward-chain": { "description": "已禁用/启用累充奖励链。", "content": {} }, "204-admin-reset-reward-chain": { "description": "累充奖励链已重置。", "content": {} }, "200-admin-get-list-daily-chains": { "description": "每日奖励列表检索成功。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-admin-daily-chain-list" } }, "schema": { "type": "object", "properties": { "has_more": { "$ref": "#/components/schemas/Pagination_has-more" }, "total_items_count": { "type": "integer", "example": 3, "description": "每日奖励总数。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/admin-daily-chain-short-model" } } } } } } }, "201-admin-create-daily-chain": { "description": "每日奖励创建成功。", "content": { "application/json": { "examples": { "response": { "value": { "daily_chain_id": 10 } } }, "schema": { "type": "object", "properties": { "daily_chain_id": { "type": "integer", "example": 10 } } } } } }, "422-admin-create-error-list": { "description": "每日奖励配置错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/daily-chain-error-model" }, "examples": { "too-many-steps-error": { "$ref": "#/components/examples/422-admin-daily-chain-error-too-many-steps" }, "incorrect-steps-order-error": { "$ref": "#/components/examples/422-admin-daily-chain-error-incorrect-steps-order" }, "item-limit-exceeded": { "$ref": "#/components/examples/422-admin-daily-chain-error-item-limit-exceeded" }, "incorrect-items": { "$ref": "#/components/examples/422-admin-daily-chain-error-incorrect-items" }, "invalid-dates": { "$ref": "#/components/examples/422-admin-daily-chain-error-invalid-dates" }, "incorrect-period": { "$ref": "#/components/examples/422-admin-daily-chain-error-incorrect-period" } } } } }, "200-admin-get-daily-chain": { "description": "每日奖励数据检索成功。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-admin-daily-chain" } }, "schema": { "$ref": "#/components/schemas/admin-daily-chain-long-model" } } } }, "404-daily-chain-not-found": { "description": "未找到每日奖励。", "content": { "application/json": { "examples": { "not-found": { "$ref": "#/components/examples/404-daily-chain-not-found" } }, "schema": { "$ref": "#/components/schemas/daily-chain-error-model" } } } }, "422-admin-update-error-list": { "description": "每日奖励配置错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/daily-chain-error-model" }, "examples": { "too-many-steps-error": { "$ref": "#/components/examples/422-admin-daily-chain-error-too-many-steps" }, "incorrect-steps-order-error": { "$ref": "#/components/examples/422-admin-daily-chain-error-incorrect-steps-order" }, "item-limit-exceeded": { "$ref": "#/components/examples/422-admin-daily-chain-error-item-limit-exceeded" }, "incorrect-items": { "$ref": "#/components/examples/422-admin-daily-chain-error-incorrect-items" }, "invalid-dates": { "$ref": "#/components/examples/422-admin-daily-chain-error-invalid-dates" }, "incorrect-period": { "$ref": "#/components/examples/422-admin-daily-chain-error-incorrect-period" }, "invalid-chain-step-ids": { "$ref": "#/components/examples/422-admin-daily-chain-error-invalid-chain-step-ids" }, "chain-id-mismatch": { "$ref": "#/components/examples/422-admin-daily-chain-error-chain-id-mismatch" }, "chain-step-ids-duplication": { "$ref": "#/components/examples/422-admin-daily-chain-error-duplicate-step-ids" }, "active-daily-chain": { "$ref": "#/components/examples/422-admin-daily-chain-error-activated" } } } } }, "200-client-get-daily-chains-list": { "description": "用户每日奖励检索成功。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-client-daily-chain-list" } }, "schema": { "type": "object", "properties": { "has_more": { "type": "boolean", "example": true, "description": "用作指示还有更多页面。" }, "total_items_count": { "type": "integer", "example": 3, "description": "每日奖励总数。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/client-daily-chain-model" } } } } } } }, "401-client-auth-error": { "description": "认证未通过或错误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 401 }, "errorCode": { "type": "integer", "example": 1501 }, "errorMessage": { "type": "string", "example": "[0401-1501]: Authorization failed: Provide authorization" } } }, "examples": { "response": { "value": { "statusCode": 401, "errorCode": 1501, "errorMessage": "[0401-1501]: Authorization failed: Provide authorization" } } } } } }, "404-daily-chain-step-not-found": { "description": "未找到每日奖励或每日奖励步骤。", "content": { "application/json": { "examples": { "not-found": { "$ref": "#/components/examples/404-daily-chain-step-not-found" } }, "schema": { "$ref": "#/components/schemas/daily-chain-error-model" } } } }, "200-client-get-offer-chains-list": { "description": "优惠链列表接收成功。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-client-offer-chain-list" } }, "schema": { "type": "object", "properties": { "has_more": { "type": "boolean", "example": true, "description": "是否有更多分页。" }, "total_items_count": { "type": "integer", "example": 10, "description": "可用优惠链总数。" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/client-offer-chain-model" } } } } } } }, "404-offer-chain-not-found": { "description": "未找到优惠链。", "content": { "application/json": { "examples": { "not-found": { "$ref": "#/components/examples/404-offer-chain-not-found" } }, "schema": { "$ref": "#/components/schemas/offer-chain-error-model" } } } }, "404-offer-chain-step-not-found": { "description": "未找到优惠链或步骤。", "content": { "application/json": { "examples": { "not-found": { "$ref": "#/components/examples/404-offer-chain-step-not-found" } }, "schema": { "$ref": "#/components/schemas/offer-chain-error-model" } } } }, "Cart-Payment_200-order-created": { "description": "已成功创建订单。", "content": { "application/json": { "schema": { "type": "object", "properties": { "order_id": { "type": "integer", "description": "订单ID。" }, "token": { "type": "string", "description": "支付令牌。" } } }, "examples": { "response": { "value": { "order_id": 641, "token": "f4puMEFFDZcx9nv5HoNHIkPe9qghvBQo" } } } } } }, "200-admin-get-list-offer-chains": { "description": "优惠链列表获取成功。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-admin-offer-chain-list" } }, "schema": { "type": "object", "properties": { "has_more": { "$ref": "#/components/schemas/Pagination_has-more" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/admin-offer-chain-short-model" } } } } } } }, "201-admin-create-offer-chain": { "description": "优惠链创建成功。", "content": { "application/json": { "examples": { "response": { "value": { "offer_chain_id": 10 } } }, "schema": { "type": "object", "properties": { "offer_chain_id": { "type": "integer", "example": 10 } } } } } }, "422-create-error-list": { "description": "优惠链配置无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/offer-chain-error-model" }, "examples": { "too-many-steps-error": { "$ref": "#/components/examples/422-admin-offer-chain-error-too-many-steps" }, "incorrect-steps-order-error": { "$ref": "#/components/examples/422-admin-offer-chain-error-incorrect-steps-order" }, "item-limit-exceeded": { "$ref": "#/components/examples/422-admin-offer-chain-error-item-limit-exceeded" }, "incorrect-items": { "$ref": "#/components/examples/422-admin-offer-chain-error-incorrect-items" }, "invalid-dates": { "$ref": "#/components/examples/422-admin-offer-chain-error-invalid-dates" }, "incorrect-period": { "$ref": "#/components/examples/422-admin-offer-chain-error-incorrect-period" } } } } }, "200-admin-get-offer-chain": { "description": "优惠链数据获取成功。", "content": { "application/json": { "examples": { "response": { "$ref": "#/components/examples/200-admin-offer-chain" } }, "schema": { "$ref": "#/components/schemas/admin-offer-chain-long-model" } } } }, "422-update-error-list": { "description": "优惠链配置无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/offer-chain-error-model" }, "examples": { "too-many-steps-error": { "$ref": "#/components/examples/422-admin-offer-chain-error-too-many-steps" }, "incorrect-steps-order-error": { "$ref": "#/components/examples/422-admin-offer-chain-error-incorrect-steps-order" }, "item-limit-exceeded": { "$ref": "#/components/examples/422-admin-offer-chain-error-item-limit-exceeded" }, "incorrect-items": { "$ref": "#/components/examples/422-admin-offer-chain-error-incorrect-items" }, "invalid-dates": { "$ref": "#/components/examples/422-admin-offer-chain-error-invalid-dates" }, "incorrect-period": { "$ref": "#/components/examples/422-admin-offer-chain-error-incorrect-period" }, "invalid-chain-step-ids": { "$ref": "#/components/examples/422-admin-offer-chain-error-invalid-chain-step-ids" }, "chain-id-mismatch": { "$ref": "#/components/examples/422-admin-offer-chain-error-chain-id-mismatch" }, "chain-step-ids-duplication": { "$ref": "#/components/examples/422-admin-offer-chain-error-duplicate-step-ids" }, "active-offer-chain": { "$ref": "#/components/examples/422-admin-offer-chain-error-activated" } } } } }, "Upsell-404-item-not-found": { "description": "未找到商品。", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "errorCode": { "type": "integer", "example": 4001 }, "errorMessage": { "type": "string", "example": "[0401-4001]: Items weren't found: sku1, sku2" } } }, "examples": { "response": { "value": { "statusCode": 404, "errorCode": 9901, "errorMessage": "[0401-4001]: Items weren't found: sku1, sku2" } } } } } }, "Upsell-422-invalid-request": { "description": "请求无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upsell-422-invalid-request" } } } }, "Upsell-200-get-client-list": { "description": "成功接收追加销售商品列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Upsell_item-list" }, "examples": { "response": { "value": { "has_more": true, "items": [ { "sku": "com.xsolla.big_rocket_1", "name": "Big Rocket", "groups": [ { "external_id": "accessory", "name": { "en": "accessory" } } ], "attributes": [ { "external_id": "stack_size", "name": { "en": "Quantity of items in the upsell set" }, "values": [ { "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85", "value": "5" } ] } ], "type": "virtual_good", "description": "Big Rocket - description", "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png", "is_free": false, "price": { "amount": "100.99", "amount_without_discount": "100.99", "currency": "USD" }, "virtual_prices": [ { "amount": 100, "sku": "com.xsolla.vc_1", "is_default": true, "amount_without_discount": 100, "image_url": "http://image.png", "name": "SHOTGUN FOR TRUE RAIDERS", "type": "virtual_currency", "description": "description" } ], "can_be_bought": true, "virtual_item_type": "non_renewing_subscription", "promotions": [ { "name": "Bonus promotion", "date_start": "2020-04-15T16:16:00+03:00", "date_end": "2026-04-15T16:16:00+03:00", "discount": null, "bonus": [ { "quantity": 1, "name": "Xsolla Minigun", "image_url": "https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png", "sku": "com.xsolla.minigun_1", "type": "virtual_good" }, { "quantity": 1, "sku": "com.xsolla.phys_good_1", "type": "physical_good" }, { "quantity": 1, "name": "Super Lootbox with items", "image_url": "https://cdn.xsolla.net/img/misc/images/9676f06265375087e607cb79c5283688.png", "sku": "com.xsolla.SuperLootboxBundle_1", "type": "bundle", "bundle_type": "standard" } ] } ], "limits": { "per_user": { "total": 5, "available": 3, "recurrent_schedule": { "interval_type": "weekly", "reset_next_date": 1746057600 }, "limit_exceeded_visibility": "show" } }, "periods": [ { "date_from": "2020-08-11T10:00:00+03:00", "date_until": "2020-08-11T20:00:00+03:00" } ], "custom_attributes": { "purchased": 0, "attr": "value" }, "vp_rewards": [] }, { "sku": "com.xsolla.shotgun_raider_1", "name": "SHOTGUN FOR TRUE RAIDERS", "groups": [ { "external_id": "weapons", "name": { "en": "Weapons" } } ], "attributes": [ { "external_id": "stack_size", "name": { "en": "Quantity of items in the upsell set" }, "values": [ { "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85", "value": "5" } ] }, { "external_id": "rating", "name": { "en": "Items rating" }, "values": [ { "external_id": "rating_e3364991f92e751689a68b96598a5a5a84010b85", "value": "3.9" } ] } ], "type": "virtual_good", "description": "description", "image_url": "http://image.png", "is_free": false, "price": { "amount": "101.0", "amount_without_discount": "101.0", "currency": "USD" }, "virtual_prices": [ { "amount": 100, "sku": "com.xsolla.vc_2", "is_default": true, "amount_without_discount": 100, "image_url": "http://image.png", "name": "SHOTGUN FOR TRUE RAIDERS", "type": "virtual_currency", "description": "description" }, { "amount": 200, "sku": "com.xsolla.vc_3", "is_default": false, "amount_without_discount": 200, "image_url": "http://image.png", "name": "SHOTGUN FOR TRUE RAIDERS", "type": "virtual_currency", "description": "description" } ], "can_be_bought": true, "virtual_item_type": "non_renewing_subscription", "promotions": [], "limits": null, "periods": [ { "date_from": "2020-08-11T20:00:00+03:00", "date_until": null } ], "vp_rewards": [] }, { "sku": "com.xsolla.shotgun_raider_2", "name": "SHOTGUN FOR TRUE RAIDERS", "groups": [], "attributes": [], "type": "virtual_good", "description": "description", "image_url": "http://image.png", "is_free": true, "price": null, "virtual_prices": [], "can_be_bought": true, "virtual_item_type": "non_renewing_subscription", "promotions": [], "limits": null, "periods": [], "vp_rewards": [] } ] } } } } } } }, "requestBodies": { "Promotions_redeem-coupon-model": { "content": { "application/json": { "schema": { "type": "object", "properties": { "coupon_code": { "type": "string", "description": "唯一优惠券码。包含字母和数字。", "minLength": 1, "maxLength": 128, "example": "WINTER2021", "default": "WINTER2021" }, "selected_unit_items": { "$ref": "#/components/schemas/Promotions_selected_unit_items" } } } } } }, "Promotions_coupon-create": { "content": { "application/json": { "schema": { "type": "object", "required": [ "external_id", "name" ], "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "bonus": { "$ref": "#/components/schemas/Promotions_coupon_bonus" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-post" } } }, "examples": { "simple": { "value": { "external_id": "coupon_external_id", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "bonus": [ { "sku": "com.xsolla.elven_sword_1", "quantity": 1 } ] } }, "personalized": { "value": { "external_id": "coupon_external_id", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "bonus": [ { "sku": "com.xsolla.elven_sword_2", "quantity": 1 } ], "attribute_conditions": [ { "attribute": "account_status", "type": "string", "operator": "eq", "value": "golden", "can_be_missing": false } ] } } } } } }, "Promotions_coupon-update": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "bonus": { "$ref": "#/components/schemas/Promotions_coupon_bonus" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-post" } } }, "examples": { "simple": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "bonus": [ { "sku": "com.xsolla.elven_sword_1", "quantity": 1 } ] } }, "personalized": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "bonus": [ { "sku": "com.xsolla.elven_sword_2", "quantity": 1 } ], "attribute_conditions": [ { "attribute": "account_status", "type": "string", "operator": "eq", "value": "golden", "can_be_missing": false } ] } } } } } }, "Promotions_create-coupon-promocode-code": { "content": { "application/json": { "schema": { "type": "object", "properties": { "coupon_code": { "$ref": "#/components/schemas/Promotions_coupon_code" } } } } } }, "Promotions_redeem-promo-code-model": { "content": { "application/json": { "schema": { "type": "object", "properties": { "coupon_code": { "type": "string", "description": "兑换码的唯一代码。包含字母和数字。", "minLength": 1, "maxLength": 128, "example": "SUMMER2021", "default": "SUMMER2021" }, "cart": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "购物车ID。", "default": "current" } }, "required": [ "id" ] }, "selected_unit_items": { "$ref": "#/components/schemas/Promotions_selected_unit_items" } } } } } }, "Promotions_cancel-promo-code-model": { "content": { "application/json": { "schema": { "type": "object", "properties": { "cart": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "购物车ID。", "default": "current" } }, "required": [ "id" ] } } } } } }, "Promotions_promocode-create": { "content": { "application/json": { "schema": { "type": "object", "required": [ "external_id", "name" ], "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "bonus": { "$ref": "#/components/schemas/Promotions_coupon_bonus" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" }, "discount": { "type": [ "object", "null" ], "properties": { "percent": { "$ref": "#/components/schemas/Promotions_promotion_discount_percent" } }, "example": { "percent": "10.10" } }, "discounted_items": { "$ref": "#/components/schemas/Promotions_discounted_items" }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-post" }, "price_conditions": { "$ref": "#/components/schemas/price_conditions_promocode" }, "item_price_conditions": { "$ref": "#/components/schemas/item_price_conditions_promocode" }, "excluded_promotions": { "$ref": "#/components/schemas/excluded_promotions" } } }, "examples": { "simple bonus": { "value": { "external_id": "promo_code_external_id", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "bonus": [ { "sku": "com.xsolla.elven_sword_1", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_1", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_1", "quantity": 2 } ] } }, "simple discount": { "value": { "external_id": "promo_code_external_id", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Discount", "de-DE": "Neujahrsrabatt" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "discount": { "percent": "10.10" } } }, "personalized": { "value": { "external_id": "coupon_external_id", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Discount", "de-DE": "Neujahrsrabatt" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "discount": { "percent": "10.10" }, "attribute_conditions": [ { "attribute": "account_status", "type": "string", "operator": "eq", "value": "golden", "can_be_missing": false } ] } }, "with price conditions": { "value": { "external_id": "promo_code_external_id", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "bonus": [ { "sku": "com.xsolla.elven_sword_2", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_2", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_2", "quantity": 2 } ], "price_conditions": [ { "operator": "ge", "value": "10.5000" }, { "operator": "lt", "value": "50.0000" } ] } }, "with item price conditions": { "value": { "external_id": "promo_code_external_id", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "discount": { "percent": "10.10" }, "bonus": [ { "sku": "com.xsolla.elven_sword_3", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_3", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_3", "quantity": 2 } ], "item_price_conditions": [ { "operator": "ge", "value": "10.5000" }, { "operator": "lt", "value": "50.0000" } ] } }, "with excluded promotions": { "value": { "external_id": "coupon_external_id", "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Discount", "de-DE": "Neujahrsrabatt" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "discount": { "percent": "10.10" }, "excluded_promotions": [ 12, 789 ] } } } } } }, "Promotions_promocode-update": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "bonus": { "$ref": "#/components/schemas/Promotions_coupon_bonus" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" }, "discount": { "type": [ "object", "null" ], "properties": { "percent": { "$ref": "#/components/schemas/Promotions_promotion_discount_percent" } }, "example": { "percent": "10.10" } }, "discounted_items": { "$ref": "#/components/schemas/Promotions_discounted_items" }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-post" }, "price_conditions": { "$ref": "#/components/schemas/price_conditions_promocode" }, "item_price_conditions": { "$ref": "#/components/schemas/item_price_conditions_promocode" }, "excluded_promotions": { "$ref": "#/components/schemas/excluded_promotions" } } }, "examples": { "simple bonus": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "bonus": [ { "sku": "com.xsolla.elven_sword_1", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_1", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_1", "quantity": 2 } ] } }, "simple discount": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Discount", "de-DE": "Neujahrsrabatt" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "discount": { "percent": "10.10" } } }, "personalized": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Discount", "de-DE": "Neujahrsrabatt" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "discount": { "percent": "10.10" }, "attribute_conditions": [ { "attribute": "account_status", "type": "string", "operator": "eq", "value": "golden", "can_be_missing": false } ] } }, "with price conditions": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "bonus": [ { "sku": "com.xsolla.elven_sword_2", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_2", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_2", "quantity": 2 } ], "price_conditions": [ { "operator": "gt", "value": "10.5000" }, { "operator": "lt", "value": "50.0000" } ] } }, "with item price conditions": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "discount": { "percent": "10.10" }, "bonus": [ { "sku": "com.xsolla.elven_sword_3", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_3", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_3", "quantity": 2 } ], "item_price_conditions": [ { "operator": "gt", "value": "10.5000" }, { "operator": "lt", "value": "50.0000" } ] } }, "with excluded promotions": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Discount", "de-DE": "Neujahrsrabatt" }, "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1, "discount": { "percent": "10.10" }, "excluded_promotions": [ 12, 789 ] } } } } } }, "Promotions_create-update-item-promotion": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "object", "description": "促销活动名称。应包含键/值对，\n其中键是格式为\"^[a-z]{2}-[A-Z]{2}$\"的区域设置，值是字符串。", "additionalProperties": { "type": "string" }, "example": { "en-US": "Promotion", "ru-RU": "Акция" } }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "discount": { "type": "object", "properties": { "percent": { "type": "string", "description": "百分比折扣。\n商品价格将按照此百分比打折，然后四舍五入到小数点后两位。", "example": 10 } }, "required": [ "percent" ] }, "items": { "type": "array", "items": { "description": "适用折扣的商品列表。", "type": "object", "properties": { "sku": { "type": "string", "description": "商品SKU。", "default": "elven_sword" } }, "required": [ "sku" ] } }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-post" }, "price_conditions": { "$ref": "#/components/schemas/price_conditions_discount" }, "limits": { "$ref": "#/components/schemas/Promotions_promotion_limits" }, "excluded_promotions": { "$ref": "#/components/schemas/excluded_promotions" }, "is_enabled": { "$ref": "#/components/schemas/Promotions_is_enabled" } }, "required": [ "items", "discount", "name" ] }, "examples": { "simple": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-16T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "discount": { "percent": "10.00" }, "items": [ { "sku": "com.xsolla.elven_sword_1" }, { "sku": "com.xsolla.elven_helmet_1" }, { "sku": "com.xsolla.elven_armor_1" } ], "name": { "en-US": "Promotion", "ru-RU": "Акция" }, "is_enabled": true } }, "personalized": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "discount": { "percent": "24.00" }, "items": [], "is_enabled": true, "name": { "en-US": "Ork set discount", "ru-RU": "Скидка на набор для орка" }, "attribute_conditions": [ { "type": "string", "attribute": "race", "operator": "eq", "value": "ork" }, { "type": "number", "attribute": "level", "operator": "eq", "value": "10", "can_be_missing": true } ] } }, "with price condition": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "discount": { "percent": "24.00" }, "items": [], "name": { "en-US": "Ork set discount", "ru-RU": "Скидка на набор для орка" }, "price_conditions": [ { "operator": "ge", "value": "10.5000" }, { "operator": "lt", "value": "20.5000" } ] } }, "with excluded promotions": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "discount": { "percent": "24.00" }, "items": [], "name": { "en-US": "Ork set discount", "ru-RU": "Скидка на набор для орка" }, "excluded_promotions": [ 12, 789 ], "is_enabled": true } } } } }, "description": "包含促销活动数据的对象。", "required": true }, "Promotions_create-update-bonus-promotion": { "content": { "application/json": { "schema": { "type": "object", "required": [ "condition", "bonus", "name" ], "properties": { "id": { "type": "integer", "description": "促销活动ID。项目内的唯一促销活动标识符。" }, "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "type": "object", "description": "促销活动名称。应包含键/值对，其中键是\"^[a-z]{2}-[A-Z]{2}$\"格式的区域设置，值是字符串。", "additionalProperties": { "type": "string" }, "example": { "en-US": "Summer season bonus", "de-DE": "Sommersaison Bonus" } }, "condition": { "type": [ "array", "null" ], "description": "要应用促销必须在购买项中包含的一组商品。如果此参数为`null`，则促销将应用于项目内的任何购买。", "items": { "type": "object", "properties": { "sku": { "type": "string", "description": "商品SKU。", "default": "elven_sword" } } } }, "attribute_conditions": { "$ref": "#/components/schemas/promotion_user-attribute_conditions_model-post" }, "bonus": { "type": [ "array", "null" ], "items": { "description": "将作为赠品添加到用户购买中的商品列表。", "type": "object", "properties": { "sku": { "type": "string", "description": "商品SKU。", "default": "elven_shield" }, "quantity": { "type": "number", "description": "商品数量。", "default": 1 } } } }, "limits": { "$ref": "#/components/schemas/Promotions_promotion_limits" }, "price_conditions": { "$ref": "#/components/schemas/price_conditions_bonus" }, "excluded_promotions": { "$ref": "#/components/schemas/excluded_promotions" }, "is_enabled": { "$ref": "#/components/schemas/Promotions_is_enabled" } } }, "examples": { "simple": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "condition": [ { "sku": "com.xsolla.elven_boots_1" }, { "sku": "com.xsolla.elven_knife_1" } ], "bonus": [ { "sku": "com.xsolla.elven_sword_1", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_1", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_1", "quantity": 2 } ] } }, "personalized": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "condition": [ { "sku": "com.xsolla.year_1_season_pass" } ], "attribute_conditions": [ { "attribute": "account_status", "type": "string", "operator": "eq", "value": "golden", "can_be_missing": false } ], "bonus": [ { "sku": "com.xsolla.mp_credits", "quantity": 50000 } ] } }, "with price conditions": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "condition": [ { "sku": "com.xsolla.elven_boots_2" }, { "sku": "com.xsolla.elven_knife_2" } ], "bonus": [ { "sku": "com.xsolla.elven_sword_2", "quantity": 1 }, { "sku": "com.xsolla.elven_shield_2", "quantity": 2 }, { "sku": "com.xsolla.elven_gloves_2", "quantity": 2 } ], "price_conditions": [ { "operator": "gt", "value": "10.0000" }, { "operator": "lt", "value": "20.0000" } ] } }, "with excluded promotions": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Bonus", "de-DE": "Neujahrsbonus" }, "condition": [ { "sku": "com.xsolla.year_1_season_pass" } ], "bonus": [ { "sku": "com.xsolla.mp_credits", "quantity": 50000 } ], "excluded_promotions": [ 12, 789 ] } } } } } }, "Promotions_unique_catalog_offer-create": { "content": { "application/json": { "schema": { "type": "object", "required": [ "external_id", "name" ], "properties": { "external_id": { "$ref": "#/components/schemas/Promotions_coupon-external_id" }, "date_start": { "$ref": "#/components/schemas/Promotions_coupon_date_start" }, "date_end": { "$ref": "#/components/schemas/Promotions_coupon_date_end" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "items": { "type": "array", "$ref": "#/components/schemas/Promotions_unique_catalog_offer_items" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" } } }, "examples": { "simple": { "value": { "external_id": "offer_external_id", "date_start": "2020-04-15T18:16:00+05:00", "date_end": "2020-04-25T18:16:00+05:00", "name": { "en-US": "New Year Offer", "de-DE": "Neujahrsangebot" }, "items": [ "elven_sword", "elven_boots" ] } }, "limited": { "value": { "external_id": "offer_external_id", "date_start": "2020-04-15T18:16:00+05:00", "date_end": "2020-04-25T18:16:00+05:00", "name": { "en-US": "New Year Offer", "de-DE": "Neujahrsangebot" }, "items": [ "elven_sword", "elven_boots" ], "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1 } } } } } }, "Promotions_unique_catalog_offer-update": { "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "promotion_periods": { "$ref": "#/components/schemas/promotion_periods" }, "name": { "$ref": "#/components/schemas/Promotions_coupon_name" }, "items": { "$ref": "#/components/schemas/Promotions_unique_catalog_offer_items" }, "redeem_total_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_total_limit" }, "redeem_user_limit": { "$ref": "#/components/schemas/Promotions_coupon-redeem_user_limit" }, "redeem_code_limit": { "$ref": "#/components/schemas/Promotions_redeem_code_limit" } } }, "examples": { "simple": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" }, { "date_from": "2020-05-15T18:16:00+05:00", "date_until": "2020-05-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Offer", "de-DE": "Neujahrsangebot" }, "items": [ "elven_sword", "elven_boots" ] } }, "limited": { "value": { "promotion_periods": [ { "date_from": "2020-04-15T18:16:00+05:00", "date_until": "2020-04-25T18:16:00+05:00" } ], "name": { "en-US": "New Year Offer", "de-DE": "Neujahrsangebot" }, "items": [ "elven_sword", "elven_boots" ], "redeem_total_limit": 100, "redeem_user_limit": 1, "redeem_code_limit": 1 } } } } } }, "personalized-catalog_create-update-body": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-attribute_personalized-catalog-body-required" }, "example": { "name": "Ork race armor rule", "is_enabled": true, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "ork", "type": "string", "can_be_missing": false } ], "items": [ { "item_id": 1 } ], "is_satisfied_for_unauth": false } } } }, "reset-user-limits": { "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "$ref": "#/components/schemas/User-limit_user" } } }, "example": { "user": { "user_external_id": "d342dad2-9d59-11e9-a384-42010aa8003f" } } } } }, "reset-user-limits-flexible": { "content": { "application/json": { "schema": { "type": "object", "required": [ "user" ], "properties": { "user": { "$ref": "#/components/schemas/User-limit_user_flexible" } } }, "example": { "user": { "user_external_id": "d342dad2-9d59-11e9-a384-42010aa8003f" } } } } }, "update-user-limits-flexible": { "content": { "application/json": { "schema": { "type": "object", "required": [ "user", "available" ], "properties": { "user": { "$ref": "#/components/schemas/User-limit_user" }, "available": { "$ref": "#/components/schemas/User-limit_available_flexible" } } }, "example": { "user": { "user_external_id": "d342dad2-9d59-11e9-a384-42010aa8003f" }, "available": 0 } } } }, "update-user-limits-strict": { "content": { "application/json": { "schema": { "type": "object", "required": [ "user", "available" ], "properties": { "user": { "$ref": "#/components/schemas/User-limit_user" }, "available": { "$ref": "#/components/schemas/User-limit_available" } } }, "example": { "user": { "user_external_id": "d342dad2-9d59-11e9-a384-42010aa8003f" }, "available": 1 } } } }, "create-value-point": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/admin_value_points-create" }, "examples": { "default": { "summary": "Value point for reward chain", "value": { "sku": "com.xsolla.reward_vp_1", "name": { "en": "Reward VP 1" }, "is_enabled": true, "description": { "en": "Value points for reward system." }, "long_description": { "en": "Value points given to users to get new rewards in a reward chain." }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 1 } }, "clan": { "summary": "Value point for clan reward chain", "value": { "sku": "com.xsolla.clan_value_point_1", "name": { "en": "Clan Reward VP 1" }, "is_enabled": true, "description": { "en": "Value points for clan reward system." }, "long_description": { "en": "Value points given to clans to get new rewards in a reward chain." }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "media_list": [], "order": 3, "is_clan": true } } } } } }, "set-item-value-point-reward": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/item-value-point-reward-set" }, "example": [ { "sku": "com.xsolla.booster_1", "amount": 100 }, { "sku": "com.xsolla.booster_mega", "amount": 200 } ] } } }, "set-item-value-point-reward-for-patch": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/item-value-point-reward-set-for-patch" }, "example": [ { "sku": "booster_1", "amount": 100 }, { "sku": "booster_mega", "amount": 0 } ] } } }, "create-reward-chain": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/create-reward-chain-model" }, { "$ref": "#/components/schemas/create-clan-reward-chain-model" } ] }, "examples": { "default": { "summary": "Reward chain example", "value": { "name": { "en": "Reward chain" }, "description": { "en": "Reward chain description." }, "long_description": { "en": "累充奖励链详细描述。" }, "is_enabled": true, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "periods": [ { "date_from": "2026-01-01T01:00:00+05:00", "date_until": "2026-01-31T23:59:59+05:00" }, { "date_from": "2026-02-01T01:00:00+05:00", "date_until": "2026-02-28T23:59:59+05:00" } ], "value_point": { "sku": "com.xsolla.value_point_1" }, "steps": [ { "name": { "en": "First step of the reward chain" }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_1", "quantity": 5 }, { "sku": "com.xsolla.item_2", "quantity": 1 } ], "price": { "amount": 10 } }, { "name": { "en": "Second step of the reward chain" }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_3", "quantity": 5 }, { "sku": "com.xsolla.item_4", "quantity": 1 } ], "price": { "amount": 15 } } ], "recurrent_schedule": { "interval_type": "weekly", "day_of_week": 1, "time": "01:00:00+08:00" }, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "ork", "type": "string", "can_be_missing": false } ], "is_always_visible": true, "is_reset_after_end": true } }, "clan": { "summary": "Clan reward chain example", "value": { "name": { "en": "Clan reward chain" }, "description": { "en": "Clan reward chain description." }, "long_description": { "en": "Clan reward chain long description." }, "is_enabled": true, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "periods": [ { "date_from": "2026-01-01T01:00:00+05:00", "date_until": "2026-01-31T23:59:59+05:00" }, { "date_from": "2026-02-01T01:00:00+05:00", "date_until": "2026-02-28T23:59:59+05:00" } ], "value_point": { "sku": "com.xsolla.clan_value_point_1" }, "steps": [ { "name": { "en": "First step of the reward chain" }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_1", "quantity": 5 }, { "sku": "com.xsolla.item_2", "quantity": 1 } ], "price": { "amount": 10 } }, { "name": { "en": "Second step of the reward chain" }, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_3", "quantity": 5 }, { "sku": "com.xsolla.item_4", "quantity": 1 } ], "price": { "amount": 15 } } ], "recurrent_schedule": { "interval_type": "weekly", "day_of_week": 1, "time": "01:00:00+08:00" }, "popup_header": { "en": "How to unlock rewards" }, "popup_instruction": { "en": "You must be a clan member to get clan rewards. You join a clan when a clan member invites you to the clan, and you accept the invite. You can also create your own clan." }, "popup_image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "clan_type": "guild" } } } } } }, "update-reward-chain": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/update-reward-chain-model" }, { "$ref": "#/components/schemas/update-clan-reward-chain-model" } ] }, "examples": { "default": { "summary": "Reward chain example", "value": { "name": { "en": "Reward chain" }, "description": { "en": "Reward chain description." }, "long_description": { "en": "累充奖励链详细描述。" }, "is_enabled": true, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "periods": [ { "date_from": "2026-01-01T01:00:00+05:00", "date_until": "2026-01-31T23:59:59+05:00" }, { "date_from": "2026-02-01T01:00:00+05:00", "date_until": "2026-02-28T23:59:59+05:00" } ], "steps": [ { "name": { "en": "First step of the reward chain" }, "step_id": 1, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_1", "quantity": 5 }, { "sku": "com.xsolla.item_2", "quantity": 1 } ], "price": { "amount": 10 } }, { "name": { "en": "Second step of the reward chain" }, "step_id": 2, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_3", "quantity": 5 }, { "sku": "com.xsolla.item_4", "quantity": 1 } ], "price": { "amount": 15 } } ], "recurrent_schedule": { "interval_type": "weekly", "day_of_week": 1, "time": "01:00:00+08:00" }, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "ork", "type": "string", "can_be_missing": false } ], "is_always_visible": true, "is_reset_after_end": true } }, "clan": { "summary": "Clan reward chain example", "value": { "name": { "en": "Clan reward chain" }, "description": { "en": "Clan reward chain description." }, "long_description": { "en": "Clan reward chain long description." }, "is_enabled": true, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "order": 1, "periods": [ { "date_from": "2026-01-01T01:00:00+05:00", "date_until": "2026-01-31T23:59:59+05:00" }, { "date_from": "2026-02-01T01:00:00+05:00", "date_until": "2026-02-28T23:59:59+05:00" } ], "steps": [ { "name": { "en": "First step of the reward chain" }, "step_id": 1, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_1", "quantity": 5 }, { "sku": "com.xsolla.item_2", "quantity": 1 } ], "price": { "amount": 10 } }, { "name": { "en": "Second step of the reward chain" }, "step_id": 2, "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "reward": [ { "sku": "com.xsolla.item_3", "quantity": 5 }, { "sku": "com.xsolla.item_4", "quantity": 1 } ], "price": { "amount": 15 } } ], "recurrent_schedule": { "interval_type": "weekly", "day_of_week": 1, "time": "01:00:00+08:00" }, "popup_header": { "en": "How to unlock rewards" }, "popup_instruction": { "en": "You should be a clan member to get clan rewards. You join a clan when a clan member invited you to the clan, and you accepted the invite. You can create your own clan." }, "popup_image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png", "clan_type": "guild" } } } } } }, "create-daily-chain": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/create-calendar-hard-daily-chain-model" }, { "$ref": "#/components/schemas/create-rolling-skippable-daily-chain-model" }, { "$ref": "#/components/schemas/create-rolling-unskippable-daily-chain-model" } ] }, "examples": { "calendar_hard": { "summary": "Daily reward with `calendar_hard` type", "value": { "name": { "en": "New daily reward", "ru": "Новая ежедневная награда" }, "description": { "en": "New daily reward short description" }, "order": 4, "date_start": "2023-04-15T18:16:00+05:00", "is_enabled": true, "steps": [ { "step_number": 1, "items": [ { "sku": "vg_enabled_shown_in_store_1", "quantity": 2 } ] }, { "step_number": 2, "items": [ { "sku": "bundle_enabled_shown_in_store_with_2_enabled_shown_in_store_vg", "quantity": 2 } ] }, { "step_number": 3, "items": [ { "sku": "vcp_enabled_shown_in_store_1_of_10_vc_enabled_shown_in_store_1", "quantity": 2 } ] }, { "step_number": 4, "items": [ { "sku": "vg_enabled_shown_in_store_1", "quantity": 1 } ] }, { "step_number": 5, "items": [ { "sku": "bundle_enabled_shown_in_store_with_2_enabled_shown_in_store_vg", "quantity": 1 } ] }, { "step_number": 6, "items": [ { "sku": "vcp_enabled_shown_in_store_1_of_10_vc_enabled_shown_in_store_1", "quantity": 1 } ] } ], "type": "calendar_hard" } }, "rolling_skippable": { "summary": "Daily reward with `rolling_skippable` type", "value": { "name": { "en": "New skippable login reward" }, "description": { "en": "New skippable login reward short description" }, "order": 1, "date_start": "2023-05-01T10:00:00+05:00", "date_end": "2023-05-31T10:00:00+05:00", "is_enabled": true, "is_recurrent": true, "steps": [ { "step_number": 1, "items": [ { "sku": "monday_reward_item_one", "quantity": 1 } ] }, { "step_number": 2, "items": [ { "sku": "tuesday_reward_item_two", "quantity": 1 } ] }, { "step_number": 3, "items": [ { "sku": "wednesday_reward_item_three", "quantity": 1 } ] }, { "step_number": 4, "items": [ { "sku": "thursday_reward_item_four", "quantity": 1 } ] }, { "step_number": 5, "items": [ { "sku": "friday_reward_item_five", "quantity": 1 } ] }, { "step_number": 6, "items": [ { "sku": "saturday_reward_item_six", "quantity": 1 } ] }, { "step_number": 7, "items": [ { "sku": "sunday_reward_item_seven", "quantity": 1 } ] } ], "type": "rolling_skippable" } }, "rolling_unskippable": { "summary": "Daily reward with `rolling_unskippable` type", "value": { "name": { "en": "New unskippable login reward" }, "description": { "en": "New unskippable login reward short description" }, "order": 2, "date_start": "2023-06-01T10:00:00+05:00", "date_end": "2023-06-30T10:00:00+05:00", "is_enabled": true, "is_recurrent": false, "steps": [ { "step_number": 1, "items": [ { "sku": "monday_reward_item_one", "quantity": 1 } ] }, { "step_number": 2, "items": [ { "sku": "tuesday_reward_item_two", "quantity": 1 } ] }, { "step_number": 3, "items": [ { "sku": "wednesday_reward_item_three", "quantity": 1 } ] }, { "step_number": 4, "items": [ { "sku": "thursday_reward_item_four", "quantity": 1 } ] }, { "step_number": 5, "items": [ { "sku": "friday_reward_item_five", "quantity": 1 } ] } ], "type": "rolling_unskippable" } } } } } }, "update-daily-chain": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/update-calendar-hard-daily-chain-model" }, { "$ref": "#/components/schemas/update-rolling-skippable-daily-chain-model" }, { "$ref": "#/components/schemas/update-rolling-unskippable-daily-chain-model" } ] }, "examples": { "calendar_hard": { "summary": "Daily reward with `calendar_hard` type", "value": { "name": { "en": "Updated daily reward", "ru": "Обновленная ежедневная награда" }, "description": { "en": "Updated daily reward description" }, "order": 4, "date_start": "2023-04-15T18:16:00+05:00", "is_enabled": true, "steps": [ { "step_number": 1, "items": [ { "sku": "vg_enabled_shown_in_store_1", "quantity": 1 } ] }, { "step_number": 2, "items": [ { "sku": "vg_enabled_shown_in_store_2", "quantity": 1 } ] }, { "step_id": 10, "step_number": 3, "items": [ { "sku": "vg_not_shown_in_store", "quantity": 1 } ] }, { "step_id": 8, "step_number": 4, "items": [ { "sku": "bundle_enabled_shown_in_store_with_2_enabled_shown_in_store_vg", "quantity": 1 } ] }, { "step_number": 5, "items": [ { "sku": "vcp_enabled_shown_in_store_1_of_10_vc_enabled_shown_in_store_1", "quantity": 1 } ] } ], "type": "calendar_hard" } }, "rolling_skippable": { "summary": "Daily reward with `rolling_skippable` type", "value": { "name": { "en": "Updated login reward" }, "description": { "en": "Updated login reward description" }, "order": 4, "date_start": "2023-08-01T10:00:00+05:00", "date_end": "2023-08-31T10:00:00+05:00", "is_enabled": true, "steps": [ { "step_number": 1, "items": [ { "sku": "monday_reward_item_one", "quantity": 1 } ] }, { "step_number": 2, "items": [ { "sku": "tuesday_reward_item_two", "quantity": 1 } ] }, { "step_number": 3, "items": [ { "sku": "wednesday_reward_item_three", "quantity": 1 } ] }, { "step_number": 4, "items": [ { "sku": "thursday_reward_item_four", "quantity": 1 } ] }, { "step_number": 5, "items": [ { "sku": "friday_reward_item_five", "quantity": 1 } ] }, { "step_number": 6, "items": [ { "sku": "saturday_reward_item_six", "quantity": 1 } ] }, { "step_number": 7, "items": [ { "sku": "sunday_reward_item_seven", "quantity": 1 } ] } ], "type": "rolling_skippable" } }, "rolling_unskippable": { "summary": "Daily reward with `rolling_unskippable` type", "value": { "name": { "en": "Updated unskippable login reward" }, "description": { "en": "Updated unskippable login reward description" }, "order": 2, "date_start": "2023-09-01T10:00:00+05:00", "date_end": "2023-09-30T10:00:00+05:00", "is_enabled": true, "steps": [ { "step_number": 1, "items": [ { "sku": "monday_reward_item_one", "quantity": 1 } ] }, { "step_number": 2, "items": [ { "sku": "tuesday_reward_item_two", "quantity": 1 } ] }, { "step_number": 3, "items": [ { "sku": "wednesday_reward_item_three", "quantity": 1 } ] }, { "step_number": 4, "items": [ { "sku": "thursday_reward_item_four", "quantity": 1 } ] }, { "step_number": 5, "items": [ { "sku": "friday_reward_item_five", "quantity": 1 } ] } ], "type": "rolling_unskippable" } } } } } }, "create-offer-chain": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-offer-chain-model" }, "examples": { "default": { "summary": "Non-personalized offer chain example", "value": { "name": { "en": "New offer chain", "ru": "Новая цепочка предложений", "de": "Neue Angebotskette", "fr": "Nouvelle chaîne d'offres", "it": "Nuova catena di offerte" }, "description": { "en": "A short description of a regular offer chain", "ru": "Краткое описание обычной цепочки предложений", "de": "Eine kurze Beschreibung einer regulären Angebotskette", "fr": "Une brève description d'une chaîne d'offres régulière", "it": "Una breve descrizione di una catena di offerte regolare" }, "order": 4, "date_start": "2023-04-15T18:16:00+05:00", "date_end": null, "recurrent_schedule": null, "is_enabled": true, "steps": [ { "step_number": 1, "is_free": false, "items": [ { "sku": "chain_step_1_paid_bundle_sku", "quantity": 2 } ] }, { "step_number": 2, "is_free": true, "items": [ { "sku": "chain_step_2_free_virtual_good_sku", "quantity": 1 } ] }, { "step_number": 3, "is_free": false, "items": [ { "sku": "chain_step_3_paid_virtual_currency_package_sku", "quantity": 5 } ] }, { "step_number": 4, "is_free": true, "items": [ { "sku": "chain_step_4_free_bundle_sku", "quantity": 1 } ] } ], "is_always_visible": true } }, "recurrent": { "summary": "Recurrent offer chain example", "value": { "name": { "en": "New recurrent offer chain", "ru": "Новая рекуррентная цепочка предложений", "de": "Neue wiederkehrende Angebotskette", "fr": "Nouvelle chaîne d'offres récurrente", "it": "Nuova catena di offerte ricorrente" }, "description": { "en": "A recurring offer chain that resets weekly on Wednesdays at 07:00 AM GMT+3", "ru": "Рекуррентная цепочка предложений, которая сбрасывается еженедельно по средам в 07:00 по GMT+3", "de": "Eine wiederkehrende Angebotskette, die wöchentlich mittwochs um 07:00 Uhr GMT+3 zurückgesetzt wird", "fr": "Une chaîne d'offres récurrente qui se réinitialise chaque semaine le mercredi à 07h00 GMT+3", "it": "Una catena di offerte ricorrente che si resetta settimanalmente il mercoledì alle 07:00 GMT+3" }, "order": 1, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "is_enabled": false, "recurrent_schedule": { "interval_type": "weekly", "day_of_week": 3, "time": "07:00:00+03:00" }, "steps": [ { "step_number": 1, "is_free": false, "items": [ { "sku": "chain_step_1_paid_bundle_sku", "quantity": 2 } ] }, { "step_number": 2, "is_free": true, "items": [ { "sku": "chain_step_2_free_virtual_good_sku", "quantity": 3 } ] } ], "is_always_visible": true } }, "personalized-default": { "summary": "Offer chain displayed when no personalized offer chains are found example", "value": { "name": { "en": "New personalized default offer chain", "ru": "Новая персонализированная цепочка предложений по умолчанию", "de": "Neue personalisierte Standard-Angebotskette", "fr": "Nouvelle chaîne d'offres personnalisée par défaut", "it": "Nuova catena di offerte personalizzata predefinita" }, "description": { "en": "Default personalized offer chain for users that do not meet the conditions of other personalized chains", "ru": "Персонализированная цепочка по умолчанию для пользователей, не подходящих под условия других персонализированных цепочек", "de": "Standard-personalisierte Angebotskette für Benutzer, die die Bedingungen anderer personalisierter Ketten nicht erfüllen", "fr": "Chaîne d'offres personnalisée par défaut pour les utilisateurs qui ne répondent pas aux conditions des autres chaînes personnalisées", "it": "Catena di offerte personalizzata predefinita per gli utenti che non soddisfano le condizioni di altre catene personalizzate" }, "order": 4, "date_start": "2023-04-15T18:16:00+05:00", "date_end": null, "recurrent_schedule": null, "is_enabled": true, "steps": [ { "step_number": 1, "is_free": false, "items": [ { "sku": "chain_x_step_1_item_default", "quantity": 1 } ] }, { "step_number": 2, "is_free": false, "items": [ { "sku": "chain_x_step_2_item_default", "quantity": 2 } ] }, { "step_number": 3, "is_free": true, "items": [ { "sku": "chain_x_step_3_free_item_default", "quantity": 1 } ] } ], "is_always_visible": false } }, "personalized-with-conditions": { "summary": "Personalized offer chain with user attribute conditions example", "value": { "name": { "en": "New personalized offer chain", "ru": "Новая персонализированная цепочка предложений", "de": "Neue personalisierte Angebotskette", "fr": "Nouvelle chaîne d'offres personnalisée", "it": "Nuova catena di offerte personalizzata" }, "description": { "en": "Personalized offer chain with user attribute conditions - for level 10 and above elves who reached level 10 no later than 2026-01-01 00:00:00, inclusive", "ru": "Персонализированная цепочка предложений с условиями по атрибутам пользователя - для эльфов уровня 10 и выше, достигших 10 уровня не позднее 2026-01-01 00:00:00 включительно", "de": "Personalisierte Angebotskette mit Benutzerattributbedingungen - für Elfen der Stufe 10 und höher, die Stufe 10 spätestens am 2026-01-01 00:00:00 erreicht haben, einschließlich", "fr": "Chaîne d'offres personnalisée avec des conditions d'attribut utilisateur - pour les elfes de niveau 10 et plus qui ont atteint le niveau 10 au plus tard le 2026-01-01 00:00:00, inclus", "it": "Catena di offerte personalizzata con condizioni di attributo utente - per elfi di livello 10 e superiore che hanno raggiunto il livello 10 non più tardi del 2026-01-01 00:00:00, inclusi" }, "order": 4, "date_start": "2023-04-15T18:16:00+05:00", "date_end": null, "recurrent_schedule": null, "is_enabled": true, "steps": [ { "step_number": 1, "is_free": false, "items": [ { "sku": "chain_x_step_1_item_for_elves_level_10_and_above", "quantity": 1 } ] }, { "step_number": 2, "is_free": false, "items": [ { "sku": "chain_x_step_2_item_for_elves_level_10_and_above", "quantity": 2 } ] }, { "step_number": 3, "is_free": true, "items": [ { "sku": "chain_x_step_3_free_item_for_elves_level_10_and_above", "quantity": 1 } ] } ], "is_always_visible": false, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "elf", "type": "string", "can_be_missing": false }, { "attribute": "level", "operator": "ge", "value": "10", "type": "number", "can_be_missing": false }, { "attribute": "10_level_up_date", "operator": "le", "value": "2026-01-01T00:00:00", "type": "date", "can_be_missing": false } ] } } } } } }, "update-offer-chain": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/modify-offer-chain-model" }, "examples": { "default": { "summary": "Default example", "value": { "name": { "en": "Updated offer chain", "ru": "Обновляемая цепочка предложений", "de": "Aktualisierte Angebotskette", "fr": "Chaîne d'offres mise à jour", "it": "Catena di offerte aggiornata" }, "description": { "en": "A short description of a regular offer chain", "ru": "Краткое описание обычной цепочки предложений", "de": "Eine kurze Beschreibung einer regulären Angebotskette", "fr": "Une brève description d'une chaîne d'offres régulière", "it": "Una breve descrizione di una catena di offerte regolare" }, "order": 4, "date_start": "2023-04-15T18:16:00+05:00", "date_end": null, "recurrent_schedule": null, "is_enabled": true, "steps": [ { "step_id": 10, "step_number": 1, "is_free": false, "items": [ { "sku": "chain_step_1_paid_bundle_sku", "quantity": 2 } ] }, { "step_number": 2, "is_free": true, "items": [ { "sku": "chain_step_2_free_virtual_good_sku", "quantity": 1 } ] }, { "step_number": 3, "is_free": false, "items": [ { "sku": "chain_step_3_paid_virtual_currency_package_sku", "quantity": 5 } ] }, { "step_id": 9, "step_number": 4, "is_free": true, "items": [ { "sku": "chain_step_4_free_bundle_sku", "quantity": 1 } ] } ], "is_always_visible": true } }, "recurrent": { "summary": "Recurrent offer chain example", "value": { "id": 1, "name": { "en": "Updated recurrent offer chain", "ru": "Обновляемая рекуррентная цепочка предложений", "de": "Aktualisierte wiederkehrende Angebotskette", "fr": "Chaîne d'offres récurrente mise à jour", "it": "Catena di offerte ricorrente aggiornata" }, "description": { "en": "Updated offer chain that becomes recurrent and resets monthly on the 2nd day at 03:00 AM GMT+8", "ru": "Обновляемая цепочка предложений, которая становится рекуррентной и сбрасывается ежемесячно во 2-й день в 03:00 по GMT+8", "de": "Aktualisierte Angebotskette, die wiederkehrend wird und monatlich am 2. Tag um 03:00 Uhr GMT+8 zurückgesetzt wird", "fr": "Chaîne d'offres mise à jour qui devient récurrente et se réinitialise mensuellement le 2e jour à 03h00 GMT+8", "it": "Catena di offerte aggiornata che diventa ricorrente e si resetta mensilmente il 2° giorno alle 03:00 GMT+8" }, "order": 4, "date_start": "2023-04-15T17:16:00+05:00", "date_end": "2025-04-25T19:16:00+05:00", "is_enabled": true, "recurrent_schedule": { "interval_type": "monthly", "day_of_month": 2, "time": "03:00:00+08:00" }, "steps": [ { "step_number": 1, "is_free": false, "items": [ { "sku": "chain_bundle_sku", "quantity": 6 } ] }, { "step_number": 1, "is_free": true, "items": [ { "sku": "chain_bundle_sku", "quantity": 2 } ] } ] } }, "personalized-default": { "summary": "Personalized default offer chain example", "value": { "name": { "en": "New personalized default offer chain", "ru": "Новая персонализированная цепочка предложений по умолчанию", "de": "Neue personalisierte Standard-Angebotskette", "fr": "Nouvelle chaîne d'offres personnalisée par défaut", "it": "Nuova catena di offerte personalizzata predefinita" }, "description": { "en": "Default personalized offer chain for users that do not meet the conditions of other personalized chains", "ru": "Персонализированная цепочка по умолчанию для пользователей, не подходящих под условия других персонализированных цепочек", "de": "Standard-personalisierte Angebotskette für Benutzer, die die Bedingungen anderer personalisierter Ketten nicht erfüllen", "fr": "Chaîne d'offres personnalisée par défaut pour les utilisateurs qui ne répondent pas aux conditions des autres chaînes personnalisées", "it": "Catena di offerte personalizzata predefinita per gli utenti che non soddisfano le condizioni di altre catene personalizzate" }, "order": 4, "date_start": "2023-04-15T18:16:00+05:00", "date_end": null, "recurrent_schedule": null, "is_enabled": true, "steps": [ { "step_id": 10, "step_number": 1, "is_free": false, "items": [ { "sku": "chain_x_step_1_item_default", "quantity": 1 } ] }, { "step_number": 2, "is_free": false, "items": [ { "sku": "chain_x_step_2_item_default", "quantity": 2 } ] }, { "step_id": 9, "step_number": 3, "is_free": true, "items": [ { "sku": "chain_x_step_3_free_item_default", "quantity": 1 } ] } ], "is_always_visible": false } }, "personalized-with-conditions": { "summary": "Personalized offer chain with user attribute conditions example", "value": { "name": { "en": "New personalized offer chain", "ru": "Новая персонализированная цепочка предложений", "de": "Neue personalisierte Angebotskette", "fr": "Nouvelle chaîne d'offres personnalisée", "it": "Nuova catena di offerte personalizzata" }, "description": { "en": "Personalized offer chain with user attribute conditions - for level 10 and above elves who reached level 10 no later than 2026-01-01 00:00:00, inclusive", "ru": "Персонализированная цепочка предложений с условиями по атрибутам пользователя - для эльфов уровня 10 и выше, достигших 10 уровня не позднее 2026-01-01 00:00:00 включительно", "de": "Personalisierte Angebotskette mit Benutzerattributbedingungen - für Elfen der Stufe 10 und höher, die Stufe 10 spätestens am 2026-01-01 00:00:00 erreicht haben, einschließlich", "fr": "Chaîne d'offres personnalisée avec des conditions d'attribut utilisateur - pour les elfes de niveau 10 et plus qui ont atteint le niveau 10 au plus tard le 2026-01-01 00:00:00, inclus", "it": "Catena di offerte personalizzata con condizioni di attributo utente - per elfi di livello 10 e superiore che hanno raggiunto il livello 10 non più tardi del 2026-01-01 00:00:00, inclusi" }, "order": 4, "date_start": "2023-04-15T18:16:00+05:00", "date_end": null, "recurrent_schedule": null, "is_enabled": true, "steps": [ { "step_id": 10, "step_number": 1, "is_free": false, "items": [ { "sku": "chain_x_step_1_item_for_elves_level_10_and_above", "quantity": 1 } ] }, { "step_id": 8, "step_number": 2, "is_free": false, "items": [ { "sku": "chain_x_step_2_item_for_elves_level_10_and_above", "quantity": 2 } ] }, { "step_number": 3, "is_free": true, "items": [ { "sku": "chain_x_step_3_free_item_for_elves_level_10_and_above", "quantity": 1 } ] } ], "is_always_visible": false, "attribute_conditions": [ { "attribute": "race", "operator": "eq", "value": "elf", "type": "string", "can_be_missing": false }, { "attribute": "level", "operator": "ge", "value": "10", "type": "number", "can_be_missing": false }, { "attribute": "10_level_up_date", "operator": "le", "value": "2026-01-01T00:00:00", "type": "date", "can_be_missing": false } ] } } } } } }, "update-upsell": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Upsell-model" }, { "$ref": "#/components/schemas/Upsell-model-not-fixed-list" } ] }, "examples": { "fixed_list": { "summary": "Example of upsell with fixed list of items", "value": { "is_enabled": true, "type": "fixed_list", "items": [ "game_sku_1", "game_sku_2", "game_sku_3" ] } }, "special_type_promotions": { "summary": "Example of upsell with promotion items only", "value": { "is_enabled": true, "type": "only_promotions", "items": [] } }, "special_type_most_sellable": { "summary": "Example of upsell with most sellable items for last 30 days", "value": { "is_enabled": true, "type": "most_sellable", "items": [] } } } } } }, "create-upsell": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Upsell-model" }, { "$ref": "#/components/schemas/Upsell-model-not-fixed-list" } ] }, "examples": { "fixed_list": { "summary": "Example of upsell with fixed list of items", "value": { "is_enabled": true, "type": "fixed_list", "items": [ "game_sku_1", "game_sku_2", "game_sku_3" ] } }, "special_type_promotions": { "summary": "Example of upsell with promotion items only", "value": { "is_enabled": true, "type": "only_promotions", "items": [] } }, "special_type_most_sellable": { "summary": "Example of upsell with most sellable items for last 30 days", "value": { "is_enabled": true, "type": "most_sellable", "items": [] } } } } } } } }, "x-tagGroups": [ { "name": "促销活动", "tags": [ "promotions-overview", "promotions-common", "promotions-coupons", "promotions-promo-codes", "promotions-unique-catalog-offers", "promotions-discounts", "promotions-bonuses" ] }, { "name": "个性化", "tags": [ "personalized-catalog" ] }, { "name": "限制", "tags": [ "promotion-limits-overview", "user-limits-admin" ] }, { "name": "累充奖励链和累充积分", "tags": [ "reward-chain-value-points-overview", "reward-chain-value-points-admin", "reward-chain-client", "clan-reward-chain-client" ] }, { "name": "每日奖励链", "tags": [ "daily-chain-admin", "daily-chain-client" ] }, { "name": "优惠链", "tags": [ "offer-chains-overview", "offer-chain-admin", "offer-chain-client" ] }, { "name": "追加销售", "tags": [ "upsell-admin", "upsell-client" ] } ] }