创建与更新商品
使用 Open API 创建商品、更新商品字段、上架或下架商品，以及删除商品。在这里创建的商品初始状态为草稿，上架后才会在店铺前台可见。
适用场景
从你的应用发布新商品、批量导入商品目录，或搭建商品管理后台。
前置条件
- 一个已完成 OAuth 授权与 token 存储的公开应用——先完成 开发应用。下面的每个请求都带
Access-Token: {token}头，使用你为每个店铺保存的 token。 - OAuth 授权时已获得
product访问权限范围。
工作原理
商品通过一次调用构建完成：options、variants、images 都内联在同一个请求里。
- 对于带选项（如尺码、颜色）的商品，需将
has_only_default_variant设为false，声明options，并为每个变体设置与之对应的option1值——同时设置need_variant_image: false。 - 若
inventory_tracking: true，还需要传inventory_policy。 images必须包含至少一张图片。- 商品创建后初始状态为草稿，只有将
published置为true（或用auto_publish_at定时）才会上架。
创建商品
商品通过一次调用创建：请求体将所有字段嵌套在 product 下。title、has_only_default_variant、images、variants 均为必填，且每个变体都需要 price。
POST /openapi/2026-01/products
请求体：
{
"product": {
"title": "Summer cotton T-shirt",
"published": false, // 先作为草稿创建，之后再上架
"has_only_default_variant": false,
"need_variant_image": false, // has_only_default_variant 为 false 时必填
"inventory_tracking": true,
"inventory_policy": "deny", // inventory_tracking 为 true 时必填
"options": [{ "name": "Size", "values": ["S", "M"] }],
"images": [{ "src": "https://cdn.example.com/tshirt.jpg" }], // 至少一张图片
"variants": [
{ "option1": "S", "price": 19.9, "sku": "TS-S", "inventory_quantity": 100, "position": 1 },
{ "option1": "M", "price": 19.9, "sku": "TS-M", "inventory_quantity": 100, "position": 2 }
]
}
}
响应（节选，创建的商品在 data.data.product 下）：
{
"code": "Success",
"data": {
"product": {
"id": "4d3e7859-455c-4899-a296-7befe731c585",
"title": "Summer cotton T-shirt",
"handle": "summer-cotton-t-shirt",
"inventory_tracking": true,
"inventory_policy": "deny",
"options": [
{ "id": "bca26b9d-c3f1-48ac-93aa-e4a975c44dce", "name": "Size", "values": ["S", "M"], "position": 1 }
],
"variants": [
{ "id": "28ea5ee4-5b1d-4a9d-a92e-e60f0dff3da8", "title": "S", "option1": "S", "position": 1, "price": 19.9, "sku": "TS-S", "inventory_quantity": 100 }
],
"price_min": 19.9,
"price_max": 19.9,
"created_at": "2026-07-02T02:57:25Z",
"updated_at": "2026-07-02T02:57:25Z"
}
}
}
images 必须包含至少一项——传空数组会被拒绝，返回 value must contain at least 1 item(s)。请把图片托管到可公开访问的地址，并将该 URL 作为 src 传入。完整请求体见 创建商品。
获取商品
按 id 获取单个商品。
GET /openapi/2026-01/products/{id}
响应（节选）：完整商品对象，包含 options[]、images[]、variants[]、primary_image，以及 id、title、handle、inventory_tracking、inventory_policy、price_min、price_max、created_at、updated_at。
完整字段见 获取商品。
更新商品
使用 PUT 修改商品级字段（标题、描述、标签等）。只有你传入的字段会被修改。
PUT /openapi/2026-01/products/{id}
请求体：
{
"product": {
"title": "Summer cotton T-shirt (2026)" // 只传要改的字段
}
}
返回更新后的商品。可编辑字段详见 更新商品 参考文档。
上架与下架
上架本质上就是设置 published 字段。设为 true 使商品在店铺前台可见，设为 false 则重新隐藏——两个方向用的是同一个 PUT 接口。
PUT /openapi/2026-01/products/{id}
请求体：
{
"product": {
"published": true // 传 false 即可下架
}
}
响应（节选，与创建响应结构相同，published_at 已填上具体时间）：
{
"code": "Success",
"data": {
"product": {
"id": "4d3e7859-455c-4899-a296-7befe731c585",
"title": "Summer cotton T-shirt",
"published": true,
"published_at": "2026-07-02T02:58:55Z"
}
}
}
上架后，可以通过 https://<shop>/products/<handle> 在店铺前台访问该商品。
如需定时上架，可在创建或更新时设置 auto_publish_at（RFC 3339 格式）。如需在售罄时自动下架，设置 inventory_policy: auto_unpublished。详见 创建商品。
删除商品
DELETE /openapi/2026-01/products/{id}
响应：
{ "code": "Success", "data": {} }
见 删除商品。
如需批量删除，使用 DELETE /products?product_ids=id1,id2——见 批量删除商品。
列出商品
列表接口使用游标分页（cursor 配合 per_page，最大 250），并支持 title、collection_id、published_status 等过滤条件。
GET /openapi/2026-01/products
响应（节选，列表在 data.data.products 下，游标在 data.data.cursor 下）：
{
"code": "Success",
"data": {
"cursor": "MjAyNi0wMS0yM1QxMDowODoyN1o...",
"products": [
{
"id": "ac7783d3-df2d-47fe-abca-7ee3d9bceb04",
"title": "T-shirt",
"handle": "t-shirt",
"inventory_quantity": 666,
"price_min": 11,
"price_max": 33,
"created_at": "2026-07-01T09:25:50Z"
}
]
}
}
完整过滤条件见 商品列表。
只需要总数时，用 GET /products/count——见 统计商品数量。