跳转到内容
/
删除奖励链

LiveOps API (2.0.0)

概述

  • 版本： 2.0.0
  • 服务器：https://store.xsolla.com/api
  • 通过邮件联系我们
  • 联系URL: https://xsolla.com/
  • 必需的TLS版本： 1.2

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

通过该API可管理以下功能：

  • 促销活动 — 创建和管理优惠券、促销码、折扣及奖励活动。
  • 个性化 — 指定商品目录显示和促销活动应用条件，仅面向特定授权用户。
  • 促销活动限制 — 设置用户使用促销活动的次数限制，并配置限制的定期重置。
  • 奖励链和奖励积分 — 配置与奖励积分累积关联的奖励进度。
  • 每日奖励链 — 设置循环每日奖励，激励玩家定期登录。
  • 优惠链 — 创建阶梯式连续购买优惠，每步提供不同定价和免费奖励选项。
  • 追加销售 —向用户提供购买超值商品的销售方式。

API调用

API分为以下组别:

  • Admin — 用于创建、更新、激活和删除营销活动及奖励链配置。通过基本认证方式验证身份，需使用您的商户或项目凭据。
  • Client — 用于检索可用促销活动、获取活跃奖励链、兑换码，以及代表最终用户（已完成身份认证）领取奖励。通过用户JWT进行身份认证。
下载 OpenAPI 描述
index.json
index.yaml
语言
服务器
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/zh/api/liveops/

通用

操作

优惠券

此API让您可以管理优惠券。

操作

促销码

此API让您可以管理促销码。

操作

特别目录优惠

此API让您可以管理特别目录优惠活动。

操作

折扣

此API让您可以管理折扣促销活动。

操作

奖励

此API让您可以管理奖励促销活动。

操作

个性化目录

此API可让您针对用户属性指定规则。如果用户满足具体规则的所有条件，则会显示个性化商品。

有关个性化促销活动的信息，请参阅促销活动部分。

要在购买前传递属性，您可以使用艾克索拉Login API或在使Pay Station API生成令牌时将它们传入user.attributes属性。

操作

管理

操作

管理

操作

创建奖励链Server-sideAdmin

请求

创建奖励链。

安全
basicAuth
路径
project_idinteger必需

项目ID。您可以在您的发布商帐户项目名称旁边找到。

示例: 44056
正文application/json
One of:

一个奖励链。

attribute_conditionsArray of type = string (object) or type = number (object) or type = date (object)(chain_user-attribute_conditions_model-post)[ 1 .. 100 ] items

用户属性验证条件。 根据用户属性是否满足所有指定条件来确定优惠链可用性。

description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)

包含本地化商品描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

One of:

包含本地化商品描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

image_urlstring or null(image_url)

图像URL。

示例: "https://image.example.com"
is_always_visibleboolean(chain_is_always_visible)

优惠链是否对所有用户可见：

  • 如为true，则无论用户的认证状态或属性如何，优惠链始终显示。
  • 如为false，则仅在未找到个性化优惠链时才显示该优惠链。例如，当用户未认证或其属性与任何个性化优惠链都不匹配时。

仅适用于存在个性化奖励链的前提，并在未传递attribute_conditions数组时使用。

默认值 true
示例: true
is_enabledboolean(is_enabled)必需
示例: true
is_reset_after_endboolean(is_reset_after_end)

是否在结束日期后重置奖励链（所有用户的奖励积分和进度）：

  • 如为true，奖励链将在结束日期后重置。
  • 如为false，奖励链在结束日期后不重置。

注意

以下情况不能设置为true：
  • recurrent_schedule中已设置重置周期。
  • periods.date_until中传入了null值。
默认值 false
示例: false
long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

包含商品详细本地化描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

Any of:

包含商品详细本地化描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)必需

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

One of:

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

name.​arstring or null

阿拉伯语

name.​bgstring or null

保加利亚语

name.​cnstring or null

中文（简体）

name.​csstring or null

捷克语

name.​destring or null

德语

name.​enstring or null

英语

name.​esstring or null

西班牙语（西班牙）

name.​frstring or null

法语

name.​hestring or null

希伯来语

name.​idstring or null

印度尼西亚语

name.​itstring or null

意大利语

name.​jastring or null

日语

name.​kmstring or null

高棉语

name.​kostring or null

韩语

name.​lostring or null

老挝语

name.​mystring or null

缅甸语

name.​nestring or null

尼泊尔语

name.​phstring or null

菲律宾语

name.​plstring or null

波兰语

name.​ptstring or null

