跳转到内容

LiveOps运营API (2.0.0)

概述

LiveOps运营是一套工具包，可通过促销活动和个性化优惠持续提升玩家互动。

使用该API管理以下功能：

  • 促销活动 — 创建和管理优惠券、兑换码、折扣和买赠活动。
  • 个性化 — 指定商品目录的显示条件，并仅对特定授权用户应用促销活动。
  • 促销活动限制 — 限制用户可使用促销活动的次数，并为这些限制配置定时重置。
  • 累充奖励链和累充积分 — 配置与累充积分积累相关的奖励进度。
  • 每日奖励链 — 设置周期性每日奖励，鼓励玩家定期登录。
  • 优惠链 — 构建连续购买优惠，支持按链中完成步骤阶梯定价和免费奖励选项。
  • 追加销售 — 一种销售方式，向用户推荐购买具有额外价值的商品。

API调用

该API分为以下组：

  • Admin — 用于创建、更新、激活和删除活动及奖励链配置的调用。使用您的商户或项目凭据，通过基本访问身份认证进行身份认证。
  • Client — 用于代表已完成身份认证的终端用户获取可用促销活动、获取有效奖励链、核销代码并领取奖励的调用。通过用户JWT进行身份认证。

身份认证

API调用需要以用户身份或项目身份进行身份认证。使用的身份认证方案见各调用描述中的安全性部分。

使用用户JWT进行身份认证

当请求从浏览器、移动应用或游戏发送时，使用用户JWT身份认证。默认情况下，应用XsollaLoginUserJWT方案。有关如何创建令牌的详细信息，请参阅艾克索拉登录管理器API文档。

令牌通过Authorization请求头按以下格式传递：Authorization: Bearer <user_JWT>，其中<user_JWT>为用户令牌。该令牌用于识别用户，并授予其访问个性化数据的权限。

或者，您也可以使用用于打开支付UI的令牌。

基本HTTP身份认证

基本HTTP身份认证用于服务器到服务器交互，即API调用直接从您的服务器发送，而不是从用户的浏览器或移动应用发送。通常使用带有API密钥的HTTP Basic身份认证。

注：

API密钥属于机密信息，不得在客户端应用中存储或使用。

使用基本服务器侧身份认证时，所有API请求都必须包含以下请求头：

  • 对于basicAuth — Authorization: Basic <your_authorization_basic_key>，其中your_authorization_basic_key是以Base64编码的project_id:api_key对
  • 对于basicMerchantAuth — Authorization: Basic <your_authorization_basic_key>，其中your_authorization_basic_key是以Base64编码的merchant_id:api_key对

您可以在发布商帐户中找到参数值：

  • merchant_id显示在：
    • 公司设置 > 公司中。
    • 任意发布商帐户页面的浏览器地址栏URL中。URL格式为：https://publisher.xsolla.com/<merchant_id>。
  • project_id显示在：
    • 发布商帐户中项目名称旁边。
    • 发布商帐户中项目页面的浏览器地址栏URL中。URL格式为：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
  • api_key仅在创建时在发布商帐户中显示，必须在己侧安全存储。您可以在以下部分创建API密钥：
提示

如果所需的API调用不包含project_id路径参数，请使用对公司所有项目均有效的API密钥进行授权。

有关使用API密钥的更多信息，请参阅API参考。

支持访客访问的身份认证

AuthForCart身份认证方案用于购物车购买，支持两种模式：

  1. 使用用户JWT进行身份认证。 令牌通过Authorization请求头传递，格式如下：Authorization: Bearer <user_JWT>，其中<user_JWT>为用户令牌。该令牌用于识别用户，并授予其访问个性化数据的权限。或者，您也可以使用用于打开支付UI的令牌。

  2. 不带Authorization请求头的简化模式。 此模式仅适用于未完成身份认证的用户，且仅可用于游戏Key销售请求中不使用令牌，而必须包含以下请求头：

    • x-unauthorized-id，值为请求ID
    • x-user，值为使用Base64编码的用户电子邮件地址

核心实体结构

所有类型的商品（虚拟物品、捆绑包、虚拟货币和密钥）都使用类似的数据结构。了解基本结构有助于简化API使用，并帮助您更轻松地查阅文档。

注：

部分调用可能包含其他字段，但这些字段不会改变基本结构。

标识信息

  • merchant_id — 发布商帐户中的公司ID
  • project_id — 发布商帐户中的项目ID
  • sku — 商品SKU，在项目内唯一

商店显示

  • name — 商品名称
  • description — 商品描述
  • image_url — 图片URL
  • is_enabled — 商品可用性
  • is_show_in_store — 商品是否显示在商品目录中

有关在商品目录中管理商品可用性的更多信息，请参阅文档。

组织方式

  • type — 商品类型，例如虚拟物品（virtual_item）或捆绑包（bundle）
  • groups — 商品所属的组
  • order — 在商品目录中的显示顺序

销售条件

  • prices — 以真实货币或虚拟货币表示的价格
  • limits — 购买限制
  • periods — 可用时间段
  • regions — 区域限制

核心实体结构示例：

