Virtual currency description.
商品目录API (2.0.0)
- 版本： 2.0.0
- 服务器：
https://store.xsolla.com/api - 通过电子邮件联系我们
- 联系网址： https://xsolla.com/
- 所需TLS版本： 1.2
商品目录API可用于在艾克索拉侧配置游戏内购商品目录，并在您的商店中向用户展示该商品目录。
该API可用于管理以下商品目录实体：
- 虚拟物品 — 武器、皮肤、加成道具等游戏内物品。
- 虚拟货币 — 用于购买虚拟物品的虚拟资金。
- 虚拟货币套餐 — 预定义的虚拟货币捆绑包。
- 捆绑包 — 将虚拟物品、货币或游戏Key组合后作为单个SKU销售的组合包。
- 游戏Key — 通过Steam等平台或其他DRM提供商分发的游戏和DLC密钥。
- 组 — 用于在商品目录中组织和排序商品的逻辑分组。
该API分为以下组别：
Admin — 用于创建、更新、删除和配置商品目录中的商品及分组的调用。通过基本访问身份认证方式进行身份认证，需使用您的商户或项目凭据。不适用于商店前端调用。Catalog — 用于检索商品并构建面向最终用户的自定义商店前端。专为高负载场景设计。支持可选的用户JWT授权，可返回个性化数据，例如用户限购额度和当前进行中的促销活动。
当请求从浏览器、移动应用或游戏发送时，使用用户JWT身份认证。默认情况下，应用XsollaLoginUserJWT方案。有关如何创建令牌的详细信息，请参阅艾克索拉登录管理器API文档。
令牌通过Authorization请求头按以下格式传递：Authorization: Bearer <user_JWT>，其中<user_JWT>为用户令牌。该令牌用于识别用户，并授予其访问个性化数据的权限。
或者，您也可以使用用于打开支付UI的令牌。
基本HTTP身份认证用于服务器到服务器交互，即API调用直接从您的服务器发送，而不是从用户的浏览器或移动应用发送。通常使用带有API密钥的HTTP Basic身份认证。
注：
API密钥属于机密信息，不得在客户端应用中存储或使用。
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调用不包含
如果所需的API调用不包含
project_id路径参数，请使用对公司所有项目均有效的API密钥进行授权。有关使用API密钥的更多信息，请参阅API参考。
AuthForCart身份认证方案用于购物车购买，支持两种模式：
使用用户JWT进行身份认证。 令牌通过
Authorization请求头按以下格式传递：Authorization: Bearer <user_JWT>，其中<user_JWT>是用户令牌。该令牌用于识别用户，并提供对个性化数据的访问权限。 或者，您也可以使用用于打开支付UI的令牌。不带Authorization请求头的简化模式。 此模式仅适用于未完成身份认证的用户，且仅可用于游戏Key销售请求中不使用令牌，而必须包含以下请求头：
x-unauthorized-id，值为请求IDx-user，值为使用Base64编码的用户电子邮件地址
所有类型的商品（虚拟物品、捆绑包、虚拟货币和密钥）都使用类似的数据结构。了解基本结构有助于简化API使用，并帮助您更轻松地查阅文档。
注：
部分调用可能包含其他字段，但这些字段不会改变基本结构。
部分调用可能包含其他字段，但这些字段不会改变基本结构。
标识信息
merchant_id— 发布商帐户中的公司IDproject_id— 发布商帐户中的项目IDsku— 商品SKU，在项目内唯一
商店显示
name— 商品名称description— 商品描述image_url— 图片URLis_enabled— 商品可用性is_show_in_store— 商品是否显示在商品目录中
有关在商品目录中管理商品可用性的更多信息，请参阅文档。
组织方式
type— 商品类型，例如虚拟物品（virtual_item）或捆绑包（bundle）groups— 商品所属的组order— 在商品目录中的显示顺序
Sale conditions
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调用会返回请求时商店中当前可用的商品。如需获取尚未可用或已不再可用的商品，请在商品目录请求中包含参数
"show_inactive_time_limited_items": 1。
您可以使用以下方法销售商品：
- 快速购买 — 多次销售同一SKU。
- 购物车购买 — 用户可在同一订单中向购物车添加商品、移除商品并更新数量。
如果商品使用虚拟货币而非真实货币购买，请使用创建包含指定商品的订单 API调用。由于扣款会在执行API调用时处理，因此无需支付UI。
如需购买免费商品，请使用使用指定商品创建订单 API调用或使用免费购物车创建订单 API调用。无需支付UI — 订单会立即设置为done状态。
可以在客户端或服务器侧设置购物车并完成购买。
在客户端设置和购买购物车商品
您需要自行实现添加和移除商品的逻辑。在调用用于设置购物车的API之前，您无法获知哪些促销活动会应用于本次购买。这意味着您无法提前获知总费用以及添加的赠品的详细信息。
实现以下购物车逻辑：
- 玩家在购物车加购后，使用向购物车添加商品 API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。
- 根据用户操作更新购物车内容：
- 如需添加商品或更改商品数量，请使用按购物车ID更新购物车商品 API调用。
- 如需移除商品，请使用按购物车ID删除购物车商品 API调用。
注：
如需获取购物车的当前状态，请使用“获取当前用户的购物车”API调用。
如需获取购物车的当前状态，请使用“获取当前用户的购物车”API调用。
- 使用创建包含当前购物车中所有商品的订单 API调用。该调用返回订单ID和支付令牌。新创建的订单默认设置为
new状态。
在服务器侧设置和购买购物车商品
这种设置方式可能需要更长的购物车设置时间，因为每次更改购物车都必须伴随API调用。
实现以下购物车逻辑：
- 玩家在购物车加购后，使用向购物车添加商品 API调用。该调用会返回所选商品的当前信息（折扣前后价格、赠品）。
- 使用创建包含当前购物车中所有商品的订单 API调用。该调用会返回订单ID和支付令牌。新创建的订单默认设置为
new状态。
使用返回的令牌在新窗口中打开支付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
艾克索拉支持对商品名称、描述等面向用户的字段进行本地化。本地化值以对象形式传递，其中语言代码作为键。支持的完整语言列表，请参阅文档。
支持的字段
可为以下参数指定本地化内容：
namedescriptionlong_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 描述
语言
服务器
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/zh/api/catalog/
概述
您可以使用虚拟物品和虚拟货币构建游戏内购商店，并配置其向用户展示的方式。可使用以下商品类型：
- 虚拟物品 — 武器、皮肤、加成道具等游戏内商品。可使用真实货币或虚拟货币销售。
- 虚拟货币 — 用于购买虚拟物品的游戏内货币。可使用真实货币或虚拟货币销售。
- 虚拟货币套餐 — 固定数量的虚拟货币。可使用真实货币或虚拟货币销售。
组(Group)用于组织商品目录中的商品。通过组，您可以按逻辑对商品进行分组，并管理商品的显示方式。
使用管理子部分中的API调用来创建、更新和删除商品。
使用商品目录子部分中的API调用获取商品列表，并向用户展示商品。
提示
请勿使用管理子部分中的API调用来构建商店商品目录。
请勿使用管理子部分中的API调用来构建商店商品目录。
注：
获取虚拟物品列表API调用会返回详细的商品数据，包括价格和属性，并支持分页。请使用该调用在商店前端显示商品目录页面。
获取所有虚拟物品列表API调用会返回商品SKU、名称、描述，以及组ID和组名称，且不分页。请将其用于客户端侧搜索或索引。
获取虚拟物品列表API调用会返回详细的商品数据，包括价格和属性，并支持分页。请使用该调用在商店前端显示商品目录页面。
获取所有虚拟物品列表API调用会返回商品SKU、名称、描述，以及组ID和组名称，且不分页。请将其用于客户端侧搜索或索引。
如需使用虚拟货币的购买，请使用使用以虚拟货币购买的指定商品创建订单 API调用。无需支付UI⸺扣款会在执行API调用时完成。
使用虚拟货币购买流程示例：
请求
获取用于构建商品目录的虚拟货币套餐列表。
注意
所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。
所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。
注：
未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在
未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在
Authorization请求头中传递用户JWT。
有关用户JWT的更多信息，请参阅此调用的Security部分。
安全
XsollaLoginUserJWT
路径
项目ID。您可以在发布商帐户的项目名称旁找到此参数；使用项目时，也可以在浏览器地址栏中找到此参数。URL格式如下：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
示例: 44056
查询
响应语言。符合ISO 639-1标准的两位小写语言代码（例如en）。name和description等本地化字段支持五字符区域代码（例如en-US），但在响应中会标准化为两位代码。支持的语言完整列表请参阅文档。
默认值 "en"
附加字段列表。如果在请求中发送这些字段，则它们将包含在响应中。
项 枚举"media_list""order""long_description""custom_attributes""item_order_in_group"
- https://store.xsolla.com/api/v2/project/{project_id}/items/virtual_currency/package
- Mock serverhttps://xsolla.redocly.app/_mock/zh/api/catalog/v2/project/{project_id}/items/virtual_currency/package
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://store.xsolla.com/api/v2/project/44056/items/virtual_currency/package?limit=50&offset=0&locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'已成功收到虚拟货币套餐列表。
商品所属分组。
与商品对应的属性及其值的列表。可用于商品目录筛选。
图片URL。
示例: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
商品价格。
虚拟价格。
虚拟货币套餐内容。
示例: [{"description":"Crystal Pack - short description","image_url":"https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png","sku":"com.xsolla.crystal_pack_1","name":"Crystal Pack","type":"virtual_currency","quantity":100}]
图片URL。
示例: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
商品限制数。
单个用户的商品购买数量限制。
items[].content[].limits.per_user.recurrent_schedule(object or null)(catalog_recurrent_schedule_client_response)
One of:
用户的商品限制循环刷新周期。
object or null
设定商品在达到购买限制后、下次限制重置前在商品目录中的可见性。
适用于在recurrent_schedule数组中配置了周期性重置数量限制的商品。
如果未配置重置限制，则达到购买限制后，无论limit_exceeded_visibility的值如何，该商品都不会显示在商品目录中。
可能值：
show— 达到购买限制后，商品目录检索API调用仍会返回该商品。在客户端侧 商品目录检索API调用中，达到限制后返回的商品会带有can_be_bought: false标志。下一次重置日期 将在reset_next_date中返回。hide— 达到购买限制后，在限制 重置之前，商品目录检索API调用不会返回该商品。
枚举"show""hide"
应用于购物车中指定商品的促销活动。仅在以下情况下返回该数组：
为某商品配置了折扣促销活动。
应用了具有对所选商品提供折扣设置的兑换码。
如果未应用任何商品级促销活动，则返回空数组。
赠品类型。
枚举"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
商品限制数。
单个用户的商品购买数量限制。
items[].limits.per_user.recurrent_schedule(object or null)(catalog_recurrent_schedule_client_response)
One of:
用户的商品限制循环刷新周期。
object or null
设定商品在达到购买限制后、下次限制重置前在商品目录中的可见性。
适用于在recurrent_schedule数组中配置了周期性重置数量限制的商品。
如果未配置重置限制，则达到购买限制后，无论limit_exceeded_visibility的值如何，该商品都不会显示在商品目录中。
可能值：
show— 达到购买限制后，商品目录检索API调用仍会返回该商品。在客户端侧 商品目录检索API调用中，达到限制后返回的商品会带有can_be_bought: false标志。下一次重置日期 将在reset_next_date中返回。hide— 达到购买限制后，在限制 重置之前，商品目录检索API调用不会返回该商品。
枚举"show""hide"
商品销售期。
响应
application/json
{ "has_more": false, "items": [ { … }, { … } ] }
请求
按SKU获取用于构建商品目录的虚拟货币套餐。
注：
未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在
未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在
Authorization请求头中传递用户JWT。
有关用户JWT的更多信息，请参阅此调用的Security部分。
安全
XsollaLoginUserJWT
路径
项目ID。您可以在发布商帐户的项目名称旁找到此参数；使用项目时，也可以在浏览器地址栏中找到此参数。URL格式如下：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
示例: 44056
查询
响应语言。符合ISO 639-1标准的两位小写语言代码（例如en）。name和description等本地化字段支持五字符区域代码（例如en-US），但在响应中会标准化为两位代码。支持的语言完整列表请参阅文档。
默认值 "en"
显示对用户不可用的时效性商品。这类商品的有效期尚未开始或已经结束。
默认值 0
示例: show_inactive_time_limited_items=1
- https://store.xsolla.com/api/v2/project/{project_id}/items/virtual_currency/package/sku/{virtual_currency_package_sku}
- Mock serverhttps://xsolla.redocly.app/_mock/zh/api/catalog/v2/project/{project_id}/items/virtual_currency/package/sku/{virtual_currency_package_sku}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://store.xsolla.com/api/v2/project/44056/items/virtual_currency/package/sku/crystal-pack?locale=en&country=US&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'已成功接收虚拟货币套餐。
商品所属分组。
与商品对应的属性及其值的列表。可用于商品目录筛选。
唯一属性ID。 external_id只能包含大小写英文字母、数字、短横线和下划线。
图片URL。
示例: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
商品价格。
虚拟价格。
虚拟货币套餐内容。
示例: [{"description":"Crystal Pack - short description","image_url":"https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png","sku":"com.xsolla.crystal_pack_1","name":"Crystal Pack","type":"virtual_currency","quantity":100}]
图片URL。
示例: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
商品限制数。
单个用户的商品购买数量限制。
content[].limits.per_user.recurrent_schedule(object or null)(catalog_recurrent_schedule_client_response)
One of:
用户的商品限制循环刷新周期。
object or null
设定商品在达到购买限制后、下次限制重置前在商品目录中的可见性。
适用于在recurrent_schedule数组中配置了周期性重置数量限制的商品。
如果未配置重置限制，则达到购买限制后，无论limit_exceeded_visibility的值如何，该商品都不会显示在商品目录中。
可能值：
show— 达到购买限制后，商品目录检索API调用仍会返回该商品。在客户端侧 商品目录检索API调用中，达到限制后返回的商品会带有can_be_bought: false标志。下一次重置日期 将在reset_next_date中返回。hide— 达到购买限制后，在限制 重置之前，商品目录检索API调用不会返回该商品。
枚举"show""hide"
应用于购物车中指定商品的促销活动。仅在以下情况下返回该数组：
为某商品配置了折扣促销活动。
应用了具有对所选商品提供折扣设置的兑换码。
如果未应用任何商品级促销活动，则返回空数组。
赠品类型。
枚举"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
商品限制数。
单个用户的商品购买数量限制。
One of:
用户的商品限制循环刷新周期。
object or null
设定商品在达到购买限制后、下次限制重置前在商品目录中的可见性。
适用于在recurrent_schedule数组中配置了周期性重置数量限制的商品。
如果未配置重置限制，则达到购买限制后，无论limit_exceeded_visibility的值如何，该商品都不会显示在商品目录中。
可能值：
show— 达到购买限制后，商品目录检索API调用仍会返回该商品。在客户端侧 商品目录检索API调用中，达到限制后返回的商品会带有can_be_bought: false标志。下一次重置日期 将在reset_next_date中返回。hide— 达到购买限制后，在限制 重置之前，商品目录检索API调用不会返回该商品。
枚举"show""hide"
商品销售期。
响应
application/json
{ "item_id": 488832, "sku": "com.xsolla.crystal_pack_1", "type": "bundle", "name": "Crystal Pack", "bundle_type": "virtual_currency_package", "description": "Crystal Pack Short Description", "image_url": "http://vc_package_image.png", "price": { "amount": "100", "amount_without_discount": "100", "currency": "USD" }, "virtual_prices": [], "can_be_bought": true, "promotions": [], "limits": { "per_user": { … }, "per_item": null }, "periods": [ { … } ], "attributes": [], "is_free": false, "groups": [], "content": [ { … } ], "vp_rewards": [], "custom_attributes": { "purchased": 0, "attr": "value" } }
请求
从指定组获取商品列表以构建商品目录。
注意
所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。
所有项目对响应中可获取的商品数量均有限制。默认值和最大值均为每个响应50个商品。如需按页获取更多数据，请使用limit和offset字段。
注：
未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在
未经授权使用此API调用时，会返回通用商品目录数据。如需获取 个性化 用户数据，例如与商品相关的数量限制和促销活动，请使用授权。为此，请在
Authorization请求头中传递用户JWT。
有关用户JWT的更多信息，请参阅此调用的Security部分。
安全
XsollaLoginUserJWT
路径
项目ID。您可以在发布商帐户的项目名称旁找到此参数；使用项目时，也可以在浏览器地址栏中找到此参数。URL格式如下：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
示例: 44056
查询
响应语言。符合ISO 639-1标准的两位小写语言代码（例如en）。name和description等本地化字段支持五字符区域代码（例如en-US），但在响应中会标准化为两位代码。支持的语言完整列表请参阅文档。
默认值 "en"
附加字段列表。如果在请求中发送这些字段，则它们将包含在响应中。
项 枚举"media_list""order""long_description""custom_attributes""item_order_in_group"
- https://store.xsolla.com/api/v2/project/{project_id}/items/virtual_items/group/{external_id}
- Mock serverhttps://xsolla.redocly.app/_mock/zh/api/catalog/v2/project/{project_id}/items/virtual_items/group/{external_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/group/weapons?limit=50&offset=0&locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'已成功接收指定组中的商品列表。
示例: [{"sku":"com.xsolla.big_rocket_1","name":"Big Rocket","groups":[{"external_id":"weapons","name":"weapons"}],"attributes":[{"external_id":"stack_size","name":"Stack size","values":[{"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":{"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"}]}],"limits":{"per_user":{"total":5,"available":3,"recurrent_schedule":{"interval_type":"weekly","reset_next_date":1746057600},"limit_exceeded_visibility":"show"},"per_item":null},"periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}]},{"sku":"com.xsolla.shotgun_raider","name":"SHOTGUN FOR TRUE RAIDERS","groups":[{"external_id":"weapons","name":{"en":"weapons"}}],"attributes":[{"external_id":"stack_size","name":"Stack size","values":[{"value":"5"}]},{"external_id":"rating","name":"Rating","values":[{"value":"3.9"}]},{"external_id":"genre","name":"Genre","values":[{"value":"Strategy"},{"value":"Tactical"},"Turn-based"]}],"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_1","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_2","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":[]}]
商品所属分组。
与商品对应的属性及其值的列表。可用于商品目录筛选。
图片URL。
示例: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
商品价格。
虚拟价格。
虚拟物品的类型。
可能值：
consumable— 使用后会从物品库中消失的商品（例如弹药）。non_consumable— 可无限期保留在物品库中的商品。non_renewing_subscription— 时效性商品，可表示在限定时间内对服务或内容的访问权限。"
枚举"consumable""non_consumable""non_renewing_subscription"
示例: "non_consumable"
应用于购物车中指定商品的促销活动。仅在以下情况下返回该数组：
为某商品配置了折扣促销活动。
应用了具有对所选商品提供折扣设置的兑换码。
如果未应用任何商品级促销活动，则返回空数组。
赠品类型。
枚举"virtual_good""virtual_currency""bundle""physical_good""game_key""nft"
商品限制数。
单个用户的商品购买数量限制。
items[].limits.per_user.recurrent_schedule(object or null)(catalog_recurrent_schedule_client_response)
One of:
用户的商品限制循环刷新周期。
object or null
设定商品在达到购买限制后、下次限制重置前在商品目录中的可见性。
适用于在recurrent_schedule数组中配置了周期性重置数量限制的商品。
如果未配置重置限制，则达到购买限制后，无论limit_exceeded_visibility的值如何，该商品都不会显示在商品目录中。
可能值：
show— 达到购买限制后，商品目录检索API调用仍会返回该商品。在客户端侧 商品目录检索API调用中，达到限制后返回的商品会带有can_be_bought: false标志。下一次重置日期 将在reset_next_date中返回。hide— 达到购买限制后，在限制 重置之前，商品目录检索API调用不会返回该商品。
枚举"show""hide"
商品销售期。
累充积分商品奖励。
响应
application/json
{ "has_more": false, "items": [ { … }, { … } ] }
概述
购物车是一种购买机制，可将多个商品合并到同一个订单中。用户可以使用真实货币购买任意类型、任意数量的商品，也可以使用兑换码。
购物车与特定用户绑定，并存储在艾克索拉侧。您可以通过两种方式识别购物车：通过用户JWT自动识别或通过购物车ID (cart_id)识别。
可在客户端侧和服务器侧管理购物车。
在服务器侧，您可以向购物车添加商品，例如在恢复用户会话时。客户端侧支持以下操作：
- 获取当前用户的购物车或按ID获取购物车
- 向购物车添加商品
- 更新购物车中的商品
- 从购物车中删除商品
如需购买购物车中的商品，请使用客户端和服务器的订单创建调用。
购物车使用场景：
- 实现商店UI，供用户选择商品。
- 当用户在商店中选择商品后，将商品加入购物车，例如使用向购物车添加商品调用。在items数组中，您需要传递SKU和所需的商品数量。
- 实现购物车查看UI。当用户进入购物车时，使用获取当前用户的购物车调用显示购物车内容。响应会返回商品最终价格信息，包括折扣和已应用的促销活动。
- 实现支付UI的打开逻辑，以便用户支付订单。例如，您可以使用创建包含指定购物车中所有商品的订单调用。响应会返回用于打开支付UI的令牌。
- 配置订单状态跟踪，例如使用Webhook，以便及时接收已成功支付商品的数据，并向用户发放商品。
注：
如需实现游戏内和线上商品销售，请参阅集成指南。
订单生命周期
了解订单生命周期有助于您跟踪订单，并正确实现购买后逻辑，例如商品交付。
订单会经历以下状态：
| 状态 | 描述 | 备注 |
new | 订单已创建。系统正在等待付款确认。 | 交易状态说明请参阅支付收银台API文档。 |
paid | 订单已支付（交易已流转至done状态），可以向用户发放商品。 | 在付款确认前，订单会保持new状态。 |
done | 商品已发放给用户。 | — |
canceled | 付款已退款。 | 当交易状态变更为refunded时，订单会流转至此状态。 |
expired | 对于限购商品、兑换码或促销活动，创建新订单时，任何包含该商品且此前未支付的订单都会流转至expired状态。只有最新订单可以付款。 | 如果用户尝试支付已过期的订单，支付UI将显示2002错误，付款将失败。 |
注：
如果用户正在完成付款时订单流转至expired状态，但付款成功，则订单会从expired流转至paid状态。仅当付款后不会超出订单中商品的购买限制时，此规则才适用。
免费商品
使用本部分中的调用向用户发放免费商品。
操作
概述
购买限制可用于限制单个用户或所有用户可购买的商品数量。您还可以配置定期重置限制。
限制存储在艾克索拉侧，可在发布商帐户中按单个商品进行配置，也可在以下API调用中通过limits对象进行配置：
在以下用于获取商品目录的API调用中，限制信息会在items.limits对象中返回：
限制组的管理部分中的API调用可用于获取限制的当前状态，并针对特定用户更新限制，例如在任务完成后重置计数器，或手动调整剩余数量。