葡萄牙语

name.​rostring or null

罗马尼亚语

name.​rustring or null

俄语

name.​thstring or null

泰语

name.​trstring or null

土耳其语

name.​twstring or null

中文（繁体）

name.​vistring or null

越南语

orderinteger(order)

定义排列顺序。

示例: 1
periodsArray of objects(periods)必需

奖励链有效期。若指定了多个时间段，则date_from和date_until均为必需。

periods[].​date_fromstring(date-time)必需

指定奖励链的开始日期。

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

指定奖励链的结束日期。仅在指定单个有效期时可为null。

示例: "2020-08-11T20:00:00+03:00"
recurrent_schedule(interval_type = weekly (object or null)) or (interval_type = monthly (object or null)) or (interval_type = hourly (object or null))(recurrent_schedule_create_update)

奖励链的重置周期。

One of:

奖励链的重置周期。

stepsArray of objects(create_reward_step)必需
steps[].​image_urlstring or null(image_url)

图像URL。

示例: "https://image.example.com"
steps[].​name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)必需

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

One of:

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

steps[].​name.​arstring or null

阿拉伯语

steps[].​name.​bgstring or null

保加利亚语

steps[].​name.​cnstring or null

中文（简体）

steps[].​name.​csstring or null

捷克语

steps[].​name.​destring or null

德语

steps[].​name.​enstring or null

英语

steps[].​name.​esstring or null

西班牙语（西班牙）

steps[].​name.​frstring or null

法语

steps[].​name.​hestring or null

希伯来语

steps[].​name.​idstring or null

印度尼西亚语

steps[].​name.​itstring or null

意大利语

steps[].​name.​jastring or null

日语

steps[].​name.​kmstring or null

高棉语

steps[].​name.​kostring or null

韩语

steps[].​name.​lostring or null

老挝语

steps[].​name.​mystring or null

缅甸语

steps[].​name.​nestring or null

尼泊尔语

steps[].​name.​phstring or null

菲律宾语

steps[].​name.​plstring or null

波兰语

steps[].​name.​ptstring or null

葡萄牙语

steps[].​name.​rostring or null

罗马尼亚语

steps[].​name.​rustring or null

俄语

steps[].​name.​thstring or null

泰语

steps[].​name.​trstring or null

土耳其语

steps[].​name.​twstring or null

中文（繁体）

steps[].​name.​vistring or null

越南语

steps[].​priceobject(reward_step_price)必需
steps[].​price.​amountinteger(step_price_amount)必需

以奖励积分表示的步骤价格。

示例: 100
steps[].​rewardArray of objects必需
steps[].​reward[].​attribute_conditionsArray of type = string (object) or type = number (object) or type = date (object)(reward-chain-step-reward_user-attribute_conditions_model-post)[ 1 .. 100 ] items

用户属性验证条件。 根据用户属性是否满足所有指定条件来确定奖励链步骤的奖励可用性。

steps[].​reward[].​quantityinteger(reward_item_quantity)必需

商品数量。

示例: 2
steps[].​reward[].​skustring(sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$必需

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

示例: "booster_mega_1"
value_pointobject必需
value_point.​skustring(sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$必需

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

示例: "booster_mega_1"
curl -i -X POST \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/reward_chain \
  -H 'Content-Type: application/json' \
  -d '{
    "clan_type": "guild",
    "description": {
      "en": "Clan reward chain description."
    },
    "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
    "is_enabled": true,
    "long_description": {
      "en": "Clan reward chain long description."
    },
    "name": {
      "en": "Clan reward chain"
    },
    "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"
      }
    ],
    "popup_header": {
      "en": "How to unlock rewards"
    },
    "popup_image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
    "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."
    },
    "recurrent_schedule": {
      "day_of_week": 1,
      "interval_type": "weekly",
      "time": "01:00:00+08:00"
    },
    "steps": [
      {
        "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
        "name": {
          "en": "First step of the reward chain"
        },
        "price": {
          "amount": 10
        },
        "reward": [
          {
            "quantity": 5,
            "sku": "com.xsolla.item_1"
          },
          {
            "quantity": 1,
            "sku": "com.xsolla.item_2"
          }
        ]
      },
      {
        "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
        "name": {
          "en": "Second step of the reward chain"
        },
        "price": {
          "amount": 15
        },
        "reward": [
          {
            "quantity": 5,
            "sku": "com.xsolla.item_3"
          },
          {
            "quantity": 1,
            "sku": "com.xsolla.item_4"
          }
        ]
      }
    ],
    "value_point": {
      "sku": "com.xsolla.clan_value_point_1"
    }
  }'

