跳到主要内容

管理变体与图片

为已有商品添加变体与图片，并支持按 SKU 查找变体——在从外部系统同步价格和库存时很有用。

适用场景​

在商品创建之后新增尺码或颜色、调整价格或库存、更换图片，或将你自己的 SKU 与 Shoplazza 变体做匹配。

前置条件​

  • 一个已完成 OAuth 授权与 token 存储的公开应用——先完成 开发应用。下面每个请求都带 Access-Token: {token} 头，使用你为每个店铺保存的 token。
  • OAuth 授权时已获得 product 访问权限范围。
  • 一个已有选项的商品（创建时设置 has_only_default_variant: false——见 创建与更新商品）。

添加变体​

为已有选项的商品添加一个变体。price 和 position 为必填；option1 是新变体对应的选项值。

POST /openapi/2026-01/products/{id}/variants

请求体：

{
  "variant": {
    "option1": "L",              // 需匹配商品已声明选项中的一个值
    "price": 19.9,
    "sku": "TS-L",
    "inventory_quantity": 100,
    "position": 3
  }
}

响应（节选，新变体在 data.data.variant 下）：

{
  "code": "Success",
  "data": {
    "variant": {
      "id": "d47c9f04-ae67-4480-a092-08945767ce4a",
      "product_id": "4d3e7859-455c-4899-a296-7befe731c585",
      "title": "L",
      "option1": "L",
      "position": 3,
      "price": 19.9,
      "sku": "TS-L",
      "inventory_quantity": 100,
      "created_at": "2026-07-02T02:58:01Z",
      "updated_at": "2026-07-02T02:58:01Z"
    }
  }
}

完整字段见 创建变体。

注意

只能给已有选项（has_only_default_variant: false）的商品添加变体。对单变体商品调用此接口会失败，返回 "At least a single variant is included in the product."（商品至少包含一个变体）。请在创建商品时就定义好变体，或先对商品结构做调整。

更新或删除变体​

PUT /openapi/2026-01/variants/{id}

请求体：

{
  "variant": {
    "price": 24.9 // 只传要改的字段
  }
}

返回更新后的变体，在 data.data.variant 下。完整字段见 更新变体。

DELETE /openapi/2026-01/products/{id}/variants/{vid}

无请求体。删除变体后不返回其他数据。见 删除变体。

按 SKU 查找变体​

当外部系统以 SKU 作为主键时，可以在不知道变体 id 的情况下直接解析出对应变体。

GET /openapi/2026-01/products/sku/{sku}/variants

返回该 SKU 对应的变体列表，在 data.data.variants 下。见 按 SKU 查询变体。

如需直接按 SKU 更新变体，使用 PUT /variants/sku/{sku}——见 按 SKU 更新变体。

添加图片​

图片归属于商品。发起添加图片的请求会将其追加到图库中（不会替换已有图片）。src 为可公开访问的图片 URL。

POST /openapi/2026-01/products/{id}/images

请求体：

{
  "image": {
    "src": "https://cdn.example.com/tshirt-back.jpg" // 可公开访问的图片 URL
  }
}

响应（节选，新图片在 data.data.image 下）：

{
  "code": "Success",
  "data": {
    "image": {
      "id": "6c7d7bad-a4fe-48c3-95e5-51a36f20622f",
      "product_id": "4d3e7859-455c-4899-a296-7befe731c585",
      "position": 2,
      "src": "//cdn.example.com/tshirt-back.jpg",
      "created_at": "2026-07-02T02:58:13Z",
      "updated_at": "2026-07-02T02:58:13Z"
    }
  }
}

完整字段见 创建商品图片。

如需调整图片顺序、修改 alt 文本或删除图片，使用 PUT/DELETE /products/{id}/images/{image_id}——见 更新商品图片 和 删除商品图片。

列出与统计变体和图片​

用 GET /products/{id}/variants 列出商品的变体，或用 GET /variants/{id} 获取单个；图片同理，用 GET /products/{id}/images 列出。两者都各有一个计数端点。

见 列出变体、获取变体、统计变体数量、列出商品图片、获取商品图片 和 统计商品图片数量。

下一步​