{
  "attributes": [],
  "bundle_type": "virtual_currency_package",
  "content": [
    {
      "description": {
        "en": "Main in-game currency"
      },
      "image_url": "https://.../image.png",
      "name": {
        "en": "Crystals",
        "de": "Kristalle"
      },
      "quantity": 500,
      "sku": "com.xsolla.crystal_2",
      "type": "virtual_currency"
    }
  ],
  "description": {
    "en": "Crystals x500"
  },
  "groups": [],
  "image_url": "https://.../image.png",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": true,
  "limits": {
    "per_item": null,
    "per_user": null,
    "recurrent_schedule": null
  },
  "long_description": null,
  "media_list": [],
  "name": {
    "en": "Medium crystal pack"
  },
  "order": 1,
  "periods": [
    {
      "date_from": null,
      "date_until": "2020-08-11T20:00:00+03:00"
    }
  ],
  "prices": [
    {
      "amount": 20,
      "country_iso": "US",
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "regions": [],
  "sku": "com.xsolla.crystal_pack_2",
  "type": "bundle",
  "vc_prices": []
}

基本购买流程

艾克索拉API可用于实现游戏内购商店逻辑，包括获取商品目录、管理购物车、创建订单以及跟踪订单状态。根据集成场景，API调用分为管理和商品目录子部分，使用不同的身份认证方案。

以下示例展示了从创建商品到完成购买的商店设置和运营基本流程。

创建商品和组（管理）

为您的商店创建商品目录，例如虚拟物品、捆绑包或虚拟货币。

API调用示例：

设置促销、奖励链和限制（管理）

配置用户拉新和赢利工具，例如折扣、赠品、每日奖励或优惠链。

API调用示例：

获取商品信息（客户端）

在您的应用程序中配置商品显示。

提示

请勿使用管理子部分中的API调用来构建用户商品目录。这些API调用存在速率限制，并不适用于用户流量。

API调用示例：

注：

默认情况下，商品目录API调用会返回请求时商店中当前可用的商品。如需获取尚未可用或已不再可用的商品，请在商品目录请求中包含参数"show_inactive_time_limited_items": 1。

销售商品

您可以使用以下方法销售商品：

  • 快速购买 — 多次销售同一SKU。
  • 购物车购买 — 用户可在同一订单中向购物车添加商品、移除商品并更新数量。

如果商品使用虚拟货币而非真实货币购买，请使用创建包含指定商品的订单 API调用。由于扣款会在执行API调用时处理，因此无需支付UI。

如需购买免费商品，请使用使用指定商品创建订单 API调用或使用免费购物车创建订单 API调用。无需支付UI — 订单会立即设置为done状态。

快速购买

使用客户端API调用使用指定商品创建订单。该调用会返回用于打开支付UI的令牌。

注：

用户只能在支付UI中查看折扣信息。不支持兑换码。

购物车购买

可以在客户端或服务器侧设置购物车并完成购买。

在客户端设置和购买购物车商品

您需要自行实现添加和移除商品的逻辑。在调用用于设置购物车的API之前，您无法获知哪些促销活动会应用于本次购买。这意味着您无法提前获知总费用以及添加的赠品的详细信息。

实现以下购物车逻辑：

  1. 玩家在购物车加购后，使用向购物车添加商品 API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。
  2. 根据用户操作更新购物车内容：
注：

如需获取购物车的当前状态，请使用“获取当前用户的购物车”API调用。
  1. 使用创建包含当前购物车中所有商品的订单 API调用。该调用返回订单ID和支付令牌。新创建的订单默认设置为new状态。

在服务器侧设置和购买购物车商品

这种设置方式可能需要更长的购物车设置时间，因为每次更改购物车都必须伴随API调用。

实现以下购物车逻辑：

  1. 玩家在购物车加购后，使用向购物车添加商品 API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。
  2. 使用创建包含当前购物车中所有商品的订单 API调用。该调用会返回订单ID和支付令牌。新创建的订单默认设置为new状态。

打开支付UI

使用返回的令牌在新窗口中打开支付UI。有关打开支付UI的其他方式，请参阅文档。

操作接口
在生产环境中打开。https://secure.xsolla.com/paystation4/?token={token}
在沙盒模式中打开。https://sandbox-secure.xsolla.com/paystation4/?token={token}
注：

请在开发和测试期间使用沙盒模式。测试购买不会对真实帐户扣款。您可以使用测试银行卡。

完成第一笔真实支付后，严格的沙盒支付策略将生效。沙盒模式下的支付仅对发布商帐户 > 公司设置 > 用户中指定的用户可用。

只有在与艾克索拉签署许可协议后，才能使用真实货币购买虚拟货币和商品。如需签署协议，请在发布商帐户中前往协议与税务 > 合同与协议，填写协议表单并等待确认。协议审核最多可能需要3个工作日。

如需启用或禁用沙盒模式，请在快速购买和购物车购买请求中更改sandbox参数的值。沙盒模式默认关闭。

可能的订单状态：

  • new — 订单已创建
  • paid — 已收到付款
  • done — 商品已交付
  • canceled — 订单已取消
  • expired — 订单已过期

使用以下任一方式跟踪订单状态：

分页

返回大量记录的API调用（例如构建商品目录时）会按页返回数据。分页是一种限制单个API响应中返回商品数量的机制，并允许您按顺序获取后续页面。

使用以下参数控制返回的商品数量：

  • limit — 每页商品数量
  • offset — 页面中第一个商品的索引（从0开始编号）
  • has_more — 指示是否还有下一页
  • total_items_count — 商品总数

请求示例：

GET /items?limit=20&offset=40

响应示例：

{
  "items": [...],
  "has_more": true,
  "total_items_count": 135
}

建议发送后续请求，直到响应返回has_more = false。

日期和时间格式

日期和时间值以ISO 8601格式传递。

支持以下内容：

  • UTC偏移量
  • 当商品显示没有时间限制时使用null值
  • 部分字段使用的Unix时间戳（以秒为单位）

格式：YYYY-MM-DDTHH:MM:SS±HH:MM

示例：2026-03-16T10:00:00+03:00

本地化

艾克索拉支持对商品名称、描述等面向用户的字段进行本地化。本地化值以对象形式传递，其中语言代码作为键。支持的完整语言列表，请参阅文档。

支持的字段

可为以下参数指定本地化内容：

  • name
  • description
  • long_description

区域格式

语言区域键可使用以下任一格式指定：

  • 两字母语言代码：en、ru
  • 五字母语言代码：en-US、ru-RU、de-DE

示例

两字母语言代码示例：

{
  "name": {
    "en": "Starter Pack",
    "ru": "Стартовый набор"
  }
}

五字母语言代码示例：

{
  "description": {
    "en-US": "Premium bundle",
    "de-DE": "Premium-Paket"
  }
}

错误响应格式

如果发生错误，API会返回HTTP状态和JSON响应正文。商店相关错误的完整列表，请参阅文档。

响应示例：

{
  "errorCode": 1102,
  "errorMessage": "Validation error",
  "statusCode": 422,
  "transactionId": "c9e1a..."
}
  • errorCode — 错误代码。
  • errorMessage — 简短的错误描述。
  • statusCode — HTTP响应状态。
  • transactionId — 请求ID。仅在部分情况下返回。
  • errorMessageExtended — 其他错误详情，例如请求参数。仅在某些情况下返回。

扩展响应示例：

{
  "errorCode": 7001,
  "errorMessage": "Chain not found",
  "errorMessageExtended": {
    "chain_id": "test_chain_id",
    "project_id": "test_project_id",
    "step_number": 2
  },
  "statusCode": 404
}

常见HTTP状态代码

  • 400 — 请求无效
  • 401 — 身份认证错误
  • 403 — 权限不足
  • 404 — 资源未找到
  • 422 — 验证错误
  • 429 — 超出速率限制

建议

  • 结合HTTP状态和响应正文一起处理。
  • 使用errorCode处理与应用程序逻辑相关的错误。
  • 分析错误时，使用transactionId更快定位请求。
下载 OpenAPI 描述
index.json
index.yaml
语言
服务器
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/zh/api/liveops/

概述

促销活动是用于吸引新用户并提升销售额的营销工具。您可以使用艾克索拉API配置以下促销活动：

  • 折扣 — 为所选商品提供降价优惠。
  • 赠品 — 用户购买时随订单获得的商品。
  • 优惠券 — 用户兑换后可获得一个或多个赠品的代码。
  • 兑换码 — 用户可通过此类代码获得赠品、特定商品折扣或整个购物车折扣。优惠券会在用户输入后兑换；与之不同，兑换码会在购买过程中（结算时）兑换。
  • 专属优惠 — 在商品目录中向已输入专属优惠代码的用户显示的隐藏商品。如果未输入代码，则不会显示这些商品。

配置折扣促销活动的示例流程：

  1. 使用虚拟物品和货币、捆绑包或游戏Key组的管理子部分中的调用创建商品。
  2. 使用为商品创建折扣促销活动调用创建促销活动。在items数组中传入所需的商品SKU。
  3. 设置促销活动有效期。为此，请调用为商品创建折扣促销活动或更新商品促销活动方法，并将promotion_periods字段作为对象数组传入，其中date_from定义有效期开始日期，date_until定义有效期结束日期。
  4. 使用更新商品促销活动调用激活促销活动。传入"is_enabled": true参数。
  5. 如需获取商品价格信息（包括折后价格），请调用通用 > 商品目录、虚拟物品和货币 > 商品目录和捆绑包 > 商品目录子部分中用于获取商品目录的客户端API方法。

促销活动配置示例

关于配置促销活动的详细信息，请参阅我们的文档：

通用API调用

您可以调用此子部分中的API方法，管理不同类型的促销活动。

操作

优惠券

调用此子部分中的API方法，配置和管理优惠券促销活动。

注：

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

操作

兑换码

调用此子部分中的API方法，配置和管理兑换码促销活动。

注：

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

操作

核销兑换码Client-side

请求

核销兑换码促销活动的兑换码。 核销兑换码后，用户将获得免费商品，和/或购物车或特定商品的价格将降低。

安全
AuthForCart
路径
project_idinteger必需

项目ID。您可以在发布商帐户的项目名称旁找到此参数；使用项目时，也可以在浏览器地址栏中找到此参数。URL格式如下：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

示例: 44056
正文application/json
coupon_codestring[ 1 .. 128 ] characters

兑换码的唯一代码。包含字母和数字。

默认值 "SUMMER2021"
示例: "SUMMER2021"
cartobject or null
cart.​idstring必需

购物车ID。

默认值 "current"
selected_unit_itemsobject

用户选择作为赠品的平台对应游戏Key。将收到的 bonus.item.sku作为键，将所选bonus.item.unit_items.sku作为其值。

selected_unit_items.​property name*string附加属性
curl -i -X POST \
  https://store.xsolla.com/api/v2/project/44056/promocode/redeem \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "coupon_code": "SUMMER2021",
    "cart": {
      "id": "current"
    },
    "selected_unit_items": {
      "game_1": "game_1_steam",
      "game_2": "game_2_playstation"
    }
  }'

响应

兑换码已成功核销。

正文application/json
cart_idstring

购物车ID。

示例: "cart_id"
priceobject or null

购物车价格。

示例: {"amount":"6150.0000000000000000","amount_without_discount":"6150.0000000000000000","currency":"USD"}
price.​amountstring
示例: "6150.0000000000000000"
price.​amount_without_discountstring
示例: "6150.0000000000000000"
price.​currencystring
示例: "USD"
is_freeboolean

该商品是否免费。

itemsArray of objects
示例: [{"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"}]}]
items[].​skustring
items[].​groupsArray of objects
items[].​groups[].​external_idstring
items[].​groups[].​namestring
items[].​namestring or null
items[].​typestring
items[].​descriptionstring
items[].​image_urlstring
items[].​quantityinteger
items[].​is_freeboolean

