查询商品列表

API文档最后更新: 2026-08-31

6.2 查询商品列表

  • 请求方式：GET

  • 请求地址：/goods/catalog

按分类查询当前账户可以采购的商品。catalogRef 必须使用上一步分类接口返回的值。查询参数：

请求字段：

字段

位置

JSON 类型

必填

含义

page

Query

integer

否

页码，从 1 开始，默认第 1 页

pageSize

Query

integer

否

每页条数，默认 20 条，最多 100 条

catalogRef

Query

integer

是

分类接口返回的分类编号

keyword

Query

string

否

按商品名称搜索，最多 100 个字符

availability

Query

string

否

available 只查可购买商品；unavailable 只查暂不可购买商品

subscriptionState

Query

string

否

subscribed 只查已订阅商品；unsubscribed 只查未订阅商品

updatedAfter

Query

integer

否

只返回在该时间之后更新的商品，填写 10 位 Unix 秒级时间戳

返回字段：

字段

JSON 类型

必填

含义

code

integer

是

固定为 0，表示请求成功

message

string

是

本次请求的处理说明

data

object

是

商品分页查询结果

data.total

integer

是

符合条件的商品总数

data.page

integer

是

当前页码

data.pageSize

integer

是

当前每页条数

data.list

object[]

是

当前页商品数组

data.list[].productRef

integer

是

商品编号

data.list[].catalogRef

integer

是

分类编号

data.list[].title

string

是

商品名称

data.list[].price

number

是

当前接口账户购买该商品的进货价格，单位为人民币元，最多保留两位小数

data.list[].availability

string

是

available 可以购买；unavailable 暂时不能购买

data.list[].inventoryType

string

是

tracked 公开具体库存；unlimited 不限量；undisclosed 不公开库存

data.list[].remainingUnits

integer 或 null

是

tracked 时为可售数量；其他库存类型为 null

data.list[].subscriptionState

string

是

subscribed 已订阅商品通知；unsubscribed 未订阅

data.list[].subscriptionExpiresAt

integer 或 null

是

已订阅时为到期时间；未订阅时为 null

data.list[].revision

integer

是

商品最后更新时间，10 位 Unix 秒级时间戳

data.list[].updatedAt

integer

是

商品最后更新时间，10 位 Unix 秒级时间戳

requestId

string

是

本次请求编号，排查问题时提供给平台

返回示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "list": [
      {
        "productRef": 1001,
        "catalogRef": 10,
        "title": "示例充值商品",
        "price": 100.00,
        "availability": "available",
        "inventoryType": "undisclosed",
        "remainingUnits": null,
        "subscriptionState": "subscribed",
        "subscriptionExpiresAt": 1792991000,
        "revision": 1753776000,
        "updatedAt": 1753776000
      }
    ]
  },
  "requestId": "req_01K0EXAMPLE"
}

列表项返回商品编号、商品名称、price、是否可售、库存、订阅状态、订阅到期时间和数据版本。商品介绍和全部规格通过商品详情接口获取。

上一篇下一篇