响应

已成功创建奖励链。

正文application/json
reward_chain_idinteger
示例: 10
响应
application/json
{
  "reward_chain_id": 10
}

删除奖励链Server-sideAdmin

请求

删除特定奖励链。

安全
basicAuth
路径
project_idinteger必需

项目ID。您可以在您的发布商帐户项目名称旁边找到。

示例: 44056
reward_chain_idinteger必需

奖励链ID。

示例: 101
curl -i -X DELETE \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/reward_chain/id/101

响应

已成功删除奖励链。

正文
响应
无内容

获取奖励链Server-sideAdmin

请求

获取特定奖励链。

安全
basicAuth
路径
project_idinteger必需

项目ID。您可以在您的发布商帐户项目名称旁边找到。

示例: 44056
reward_chain_idinteger必需

奖励链ID。

示例: 101
curl -i -X GET \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/reward_chain/id/101

响应

已成功收到指定的奖励链。

正文application/json
One of:

一个奖励链。

attribute_conditionsArray of type = string (object) or type = number (object) or type = date (object)(chain_user-attribute_conditions_model-get)[ 1 .. 100 ] items

用户属性验证条件。 根据用户属性是否满足所有指定条件来确定优惠链可用性。

description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)

包含本地化商品描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

One of:

包含本地化商品描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

image_urlstring or null(image_url)

图像URL。

示例: "https://image.example.com"
is_always_visibleboolean(chain_is_always_visible)

优惠链是否对所有用户可见：

  • 如为true，则无论用户的认证状态或属性如何，优惠链始终显示。
  • 如为false，则仅在未找到个性化优惠链时才显示该优惠链。例如，当用户未认证或其属性与任何个性化优惠链都不匹配时。

仅适用于存在个性化奖励链的前提，并在未传递attribute_conditions数组时使用。

默认值 true
示例: true
is_enabledboolean(is_enabled)
示例: true
is_reset_after_endboolean(is_reset_after_end)

是否在结束日期后重置奖励链（所有用户的奖励积分和进度）：

  • 如为true，奖励链将在结束日期后重置。
  • 如为false，奖励链在结束日期后不重置。

注意

以下情况不能设置为true：
  • recurrent_schedule中已设置重置周期。
  • periods.date_until中传入了null值。
默认值 false
示例: false
long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

包含商品详细本地化描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

Any of:

包含商品详细本地化描述的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的区域设置代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

One of:

包含商品本地化名称的对象。值接受以下两种格式之一：两个小写字母的语言代码（例如，en）或五个字符的语言代码（例如，en-US）。虽然两种格式都可作为输入接受，但响应会返回两个小写字母的语言代码。当为同一种语言提供了两种输入时（例如：en和en-US），将存储最后提供的值。您可以在文档中找到支持语言的完整列表。

orderinteger(order)

定义排列顺序。

示例: 1
periodsArray of objects(periods)

奖励链有效期。若指定了多个时间段，则date_from和date_until均为必需。

recurrent_schedule(interval_type = weekly (object or null)) or (interval_type = monthly (object or null)) or (interval_type = hourly (object or null))(admin_recurrent_schedule)

奖励链的重置周期。

One of:

奖励链的重置周期。

reward_chain_idinteger(reward_chain_id)

唯一奖励链ID。

示例: 9
stepsArray of objects(reward_step_short)
value_pointobject
响应
application/json
{
  "clan_type": "guild",
  "description": {
    "en": "Clan reward chain description."
  },
  "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
  "is_enabled": true,
  "long_description": {
    "en": "Clan reward chain long description."
  },
  "name": {
    "en": "Clan reward chain"
  },
  "order": 1,
  "periods": [
    { … }
  ],
  "popup_header": {
    "en": "How to unlock rewards"
  },
  "popup_image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
  "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."
  },
  "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"
  },
  "reward_chain_id": 1,
  "steps": [
    { … },
    { … }
  ],
  "value_point": {
    "description": { … },
    "image_url": "https://cdn.xsolla.net/img/misc/images/5c3b8b45c5be5fe7803e59fbc8041be4.png",
    "is_clan": true,
    "is_enabled": true,
    "long_description": { … },
    "media_list": [],
    "name": { … },
    "order": 1,
    "sku": "com.xsolla.clan_value_point_1"
  }
}

客户端

操作

公会客户端

操作

管理

操作

客户端

操作

管理

操作

客户端

操作

管理

操作

客户端

操作