该商品是否免费。

items[].​promotionsArray of objects

应用于购物车中指定商品的促销活动。仅在以下情况下返回该数组：

  • 为某商品配置了折扣促销活动。

  • 应用了具有对所选商品提供折扣设置的兑换码。

如果未应用任何商品级促销活动，则返回空数组。

items[].​promotions[].​namestring
items[].​promotions[].​date_startstring or null(date-time)
items[].​promotions[].​date_endstring or null(date-time)
items[].​promotions[].​discountobject or null
items[].​promotions[].​discount.​percentstring or null
items[].​promotions[].​discount.​valuestring or null
items[].​promotions[].​bonusArray of objects
items[].​promotions[].​bonus[].​skustring
items[].​promotions[].​bonus[].​quantityinteger
items[].​promotions[].​bonus[].​typestring

赠品类型。

枚举"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
items[].​promotions[].​bonus[].​namestring

赠品名称。不适用于physical_good赠品类型。

items[].​promotions[].​bonus[].​image_urlstring

赠品图片URL。不适用于physical_good赠品类型。

items[].​promotions[].​bonus[].​bundle_typestring

赠品捆绑包商品类型。仅适用于bundle赠品类型。

枚举"standard""virtual_currency_package"
items[].​promotions[].​limitsobject
items[].​promotions[].​limits.​per_userobject
items[].​promotions[].​limits.​per_user.​availableinteger
items[].​promotions[].​limits.​per_user.​totalinteger
items[].​can_be_boughtboolean

