查询商品列表

GET 
/openapi/2025-06/products

分页获取商品列表。

请求

Query参数

ids string[]

商品 ID 列表。 示例：?ids=1001&ids=1002

title string

商品名称

collection_id string

专辑 UUID，例如：9e79ca1f-9ff2-409b-976f-98be343d38a3

created_at_min string

筛选创建时间不早于该时间点的商品，例如：2018-10-01T16:15:47-04:00

created_at_max string

筛选创建时间不晚于该时间点的商品，例如：2018-10-01T16:15:47-04:00

updated_at_min string

筛选最后更新时间不早于该时间点的商品，例如：2018-10-01T16:15:47-04:00

updated_at_max string

筛选最后更新时间不晚于该时间点的商品，例如：2018-10-01T16:15:47-04:00

published_at_min string

筛选上架时间不早于该时间点的商品，例如：2018-10-01T16:15:47-04:00

published_at_max string

筛选上架时间不晚于该时间点的商品，例如：2018-10-01T16:15:47-04:00

published_status string

按上架状态筛选，可选值：published（已上架）、unpublished（未上架）、any（全部）

spus string[]

商品 SPU 列表，多个值之间使用英文逗号分隔，例如：spu1,spu2

pre_cursor string

上一页游标，参考基于游标的分页

cursor string

分页游标，参考基于游标的分页

per_page int32

每页记录数，最大 250

fields string[]

指定响应中需要返回的字段列表。 示例：?fields=id&fields=title

sort_direction string

排序方向，可选值：desc（降序）、asc（升序）

exclude_ids string[]

需要排除的商品 ID 列表，例如：product_id1,product_id2

product_type string

按商品类型筛选，可选值：all（全部）、default（普通商品）、gift_card（礼品卡）；为空时返回所有商品

product_behaviour string

商品行为筛选，可选值：hidden（隐藏商品）；为空时返回所有商品

location_id uint64

按库存所在位置 ID 筛选

vendors string[]

按商品供应商筛选（精确匹配）。 示例：?vendors=Nike&vendors=Adidas

vendors_match string[]

按商品供应商进行模糊匹配筛选。 示例：?vendors_match=Nik&vendors_match=Adid

handles string[]

按商品 handle 列表筛选。 示例：?handles=t-shirt&handles=hoodie

响应

200

OK

application/json

数据结构

数据结构

codestring

错误码

messagestring

错误信息

data object
cursorstring
下一页游标，参考基于游标的分页
pre_cursorstring
上一页游标，参考基于游标的分页
products object[]
商品列表
Array [
idstring
商品 ID
titlestring
商品名称
descriptionstring
商品描述
publishedboolean
商品是否已上架
requires_shippingboolean
商品是否需要物流
taxableboolean
商品是否需要计税
tagsstring[]
商品标签列表
vendorstring
供应商名称
vendor_urlstring
供应商 URL
notestring
自定义备注，例如："This is a customizable product"
seo_titlestring
SEO 标题
seo_descriptionstring
SEO 描述
seo_keywordsstring[]
SEO 关键词列表
handlestring
商品 handle（用于 URL 的友好别名）
has_only_default_variantboolean
是否仅有默认款式（即无多款式）
inventory_trackingboolean
是否启用库存追踪
inventory_policystring
库存策略，可选值：continue（缺货时继续销售）、deny（缺货时停止销售）、auto_unpublished（缺货时自动下架）；当 inventory_tracking 为 true 时必填
need_variant_imageboolean
是否需要为款式设置图片；当 has_only_default_variant 为 false 时必填
spustring
商品 SPU（标准产品单元）
fake_salesint64
商品虚拟销量
display_fake_salesboolean
是否在前台展示虚拟销量
options object[]
商品款式属性列表（如颜色、尺寸等）
Array [
idstring
款式属性 ID
namestring
款式属性名称，例如："color"、"size"
valuesstring[]
款式属性的可选值列表，例如：["red", "black"]、["small", "large"]
positionint64
款式属性排序位置
]
images object[]
商品图片列表
Array [
idstring
图片 ID
srcstring
图片 URL
widthint32
图片宽度（单位：像素）
heightint32
图片高度（单位：像素）
altstring
图片替代文本（alt）
positionint64
图片排序位置
pathstring
图片存储路径
]
variants object[]
商品子款式列表
Array [
idstring
子款式 ID
product_idstring
子款式所属商品的 ID
image_idstring
子款式关联的图片 ID
created_atstring
子款式创建时间
updated_atstring
子款式最后更新时间
titlestring
子款式标题
option1string
子款式在第 1 个商品款式属性上的取值
option2string
子款式在第 2 个商品款式属性上的取值
option3string
子款式在第 3 个商品款式属性上的取值
image object
子款式图片
srcstring
图片 URL
widthint32
图片宽度（单位：像素）
heightint32
图片高度（单位：像素）
altstring
图片替代文本（alt）
pathstring
图片存储路径
positionint64
子款式在商品中的排序位置
compare_at_pricedouble
划线价
pricedouble
子款式售价
skustring
SKU
barcodestring
条形码
notestring
款式备注
inventory_quantityint64
库存数量
weightdouble
重量
weight_unitstring
重量单位，可选值：kg、g、lb、oz
cost_pricedouble
成本价
whole_prices object[]
批发价列表
Array [
pricedouble必填
批发价
min_quantityint64必填
起购量（达到该数量才适用此批发价）
]
retail_pricedouble
零售价
is_discountboolean
子款式当前是否处于打折状态
origin_pricedouble
原价
extend object
子款式扩展信息（包裹尺寸、原产地国别、HS 代码等）
lengthdouble
包裹长度
widthdouble
包裹宽度
heightdouble
包裹高度
dimension_unitstring
尺寸单位，可选值：cm、in、mm
origin_country_codestring
原产地国别（国家代码，例如 CN、US）
hs_codestring
HS（协调制度）代码
]
mixed_wholesaleboolean
是否支持混批
product_typestring
商品类型
brandstring
品牌
briefstring
商品简介
inventory_quantityint64
库存数量
price_mindouble
各子款式售价中的最低价
price_maxdouble
各子款式售价中的最高价
compare_at_price_mindouble
各子款式划线价中的最低价
compare_at_price_maxdouble
各子款式划线价中的最高价
published_atstring
商品上架时间
created_atstring
商品创建时间
updated_atstring
商品最后更新时间
salesint64
商品实际销量
independent_seoboolean
是否启用独立的 SEO 设置
urlstring
商品访问 URL
availableboolean
商品是否可售
retail_price_mindouble
各子款式零售价中的最低价
retail_price_maxdouble
各子款式零售价中的最高价
origin_price_mindouble
各子款式原价中的最低价
origin_price_maxdouble
各子款式原价中的最高价
primary_image object
商品主图
srcstring
图片 URL
widthint32
图片宽度（单位：像素）
heightint32
图片高度（单位：像素）
altstring
图片替代文本（alt）
pathstring
图片存储路径
tax_codestring
商品税码
category_idstring
商品所属分类 ID
category object
商品所属分类信息
iduint64
分类 ID
namestring
分类名称
google_idint64
Google 分类 ID
levelint32
分类层级
pathstring
分类层级路径
]

