**版本：202601**

# 更新子款式

**PUT** `/openapi/2026-01/variants/:variant_id`

根据提供的信息更新已有的子款式。

## 请求

**Path参数**

- `variant_id` string (required)

  待更新的子款式 ID

**application/json**

**请求体 | 示例**

**请求体 (required)**

- `variant` object (required)

  待更新的子款式数据

  - `option1` string

    商品款式属性 1 的取值（例如"颜色"取值"红色"）
  - `option2` string

    商品款式属性 2 的取值
  - `option3` string

    商品款式属性 3 的取值
  - `image_id` string

    子款式关联的图片 ID
  - `image` object

    子款式图片对象；当商品的 `need_variant_image` 字段为 `true` 时必填

    - `src` string (required)

      图片 URL
    - `width` int32

      图片宽度（单位：像素）
    - `height` int32

      图片高度（单位：像素）
    - `alt` string

      图片替代文本（alt）
    - `path` string

      图片存储路径
  - `compare_at_price` double

    划线价
  - `price` double (required)

    子款式售价；如需留空请设置为 "0.00"
  - `sku` string

    SKU
  - `barcode` string

    条形码
  - `note` string

    款式备注/说明
  - `inventory_quantity` int64

    库存数量
  - `weight` double

    重量
  - `weight_unit` string

    重量单位，可选值：`kg`、`g`、`lb`、`oz`
  - `cost_price` double

    成本价
  - `wholesale_price` object[]

    批发价列表

    *   Array \[

    - `price` double

      批发价
    - `min_quantity` int64

      起购量（达到该数量才适用此批发价）
    *   \]
  - `whole_prices` object[]

    批发价列表。已废弃，等价于 `wholesale_price`；两者同时传时以 `wholesale_price` 为准。

    *   Array \[

    - `price` double

      批发价
    - `min_quantity` int64

      起购量（达到该数量才适用此批发价）
    *   \]
  - `retail_price` double

    零售价
  - `position` int64

    子款式在列表中的排序位置
  - `extend` object

    子款式扩展信息（包裹尺寸、原产地国别、HS 代码等）

    - `length` double

      包裹长度
    - `width` double

      包裹宽度
    - `height` double

      包裹高度
    - `dimension_unit` string

      尺寸单位，可选值：`cm`、`in`、`mm`
    - `origin_country_code` string

      原产地国别（国家代码，例如 `CN`、`US`）
    - `hs_code` string

      HS（协调制度）代码

```json
{
  "variant": {
    "option1": "string",
    "option2": "string",
    "option3": "string",
    "image_id": "string",
    "image": {
      "src": "string",
      "width": 0,
      "height": 0,
      "alt": "string",
      "path": "string"
    },
    "compare_at_price": 0,
    "price": 0,
    "sku": "string",
    "barcode": "string",
    "note": "string",
    "inventory_quantity": 0,
    "weight": 0,
    "weight_unit": "string",
    "cost_price": 0,
    "wholesale_price": [
      {
        "price": 0,
        "min_quantity": 0
      }
    ],
    "whole_prices": [
      {
        "price": 0,
        "min_quantity": 0
      }
    ],
    "retail_price": 0,
    "position": 0,
    "extend": {
      "length": 0,
      "width": 0,
      "height": 0,
      "dimension_unit": "string",
      "origin_country_code": "string",
      "hs_code": "string"
    }
  }
}
```

## 响应

**200**

OK

**application/json**

**数据结构 | 示例**

**数据结构**

- `code` string

  错误码
- `message` string

  错误信息
- `data` object

  - `variant` object

    已更新的子款式

    - `id` string

      子款式 ID
    - `product_id` string

      子款式所属商品的 ID
    - `image_id` string

      子款式关联的图片 ID
    - `created_at` string

      子款式创建时间
    - `updated_at` string

      子款式最后更新时间
    - `title` string

      子款式标题
    - `option1` string

      子款式在第 1 个商品款式属性上的取值
    - `option2` string

      子款式在第 2 个商品款式属性上的取值
    - `option3` string

      子款式在第 3 个商品款式属性上的取值
    - `image` object

      子款式图片

      - `src` string

        图片 URL
      - `width` int32

        图片宽度（单位：像素）
      - `height` int32

        图片高度（单位：像素）
      - `alt` string

        图片替代文本（alt）
      - `path` string

        图片存储路径
    - `position` int64

      子款式在商品中的排序位置
    - `compare_at_price` double

      划线价
    - `price` double

      子款式售价
    - `sku` string

      SKU
    - `barcode` string

      条形码
    - `note` string

      款式备注
    - `inventory_quantity` int64

      库存数量
    - `weight` double

      重量
    - `weight_unit` string

      重量单位，可选值：`kg`、`g`、`lb`、`oz`
    - `cost_price` double

      成本价
    - `wholesale_price` object[]

      批发价列表

      *   Array \[

      - `price` double (required)

        批发价
      - `min_quantity` int64 (required)

        起购量（达到该数量才适用此批发价）
      *   \]
    - `whole_prices` object[]

      批发价列表。已废弃，等价于 `wholesale_price`，两者返回相同内容。

      *   Array \[

      - `price` double (required)

        批发价
      - `min_quantity` int64 (required)

        起购量（达到该数量才适用此批发价）
      *   \]
    - `retail_price` double

      零售价
    - `is_discount` boolean

      子款式当前是否处于打折状态
    - `origin_price` double

      原价
    - `extend` object

      子款式扩展信息（包裹尺寸、原产地国别、HS 代码等）

      - `length` double

        包裹长度
      - `width` double

        包裹宽度
      - `height` double

        包裹高度
      - `dimension_unit` string

        尺寸单位，可选值：`cm`、`in`、`mm`
      - `origin_country_code` string

        原产地国别（国家代码，例如 `CN`、`US`）
      - `hs_code` string

        HS（协调制度）代码

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "variant": {
      "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,
      "wholesale_price": [
        {
          "price": 0,
          "min_quantity": 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"
      }
    }
  }
}
```