如为true，则用户可以购买商品。

items[].​vp_rewardsArray of objects

累充积分商品奖励。

items[].​vp_rewards[].​item_idinteger

内部唯一商品ID。

items[].​vp_rewards[].​skustring

唯一累充积分ID。

items[].​vp_rewards[].​amountinteger

累充积分数量。

items[].​vp_rewards[].​namestring

累充积分名称。

items[].​vp_rewards[].​image_urlstring

图片URL。

items[].​vp_rewards[].​is_clanboolean

累充积分是否用于公会累充奖励链。

items[].​limitsobject or null

商品限制数。

items[].​limits.​per_userobject or null

单个用户的商品购买数量限制。

items[].​limits.​per_user.​totalinteger

单个用户可购买的最大商品数量。

示例: 5
items[].​limits.​per_user.​availableinteger

当前用户可购买的剩余商品数量。

示例: 3
items[].​limits.​per_user.​recurrent_schedule(object or null)
One of:

用户的商品限制循环刷新周期。

object or null
items[].​limits.​per_user.​limit_exceeded_visibilitystring

设定商品在达到购买限制后、下次限制重置前在商品目录中的可见性。

适用于在recurrent_schedule数组中配置了周期性重置数量限制的商品。

如果未配置重置限制，则达到购买限制后，无论limit_exceeded_visibility的值如何，该商品都不会显示在商品目录中。

可能值：

  • show — 达到购买限制后，商品目录检索API调用仍会返回该商品。在客户端侧 商品目录检索API调用中，达到限制后返回的商品会带有can_be_bought: false 标志。下一次重置日期 将在reset_next_date中返回。
  • hide — 达到购买限制后，在限制 重置之前，商品目录检索API调用不会返回该商品。
枚举"show""hide"
items[].​limits.​per_itemobject or null

单个商品的购买数量限制。

items[].​limits.​per_item.​totalinteger

所有用户可购买的最大商品数量。

示例: 5
items[].​limits.​per_item.​availableinteger

所有用户还可购买的剩余商品数量。

示例: 3
items[].​periodsArray of objects or null

商品销售期。

items[].​periods[].​date_fromstring(date-time)

指定商品开始可购的日期。

示例: "2020-08-11T10:00:00+03:00"
items[].​periods[].​date_untilstring or null(date-time)

指定商品停止可购的日期。可为null。