示例

{
  "code": "string",
  "message": "string",
  "data": {
    "cursor": "string",
    "pre_cursor": "string",
    "products": [
      {
        "id": "string",
        "title": "string",
        "description": "string",
        "published": true,
        "requires_shipping": true,
        "taxable": true,
        "tags": [
          "string"
        ],
        "vendor": "string",
        "vendor_url": "string",
        "note": "string",
        "seo_title": "string",
        "seo_description": "string",
        "seo_keywords": [
          "string"
        ],
        "handle": "string",
        "has_only_default_variant": true,
        "inventory_tracking": true,
        "inventory_policy": "string",
        "need_variant_image": true,
        "spu": "string",
        "fake_sales": 0,
        "display_fake_sales": true,
        "options": [
          {
            "id": "string",
            "name": "string",
            "values": [
              "string"
            ],
            "position": 0
          }
        ],
        "images": [
          {
            "id": "string",
            "src": "string",
            "width": 0,
            "height": 0,
            "alt": "string",
            "position": 0,
            "path": "string"
          }
        ],
        "variants": [
          {
            "id": "string",
            "product_id": "string",
            "image_id": "string",
            "created_at": "string",
            "updated_at": "string",
            "title": "string",
            "option1": "string",
            "option2": "string",
            "option3": "string",
            "image": {
              "src": "string",
              "width": 0,
              "height": 0,
              "alt": "string",
              "path": "string"
            },
            "position": 0,
            "compare_at_price": 0,
            "price": 0,
            "sku": "string",
            "barcode": "string",
            "note": "string",
            "inventory_quantity": 0,
            "weight": 0,
            "weight_unit": "string",
            "cost_price": 0,
            "whole_prices": [
              {
                "price": 0,
                "min_quantity": 0
              }
            ],
            "retail_price": 0,
            "is_discount": true,
            "origin_price": 0,
            "extend": {
              "length": 0,
              "width": 0,
              "height": 0,
              "dimension_unit": "string",
              "origin_country_code": "string",
              "hs_code": "string"
            }
          }
        ],
        "mixed_wholesale": true,
        "product_type": "string",
        "brand": "string",
        "brief": "string",
        "inventory_quantity": 0,
        "price_min": 0,
        "price_max": 0,
        "compare_at_price_min": 0,
        "compare_at_price_max": 0,
        "published_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "sales": 0,
        "independent_seo": true,
        "url": "string",
        "available": true,
        "retail_price_min": 0,
        "retail_price_max": 0,
        "origin_price_min": 0,
        "origin_price_max": 0,
        "primary_image": {
          "src": "string",
          "width": 0,
          "height": 0,
          "alt": "string",
          "path": "string"
        },
        "tax_code": "string",
        "category_id": "string",
        "category": {
          "id": 0,
          "name": "string",
          "google_id": 0,
          "level": 0,
          "path": "string"
        }
      }
    ]
  }
}