# 管理变体与图片

> 给已有 Shoplazza 商品增删改变体与图片，并在同步价格库存时按 SKU 反查变体。

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

## 适用场景

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

## 前置条件

- 一个已完成 OAuth 授权与 token 存储的公开应用——先完成 [开发独立应用](/docs/app/getting-started/create-public-app/develop-app)。下面每个请求都带 `Access-Token: {token}` 头，使用你为每个店铺保存的 token。
- OAuth 授权时已获得 `product` 访问权限范围。
- 一个已有选项的商品（创建时设置 `has_only_default_variant: false`——见 [创建与更新商品](/docs/app/use-cases/product-merchandising/create-and-update-products)）。

### 添加变体

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

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

请求体：

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

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

```json
{
  "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"
    }
  }
}
```

完整字段见 [创建变体](/api/variant-create)。

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

### 更新或删除变体

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

请求体：

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

返回更新后的变体，在 `data.data.variant` 下。完整字段见 [更新变体](/api/variant-update)。

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

无请求体。删除变体后不返回其他数据。见 [删除变体](/api/variant-delete)。

### 按 SKU 查找变体

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

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

返回该 SKU 对应的变体列表，在 `data.data.variants` 下。见 [按 SKU 查询变体](/api/variants-by-sku)。

如需直接按 SKU 更新变体，使用 `PUT /variants/sku/{sku}`——见 [按 SKU 更新变体](/api/variant-update-by-sku)。

### 添加图片

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

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

请求体：

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

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

```json
{
  "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"
    }
  }
}
```

完整字段见 [创建商品图片](/api/product-image-create)。

如需调整图片顺序、修改 alt 文本或删除图片，使用 `PUT`/`DELETE /products/{id}/images/{image_id}`——见 [更新商品图片](/api/product-image-update) 和 [删除商品图片](/api/product-image-delete)。

### 列出与统计变体和图片

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

见 [列出变体](/api/variants)、[获取变体](/api/variant-detail)、[统计变体数量](/api/variant-count)、[列出商品图片](/api/product-images)、[获取商品图片](/api/product-image-detail) 和 [统计商品图片数量](/api/product-image-count)。

## 下一步

- [创建与更新商品](/docs/app/use-cases/product-merchandising/create-and-update-products)
- [管理库存](/docs/app/use-cases/product-merchandising/manage-inventory)