示例: "2020-08-11T20:00:00+03:00"
rewardsobject
rewards.​bonusArray of objects
rewards.​bonus[].​itemobject
rewards.​bonus[].​item.​skustring

唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。

示例: "game_01"
rewards.​bonus[].​item.​namestring

商品名称。

示例: "Game name"
rewards.​bonus[].​item.​typestring

商品类型。可能值：

  • virtual_good — 虚拟物品
  • virtual_currency — 虚拟货币
  • bundle — 捆绑包
  • unit — 游戏Key套餐

示例: "unit"
rewards.​bonus[].​item.​descriptionstring

Item description.

示例: "Game description"
rewards.​bonus[].​item.​image_urlstring

图片URL。

示例: "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png"
rewards.​bonus[].​item.​unit_itemsArray of objects

平台专属游戏Key数组。仅当商品类型为unit (bonus.item.type = 'unit')时使用。如果游戏Key套餐包含平台专属Key，用户可以选择其中一个作为赠品。

rewards.​bonus[].​item.​unit_items[].​skustring^[a-zA-Z0-9_\-.]*$

唯一的平台专属游戏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。

示例: "cool_game_steam"
rewards.​bonus[].​item.​unit_items[].​is_freeboolean
rewards.​bonus[].​item.​unit_items[].​typestring

表示该商品为游戏Key。

值"game_key"
rewards.​bonus[].​item.​unit_items[].​namestring

游戏名称。

示例: "Awesome Game"
rewards.​bonus[].​item.​unit_items[].​drm_namestring

DRM名称。

示例: "Steam"
rewards.​bonus[].​item.​unit_items[].​drm_skustring^[a-zA-Z0-9_\-.]*$

唯一DRM ID，用作后缀以表示平台专属游戏Key。允许使用以下字符：a-z、A-Z、0-9、句点（.）、连字符（-）、下划线（_）。

示例: "steam"
rewards.​bonus[].​quantitynumber

商品数量。

默认值 1
rewards.​discountobject or null

百分比折扣。 购物车价格将按照此百分比打折，然后四舍五入到小数点后两位。

rewards.​discount.​percentstring
示例: "10.00"
rewards.​discounted_itemsArray of objects or null

通过兑换码享受折扣的商品列表。

rewards.​discounted_items[].​skustring必需

商品SKU。

默认值 "elven_shield"
rewards.​discounted_items[].​discountobject必需
rewards.​discounted_items[].​discount.​percentstring必需

百分比折扣。

购物车商品价格将按照此百分比打折， 然后四舍五入到小数点后两位。

rewards.​is_selectableboolean

如果为true，则用户应在核销兑换码前选择赠品。

响应
application/json
{
  "cart_id": "cart_id",
  "is_free": false,
  "items": [
    { … },
    { … }
  ],
  "price": {
    "amount": "6150.0000000000000000",
    "amount_without_discount": "12300.0000000000000000",
    "currency": "USD"
  },
  "rewards": {
    "bonus": [ … ],
    "discount": { … },
    "discounted_items": [ … ],
    "is_selectable": false
  }
}

从购物车中移除兑换码Client-side

请求

从购物车中移除兑换码。 移除兑换码后，系统会重新计算购物车中所有商品的总价，且不再包含该兑换码提供的赠品和折扣。

安全
AuthForCart
路径
project_idinteger必需

项目ID。您可以在发布商帐户的项目名称旁找到此参数；使用项目时，也可以在浏览器地址栏中找到此参数。URL格式如下：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

示例: 44056
正文application/json
cartobject or null
cart.​idstring必需

购物车ID。

默认值 "current"
curl -i -X PUT \
  https://store.xsolla.com/api/v2/project/44056/promocode/remove \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cart": {
      "id": "current"
    }
  }'

响应

兑换码已成功取消。

正文application/json
cart_idstring

购物车ID。

示例: "cart_id"
priceobject or null

购物车价格。

示例: {"amount":"6150.0000000000000000","amount_without_discount":"6150.0000000000000000","currency":"USD"}
price.​amountstring
默认值 "50.0000000000000000"
示例: "6150.0000000000000000"
price.​amount_without_discountstring
默认值 "100.0000000000000000"
示例: "6150.0000000000000000"
price.​currencystring
默认值 "USD"
示例: "USD"
is_freeboolean

该商品是否免费。

itemsArray of objects
示例: [{"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"}]}]
items[].​skustring
items[].​groupsArray of objects
items[].​groups[].​external_idstring
items[].​groups[].​namestring
items[].​namestring or null
items[].​typestring
items[].​virtual_item_typestring

虚拟物品的类型。

可能值：

  • consumable — 使用后会从物品库中消失的商品（例如弹药）。
  • non_consumable — 可无限期保留在物品库中的商品。
  • non_renewing_subscription — 时效性商品，可表示在限定时间内对服务或内容的访问权限。"
枚举"consumable""non_consumable""non_renewing_subscription"
示例: "non-consumable"
items[].​virtual_pricesArray of arrays
items[].​descriptionstring
items[].​attributesArray of objects

与商品对应的属性及其值的列表。可用于商品目录筛选。

items[].​attributes[].​external_idstring[ 1 .. 255 ] characters^[a-zA-Z0-9-_]+$

唯一属性ID。 external_id只能包含大小写英文字母、数字、短横线和下划线。

items[].​attributes[].​namestring

属性名称。

示例: "Genre"
items[].​attributes[].​valuesArray of objects
items[].​attributes[].​values[].​external_idstring[ 1 .. 255 ] characters^[-_.\d\w]+$

属性的唯一值ID。 external_id只能包含小写英文字母、数字、短横线和下划线。

items[].​attributes[].​values[].​valuestring

属性值。

示例: "Strategy"
items[].​image_urlstring
items[].​quantityinteger
items[].​is_freeboolean

该商品是否免费。

items[].​priceobject or null

商品价格。

items[].​price.​amountstring

商品折后价格。

示例: "2.9900"
items[].​price.​amount_without_discountstring

商品价格。

示例: "2.9900"
items[].​price.​currencystring

商品价格币种。符合ISO 4217标准的三字母代码。

示例: "USD"
items[].​promotionsArray of objects

应用于购物车中指定商品的促销活动。仅在以下情况下返回该数组：

  • 为某商品配置了折扣促销活动。

  • 应用了具有对所选商品提供折扣设置的兑换码。

如果未应用任何商品级促销活动，则返回空数组。

items[].​promotions[].​namestring
items[].​promotions[].​date_startstring or null(date-time)
items[].​promotions[].​date_endstring or null(date-time)
items[].​promotions[].​discountobject or null
items[].​promotions[].​discount.​percentstring or null
items[].​promotions[].​discount.​valuestring or null
items[].​promotions[].​bonusArray of objects
items[].​promotions[].​bonus[].​skustring
items[].​promotions[].​bonus[].​quantityinteger
items[].​promotions[].​bonus[].​typestring

赠品类型。

枚举"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
items[].​promotions[].​bonus[].​namestring

赠品名称。不适用于physical_good赠品类型。

items[].​promotions[].​bonus[].​image_urlstring

赠品图片URL。不适用于physical_good赠品类型。

items[].​promotions[].​bonus[].​bundle_typestring

赠品捆绑包商品类型。仅适用于bundle赠品类型。

枚举"standard""virtual_currency_package"
items[].​promotions[].​limitsobject
items[].​promotions[].​limits.​per_userobject
items[].​promotions[].​limits.​per_user.​availableinteger
items[].​promotions[].​limits.​per_user.​totalinteger
items[].​can_be_boughtboolean

如为true，则用户可以购买商品。

items[].​vp_rewardsArray of objects

累充积分商品奖励。

items[].​vp_rewards[].​item_idinteger

内部唯一商品ID。

items[].​vp_rewards[].​skustring

唯一累充积分ID。

items[].​vp_rewards[].​amountinteger

累充积分数量。

items[].​vp_rewards[].​namestring

累充积分名称。

items[].​vp_rewards[].​image_urlstring

图片URL。

items[].​vp_rewards[].​is_clanboolean

累充积分是否用于公会累充奖励链。

items[].​limitsobject or null

商品限制数。

items[].​limits.​per_userobject or null

单个用户的商品购买数量限制。

items[].​limits.​per_user.​totalinteger

单个用户可购买的最大商品数量。

示例: 5
items[].​limits.​per_user.​availableinteger

当前用户可购买的剩余商品数量。

示例: 3
items[].​limits.​per_user.​recurrent_schedule(object or null)
One of:

用户的商品限制循环刷新周期。

object or null
items[].​limits.​per_user.​limit_exceeded_visibilitystring

设定商品在达到购买限制后、下次限制重置前在商品目录中的可见性。

适用于在recurrent_schedule数组中配置了周期性重置数量限制的商品。

如果未配置重置限制，则达到购买限制后，无论limit_exceeded_visibility的值如何，该商品都不会显示在商品目录中。

可能值：

  • show — 达到购买限制后，商品目录检索API调用仍会返回该商品。在客户端侧 商品目录检索API调用中，达到限制后返回的商品会带有can_be_bought: false 标志。下一次重置日期 将在reset_next_date中返回。
  • hide — 达到购买限制后，在限制 重置之前，商品目录检索API调用不会返回该商品。
枚举"show""hide"
items[].​limits.​per_itemobject or null

单个商品的购买数量限制。

items[].​limits.​per_item.​totalinteger

所有用户可购买的最大商品数量。

示例: 5
items[].​limits.​per_item.​availableinteger

所有用户还可购买的剩余商品数量。

示例: 3
items[].​periodsArray of objects or null

商品销售期。

items[].​periods[].​date_fromstring(date-time)

指定商品开始可购的日期。

示例: "2020-08-11T10:00:00+03:00"
items[].​periods[].​date_untilstring or null(date-time)

指定商品停止可购的日期。可为null。

示例: "2020-08-11T20:00:00+03:00"
响应
application/json
{
  "cart_id": "cart_id",
  "is_free": false,
  "items": [
    { … }
  ],
  "price": {
    "amount": "6150.0000000000000000",
    "amount_without_discount": "6150.0000000000000000",
    "currency": "USD"
  }
}

获取兑换码奖励Client-side

请求

通过兑换码获取兑换码奖励。可用于允许用户从多个商品中选择一个作为赠品。常见场景是：如果兑换码包含游戏作为赠品(type=unit)，则选择DRM。

注：

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

请在Authorization请求头中按以下格式传入令牌：Bearer <user_JWT>。关于用户JWT的更多信息，请参阅此调用的安全性部分。
安全
XsollaLoginUserJWT
路径
project_idinteger必需

项目ID。您可以在发布商帐户的项目名称旁找到此参数；使用项目时，也可以在浏览器地址栏中找到此参数。URL格式如下：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

示例: 44056
promocode_codestring[ 1 .. 128 ] characters必需

区分大小写的唯一兑换码。包含字母和数字。

示例: SO6rew99j9
curl -i -X GET \
  https://store.xsolla.com/api/v2/project/44056/promocode/code/SO6rew99j9/rewards \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

响应

已成功接收兑换码奖励列表。

正文application/json
bonusArray of objects
bonus[].​itemobject
bonus[].​item.​skustring

唯一商品ID。SKU只能包含大小写英文字母、数字、句点、短横线和下划线。

示例: "game_01"
bonus[].​item.​namestring

商品名称。

示例: "Game name"
bonus[].​item.​typestring

商品类型。可能值：

  • virtual_good — 虚拟物品
  • virtual_currency — 虚拟货币
  • bundle — 捆绑包
  • unit — 游戏Key套餐

示例: "unit"
bonus[].​item.​descriptionstring

Item description.

示例: "Game description"
bonus[].​item.​image_urlstring

图片URL。

示例: "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png"
bonus[].​item.​unit_itemsArray of objects

平台专属游戏Key数组。仅当商品类型为unit (bonus.item.type = 'unit')时使用。如果游戏Key套餐包含平台专属Key，用户可以选择其中一个作为赠品。

bonus[].​item.​unit_items[].​skustring^[a-zA-Z0-9_\-.]*$

唯一的平台专属游戏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。

示例: "cool_game_steam"
bonus[].​item.​unit_items[].​is_freeboolean
bonus[].​item.​unit_items[].​typestring

表示该商品为游戏Key。

值"game_key"
bonus[].​item.​unit_items[].​namestring

游戏名称。

示例: "Awesome Game"
bonus[].​item.​unit_items[].​drm_namestring

DRM名称。

示例: "Steam"
bonus[].​item.​unit_items[].​drm_skustring^[a-zA-Z0-9_\-.]*$

唯一DRM ID，用作后缀以表示平台专属游戏Key。允许使用以下字符：a-z、A-Z、0-9、句点（.）、连字符（-）、下划线（_）。

示例: "steam"
bonus[].​quantitynumber

商品数量。

默认值 1
discountobject or null

百分比折扣。 购物车价格将按照此百分比打折，然后四舍五入到小数点后两位。

discount.​percentstring
示例: "10.00"
discounted_itemsArray of objects or null

通过兑换码享受折扣的商品列表。

discounted_items[].​skustring必需

商品SKU。

默认值 "elven_shield"
discounted_items[].​discountobject必需
discounted_items[].​discount.​percentstring必需

百分比折扣。

购物车商品价格将按照此百分比打折， 然后四舍五入到小数点后两位。

is_selectableboolean

如果为true，则用户应在核销兑换码前选择赠品。

响应
application/json
{
  "bonus": [
    { … },
    { … }
  ],
  "discount": {
    "percent": "10.00"
  },
  "is_selectable": true,
  "discounted_items": [
    { … }
  ]
}

专属商品目录优惠

调用此子部分中的API方法，配置和管理专属商品目录优惠。

注：

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

操作

折扣

调用此子部分中的API方法，配置和管理折扣促销活动。

注：

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

操作

买赠

调用此子部分中的API方法，配置和管理买赠促销活动。

注：

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

操作

个性化商品目录

个性化功能允许您指定商品目录显示和促销活动应用的条件，使其仅面向特定授权用户生效。条件基于用户属性定义，可帮助您向特定用户提供最相关的商品和促销活动。

支持以下个性化类型：

  • 艾克索拉侧个性化。个性化规则和逻辑在艾克索拉侧配置并存储。您传入用户属性后，艾克索拉会使用这些属性生成个性化商品目录。
  • 合作伙伴侧个性化。您在己侧配置个性化规则和逻辑，并将特定用户的最终商品目录数据载荷发送给艾克索拉。
注：

您只能使用一种个性化类型。如需更改，请按照 说明进行操作。

如需使用艾克索拉API在艾克索拉侧配置个性化：

  1. 使用虚拟物品和货币、捆绑包或游戏Key组的管理子部分中的API调用创建商品。

  2. 使用使用艾克索拉登录管理器API设置用户属性，并在您的游戏中发生变更时更新艾克索拉中的数据，确保数据保持同步。

  3. 为商品或促销活动配置个性化：

    • 如需对商品目录进行个性化，请使用创建商品目录筛选规则 API 调用定义商品目录显示规则：
      • 在attribute_conditions数组中，指定根据用户属性确定商品可用性的条件。
      • 在items数组中，提供在用户属性符合指定条件时应向用户显示的商品列表。
    • 如需配置个性化促销活动，请使用[所需促销活动类型的创建和更新API调用]](/zh/api/liveops/promotions-discounts/create-item-promotion)。在attribute_conditions数组中，指定基于用户属性确定促销活动可用性的条件。

  4. 在商品目录获取API调用中传入包含用户属性的用户JWT，以接收个性化商品目录。

为商品目录配置并应用艾克索拉侧个性化的流程：

商品目录个性化

为促销活动配置并应用艾克索拉侧个性化的流程：

促销活动个性化

注：

详细信息请参阅：
操作

概述

促销活动使用限制用于限制特定用户可使用某个促销活动的次数。您还可以配置定时重置限制。

限制数信息存储在艾克索拉侧，可在发布商帐户的促销活动设置中配置，也可以在以下API调用中通过limits对象配置：

在以下用于获取商品目录的API调用中，限制信息会在items.promotions.limits对象中返回：

限制组的管理部分中的API调用可用于获取限制的当前状态，并针对特定用户更新限制，例如在任务完成后重置计数器，或手动调整剩余数量。

注：

有关在商品目录中配置限制数的详细信息，请参阅促销活动使用限制部分。

您可以配置limits.per_user，即单个用户可使用某个促销活动的次数限制。

未认证用户始终会看到促销活动的最大可使用次数。

如需显示用户在当前有效限制下剩余的促销活动可使用次数，请在请求商品目录时传入用户授权数据。

如需配置定时重置周期（日、周或月），请在创建或更新促销活动时传入limits.recurrent_schedule对象。

限制配置和执行场景

  1. 使用为商品创建折扣促销或创建买赠促销活动 API调用创建促销活动，并传入limits对象。
  2. 为未认证用户请求商品目录⸺响应会在items.promotions.limits对象中返回促销活动的最大可使用次数。
  3. 用户登录。
  4. 使用用户的授权令牌请求商品目录⸺响应会返回当前有效限制下的剩余可使用次数。
  5. 用户选择促销商品并进行购买。
  6. 支付成功后，艾克索拉会更新items.promotions.limits.per_user值。当该值达到0时，后续商品目录API调用会返回该商品，但不再包含折扣或赠品。
  7. 您可以使用管理子部分中的API调用更新限制数：
  8. 在下一次使用用户授权令牌发起的商品目录请求中，您可以从items.promotions.limits获取更新后的限制值，并将其显示给用户。

促销活动限制

管理

操作

概述

累充奖励链用于激励用户在商店中使用真实货币购买商品。用户每完成一次购买，即可获得累充积分，并推进累充奖励链进度。如果用户属于某个公会，其购买行为还会为整个公会贡献累充积分。如需了解累充奖励链配置的详细信息，请参阅奖励系统部分。

如需配置累充奖励链，请使用管理子部分中的API调用。如需显示奖励链并领取奖励，请使用客户端子部分中的API调用。如需实现公会累充奖励链相关功能，请使用公会客户端子部分中的API调用。

累充奖励链配置流程示例：

  1. 使用虚拟物品和货币或捆绑包组中管理子部分的API调用创建商品。
  2. 使用创建累充积分API调用创建累充积分。
  3. 使用设置商品的累充积分API调用为商品分配累充积分。用户购买这些商品后即可获得累充积分。
  4. 使用创建累充奖励链API调用创建奖励链。如需激活该奖励链，请传入is_enabled: true参数。
  5. 实现累充奖励链显示。为此，请使用获取当前用户的累充奖励链API调用请求可用奖励链列表。响应中包含所有有效奖励链及其步骤和状态。
  6. 实现累充积分余额显示。为此，请使用获取当前用户的累充积分余额API调用。
  7. 实现步骤奖励领取。为此，请使用领取步骤奖励API调用。
  8. 配置订单状态跟踪，例如使用Webhook，以便及时接收已领取奖励的数据并向用户发放奖励。

奖励链配置流程

管理

操作

客户端

操作

公会客户端

操作

管理

操作

客户端

操作

概述

优惠链由一系列步骤组成，每个步骤都包含一个商品，用户可免费领取或使用有效优惠购买。优惠链可以包含仅在该链内可获得的专属商品，也可以包含价格低于商店价格的折扣商品。如需了解该营销工具配置的详细信息，请参阅优惠链部分。

如需配置优惠链，请使用管理子部分中的API调用。如需展示优惠链并实现用户获得商品后的处理逻辑，请使用客户端子部分中的API调用。

优惠链配置流程示例：

  1. 使用虚拟物品和货币或捆绑包组中管理子部分的API调用创建商品。

  2. 使用创建优惠链API调用创建优惠链。如需激活该优惠链，请传入is_enabled: true参数。

  3. 实现优惠链显示。为此，请使用获取当前用户的优惠链API调用请求可用优惠链列表。响应中包含所有有效优惠链及其步骤和状态。

  4. 实现用户所获商品的相关处理逻辑：

    • 如果步骤商品为免费商品，请使用领取免费优惠链步骤API调用。在请求中传入offer_chain_id和step_number。

    • 如果步骤商品为付费商品，请使用为付费优惠链步骤创建订单API调用。在请求中传入offer_chain_id和step_number。响应将返回order_id和用于打开支付UI的令牌。

  5. 配置订单状态跟踪，例如使用Webhook，以便及时接收已领取或已购买商品的数据并向用户发放商品。

奖励链配置流程

管理

操作

客户端

操作

管理

操作

客户端

操作