---
title: "更新商品款式"
description: "更新商品款式信息。"
doc_type: openapi
doc_category: openapi
doc_version: v20270301
source_url:
html: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/product/product-variant/update-a-variant'
md: 'https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/product/product-variant/update-a-variant.md'
---
# 更新商品款式
更新商品款式信息。
- **Base URL:** `https://{handle}.myshopline.com/admin/openapi`
- **Required Scopes:** `write_products`
- **API Version:** v20270301
- **API Type:** Admin
- **API Protocol:** RESTful
## Endpoint
```http
PUT /products/variants/:variant_id.json
```
## Base URL
* `https://{handle}.myshopline.com/admin/openapi`
* `{handle}`: `handle` ：店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001` 。
## Required Permissions
* `write_products`
## Request
### Path Parameters
* `variant_id`
string (required)
款式的唯一标识 ID。
最大长度限制：64
### Request Headers
* `Content-Type`
string (required)
字段值固定为 `application/json; charset=utf-8`。
* `Authorization`
string (required)
资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。
### Request Body
* `variant`
object
商品款式信息。
* `inventory_tracker`
boolean
表明是否开启库存追踪。
- `true`：开启库存追踪。
- `false`：不开启库存追踪。
默认值：`true`
* `option1`
string
款式第一个规格的信息。
最大长度限制：255
* `option2`
string
款式第二个规格的信息。
最大长度限制：255
* `option3`
string
款式第三个规格的信息。
最大长度限制：255
* `required_shipping`
boolean
表明款式是否需要运输。
- `true`：需要运输。
- `false`：不需要运输。
默认值：`true`
* `inventory_policy`
string
表明款式是否允许超卖。
- `deny`：不允许超卖。
- `continue`：允许超卖。
默认值: `deny`
* `price`
string
款式的售价，数值保留到小数点后两位。
默认值：`0`
* `weight`
string
款式的重量，要求大于 0，超过两位小数向上取整。
* `weight_unit`
string
款式的重量单位。有效枚举值包含：
- `g`：克
- `kg`：千克
- `lb`：磅
- `oz`：盎司
- `zh_kg`：公斤
默认值: `g`
* `compare_at_price`
string
款式的原价，数值保留到小数点后两位。
默认值: `0`
* `option4`
string
款式第四个规格的信息。
最大长度限制：255
* `option5`
string
款式第五个规格的信息。
最大长度限制：255
* `sku`
string
商家为款式自定义的标识，区别于 SHOPLINE 生成的 `variant.id`。
最大个数限制：255
* `taxable`
boolean
表明款式是否需要收税。
- `true`：需要收税。
- `false`：不需要收税。
默认值: `true`
* `barcode`
string
款式的条形码。
最大长度限制：255
* `image`
object
款式的图片。
* `alt`
string
款式图的替代文本描述，通常是具有图片特征或内容的单词或短语。
最大长度限制：512
* `id`
string
款式图的唯一标识 ID。
最大长度限制：64
* `src`
string
款式图的链接，以 URL 形式展示。
最大长度限制：255
## Response
### Status Codes
* `200`
更多状态码信息，参考 [HTTP 状态码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md?lang=zh-hans-cn)。
* `401`
* `429`
### Response Headers
* `traceId`
请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。
### Response Body
#### 200
* `variant`
object
商品款式信息。
* `barcode`
string
款式的条形码。
* `compare_at_price`
string
款式的原价，数值保留到小数点后两位。
* `inventory_item_id`
string
库存单位的唯一标识 ID。
* `inventory_tracker`
boolean
表明是否开启库存追踪。
- `true`：开启库存追踪。
- `false`：不开启库存追踪。
* `option2`
string
款式第二个规格的信息。
* `sku`
string
商家为款式自定义的标识，区别于 SHOPLINE 生成的 `variant.id`。
* `taxable`
boolean
表明款式是否需要收税。
- `true`：需要收税。
- `false`：不需要收税。
* `updated_at`
string
款式最近一次更新的时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。
* `price`
string
款式的售价，数值保留到小数点后两位。
* `weight`
string
款式的重量，超过两位小数时向上取整。
* `weight_unit`
string
款式的重量单位。有效枚举值包含：
- `g`：克
- `kg`：千克
- `lb`：磅
- `oz`：盎司
- `zh_kg`：公斤
* `option4`
string
款式第四个规格的信息。
* `option5`
string
款式第五个规格的信息。
* `created_at`
string
款式的创建时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。
* `id`
string
款式的唯一标识 ID。
* `image`
object
款式的图片。
* `alt`
string
款式图的替代文本描述，通常是具有图片特征或内容的单词或短语。
* `id`
string
款式图的唯一标识 ID。
* `src`
string
款式图的链接，以 URL 形式展示。
* `inventory_policy`
string
表明款式是否允许超卖。
- `deny`：不允许超卖。
- `continue`：允许超卖。
* `inventory_quantity`
integer
各存放地点的库存数量总和。
* `option1`
string
款式第一个规格的信息。
* `option3`
string
款式第三个规格的信息。
* `product_id`
string
款式对应商品的唯一标识 ID。
* `required_shipping`
boolean
表明款式是否需要运输。
- `true`：需要运输。
- `false`：不需要运输。
#### 401
* `errors`
string
错误描述。
#### 429
* `errors`
string
错误描述。
## OpenAPI Definition
```json
{
"tags": [
"更新商品款式"
],
"description": "更新商品款式信息。",
"externalDocs": {
"description": "接口使用的权限点: `write_products` ，更多权限点使用信息，请参考:",
"url": "ec20/3cv5d7wpfgr6a8z5/xabczf5442284vkq?lang=zh-hans-cn",
"errorTableDescription": ""
},
"operationId": "0oMgmhd1",
"parameters": [
{
"name": "variant_id",
"in": "path",
"description": "款式的唯一标识 ID。
\n最大长度限制：64",
"required": true,
"style": "simple",
"schema": {
"name": "variant_id",
"description": "款式的唯一标识 ID。
\n最大长度限制：64",
"type": "string",
"example": "18057039439794751459380282"
},
"example": "18057039439794751459380282",
"examples": {
"更新商品款式": {
"value": "18060895302863070249743144"
}
}
},
{
"name": "Content-Type",
"in": "header",
"description": "字段值固定为 `application/json; charset=utf-8`。",
"required": true,
"schema": {
"name": "Content-Type",
"type": "string",
"example": "application/json; charset=utf-8"
}
},
{
"name": "Authorization",
"in": "header",
"description": "资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。",
"required": true,
"style": "string",
"schema": {
"name": "Authorization",
"description": "资源的访问令牌。参考 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md?lang=zh-hans-cn) 获取访问令牌，然后将获取到的访问令牌以 Bearer 格式传入。",
"type": "string",
"example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
},
"example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"name": "body",
"description": "body位置参数",
"type": "object",
"properties": {
"variant": {
"name": "variant",
"description": "商品款式信息。",
"type": "object",
"properties": {
"inventory_tracker": {
"name": "inventory_tracker",
"description": "表明是否开启库存追踪。\n- `true`：开启库存追踪。\n- `false`：不开启库存追踪。\n\n默认值：`true`",
"type": "boolean"
},
"option1": {
"name": "option1",
"description": "款式第一个规格的信息。
\n最大长度限制：255",
"type": "string",
"example": "red"
},
"option2": {
"name": "option2",
"description": "款式第二个规格的信息。
\n最大长度限制：255",
"type": "string",
"example": "xl"
},
"option3": {
"name": "option3",
"description": "款式第三个规格的信息。
\n最大长度限制：255",
"type": "string",
"example": "cotton"
},
"required_shipping": {
"name": "required_shipping",
"description": "表明款式是否需要运输。\n- `true`：需要运输。\n- `false`：不需要运输。\n\n默认值：`true`",
"type": "boolean"
},
"inventory_policy": {
"name": "inventory_policy",
"description": "表明款式是否允许超卖。\n- `deny`：不允许超卖。\n- `continue`：允许超卖。\n\n默认值: `deny`",
"type": "string"
},
"price": {
"name": "price",
"description": "款式的售价，数值保留到小数点后两位。
默认值：`0`",
"type": "string",
"example": "90.22"
},
"weight": {
"name": "weight",
"description": "款式的重量，要求大于 0，超过两位小数向上取整。",
"type": "string",
"example": "0.23"
},
"weight_unit": {
"name": "weight_unit",
"description": "款式的重量单位。有效枚举值包含：\n- `g`：克\n- `kg`：千克\n- `lb`：磅\n- `oz`：盎司\n- `zh_kg`：公斤\n\n默认值: `g`",
"type": "string"
},
"compare_at_price": {
"name": "compare_at_price",
"description": "款式的原价，数值保留到小数点后两位。
默认值: `0`",
"type": "string",
"example": "129.99"
},
"option4": {
"name": "option4",
"description": "款式第四个规格的信息。
\n最大长度限制：255",
"type": "string",
"example": "short"
},
"option5": {
"name": "option5",
"description": "款式第五个规格的信息。
\n最大长度限制：255",
"type": "string",
"example": "casual"
},
"sku": {
"name": "sku",
"description": "商家为款式自定义的标识，区别于 SHOPLINE 生成的 `variant.id`。
\n最大个数限制：255",
"type": "string",
"example": "S0000001"
},
"taxable": {
"name": "taxable",
"description": "表明款式是否需要收税。\n- `true`：需要收税。\n- `false`：不需要收税。\n\n默认值: `true`",
"type": "boolean"
},
"barcode": {
"name": "barcode",
"description": "款式的条形码。
\n最大长度限制：255",
"type": "string",
"example": "T0000001"
},
"image": {
"name": "image",
"description": "款式的图片。",
"type": "object",
"properties": {
"alt": {
"name": "alt",
"description": "款式图的替代文本描述，通常是具有图片特征或内容的单词或短语。
\n最大长度限制：512",
"type": "string",
"example": "This is an image alt."
},
"id": {
"name": "id",
"description": "款式图的唯一标识 ID。
\n最大长度限制：64 ",
"type": "string",
"example": "5785060242207917075"
},
"src": {
"name": "src",
"description": "款式图的链接，以 URL 形式展示。
\n最大长度限制：255",
"type": "string",
"example": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
}
},
"example": {
"id": "5785060242207917075",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png",
"alt": "This is an image alt."
}
}
},
"example": {
"option1": "red",
"option5": "casual",
"price": "90.22",
"required_shipping": null,
"barcode": "T0000001",
"compare_at_price": "129.99",
"option4": "short",
"weight_unit": null,
"inventory_tracker": null,
"option2": "xl",
"option3": "cotton",
"sku": "S0000001",
"image": {
"id": "5785060242207917075",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png",
"alt": "This is an image alt."
},
"inventory_policy": null,
"taxable": null,
"weight": "0.23"
}
}
},
"example": {
"variant": {
"barcode": "T0000001",
"image": {
"alt": "This is an image alt.",
"id": "5785060242207917075",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
},
"option1": "red",
"option4": "short",
"required_shipping": null,
"taxable": null,
"weight_unit": null,
"compare_at_price": "129.99",
"option2": "xl",
"option3": "cotton",
"option5": "casual",
"sku": "S0000001",
"inventory_policy": null,
"inventory_tracker": null,
"price": "90.22",
"weight": "0.23"
}
}
},
"examples": {
"更新商品款式": {
"description": "更新商品款式。",
"value": {
"variant": {
"required_shipping": "true",
"sku": "S0000001",
"weight": "0.2",
"weight_unit": "kg",
"barcode": "T0000001",
"compare_at_price": "99",
"image": {
"alt": "my image alt",
"id": "6089530275430875206",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
},
"inventory_tracker": "true",
"option2": "White",
"price": "90",
"taxable": "true",
"inventory_policy": "deny",
"option1": "L"
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "更多状态码信息，参考 [HTTP 状态码](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/http-status-code.md?lang=zh-hans-cn)。",
"headers": {
"traceId": {
"description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。"
}
},
"content": {
"application/json": {
"schema": {
"name": "body",
"type": "object",
"properties": {
"variant": {
"name": "variant",
"description": "商品款式信息。",
"type": "object",
"properties": {
"barcode": {
"name": "barcode",
"description": "款式的条形码。",
"type": "string",
"example": "T00000001"
},
"compare_at_price": {
"name": "compare_at_price",
"description": "款式的原价，数值保留到小数点后两位。",
"type": "string",
"example": "129.99"
},
"inventory_item_id": {
"name": "inventory_item_id",
"description": "库存单位的唯一标识 ID。",
"type": "string",
"example": "5705499385037070868"
},
"inventory_tracker": {
"name": "inventory_tracker",
"description": "表明是否开启库存追踪。\n- `true`：开启库存追踪。\n- `false`：不开启库存追踪。",
"type": "boolean"
},
"option2": {
"name": "option2",
"description": "款式第二个规格的信息。",
"type": "string",
"example": "xl"
},
"sku": {
"name": "sku",
"description": "商家为款式自定义的标识，区别于 SHOPLINE 生成的 `variant.id`。",
"type": "string",
"example": "S00000001"
},
"taxable": {
"name": "taxable",
"description": "表明款式是否需要收税。\n- `true`：需要收税。\n- `false`：不需要收税。",
"type": "boolean"
},
"updated_at": {
"name": "updated_at",
"description": "款式最近一次更新的时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。",
"type": "string",
"example": "2025-03-06T02:20:26+08:00"
},
"price": {
"name": "price",
"description": "款式的售价，数值保留到小数点后两位。\n",
"type": "string",
"example": "90.22"
},
"weight": {
"name": "weight",
"description": "款式的重量，超过两位小数时向上取整。",
"type": "string",
"example": "0.23"
},
"weight_unit": {
"name": "weight_unit",
"description": "款式的重量单位。有效枚举值包含：\n- `g`：克\n- `kg`：千克\n- `lb`：磅\n- `oz`：盎司\n- `zh_kg`：公斤",
"type": "string"
},
"option4": {
"name": "option4",
"description": "款式第四个规格的信息。",
"type": "string",
"example": "short"
},
"option5": {
"name": "option5",
"description": "款式第五个规格的信息。",
"type": "string",
"example": "casual"
},
"created_at": {
"name": "created_at",
"description": "款式的创建时间。格式：[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)。",
"type": "string",
"example": "2025-03-06T02:20:26+08:00"
},
"id": {
"name": "id",
"description": "款式的唯一标识 ID。",
"type": "string",
"example": "18057039439794751459380282"
},
"image": {
"name": "image",
"description": "款式的图片。",
"type": "object",
"properties": {
"alt": {
"name": "alt",
"description": "款式图的替代文本描述，通常是具有图片特征或内容的单词或短语。",
"type": "string",
"example": "This is an image alt."
},
"id": {
"name": "id",
"description": "款式图的唯一标识 ID。",
"type": "string",
"example": "5785060242207917075"
},
"src": {
"name": "src",
"description": "款式图的链接，以 URL 形式展示。",
"type": "string",
"example": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
}
},
"example": {
"alt": "This is an image alt.",
"id": "5785060242207917075",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
}
},
"inventory_policy": {
"name": "inventory_policy",
"description": "表明款式是否允许超卖。\n- `deny`：不允许超卖。\n- `continue`：允许超卖。",
"type": "string"
},
"inventory_quantity": {
"name": "inventory_quantity",
"description": "各存放地点的库存数量总和。",
"type": "integer",
"example": 99
},
"option1": {
"name": "option1",
"description": "款式第一个规格的信息。",
"type": "string",
"example": "red"
},
"option3": {
"name": "option3",
"description": "款式第三个规格的信息。",
"type": "string",
"example": "cotton"
},
"product_id": {
"name": "product_id",
"description": "款式对应商品的唯一标识 ID。",
"type": "string",
"example": "16050375155238626683133099"
},
"required_shipping": {
"name": "required_shipping",
"description": "表明款式是否需要运输。\n- `true`：需要运输。\n- `false`：不需要运输。",
"type": "boolean"
}
},
"example": {
"created_at": "2025-03-06T02:20:26+08:00",
"product_id": "16050375155238626683133099",
"barcode": "T00000001",
"compare_at_price": "129.99",
"image": {
"id": "5785060242207917075",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png",
"alt": "This is an image alt."
},
"inventory_quantity": 99,
"option1": "red",
"option2": "xl",
"id": "18057039439794751459380282",
"inventory_tracker": null,
"option4": "short",
"option5": "casual",
"sku": "S00000001",
"taxable": null,
"updated_at": "2025-03-06T02:20:26+08:00",
"weight": "0.23",
"inventory_item_id": "5705499385037070868",
"inventory_policy": null,
"option3": "cotton",
"price": "90.22",
"required_shipping": null,
"weight_unit": null
}
}
},
"example": {
"variant": {
"weight": "0.23",
"inventory_quantity": 99,
"option1": "red",
"option4": "short",
"weight_unit": null,
"barcode": "T00000001",
"compare_at_price": "129.99",
"id": "18057039439794751459380282",
"inventory_item_id": "5705499385037070868",
"product_id": "16050375155238626683133099",
"taxable": null,
"created_at": "2025-03-06T02:20:26+08:00",
"inventory_policy": null,
"option3": "cotton",
"sku": "S00000001",
"image": {
"alt": "This is an image alt.",
"id": "5785060242207917075",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
},
"inventory_tracker": null,
"option2": "xl",
"option5": "casual",
"price": "90.22",
"required_shipping": null,
"updated_at": "2025-03-06T02:20:26+08:00"
}
}
},
"examples": {
"更新商品款式": {
"description": "更新商品款式。",
"value": {
"variant": {
"option1": "L",
"option2": "White",
"price": "90.00",
"compare_at_price": "99.00",
"inventory_policy": "deny",
"inventory_tracker": true,
"product_id": "16060895302856191591063144",
"sku": "S0000001",
"weight_unit": "kg",
"id": "18060895302863070249743144",
"inventory_item_id": "6089530288991379429",
"required_shipping": true,
"taxable": true,
"updated_at": "2023-08-29T15:10:42+08:00",
"weight": "0.20",
"barcode": "T0000001",
"created_at": "2023-08-29T14:59:58+08:00",
"image": {
"alt": "my image alt",
"id": "6089530275430875206",
"src": "https://img-va.myshopline.com/image/store/2001026666/1653474941510/e46e6189dd5641a3b179444cacdcdd2a_15.png?w=1024&h=1024"
}
}
}
}
}
}
}
},
"401": {
"headers": {
"traceId": {
"description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"description": "错误描述。",
"type": "string"
}
},
"required": [
"errors"
]
}
}
}
},
"429": {
"headers": {
"traceId": {
"description": "请求的全局唯一标识符。用于追踪请求在系统中的流转，以便于问题发生时进行定位和调试。"
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"description": "错误描述。",
"type": "string"
}
},
"required": [
"errors"
]
}
}
}
}
},
"security": [
{
"oauth2": []
}
],
"method": "put",
"path": "/products/variants/:variant_id.json",
"servers": [
{
"url": "https://{handle}.myshopline.com/admin/openapi",
"variables": {
"handle": {
"default": "openapiceshidianpu",
"description": "`handle` ：店铺的唯一标识符，值为店铺域名的前缀。例如，域名为 `open001.myshopline.com` 的店铺，其 `handle` 是 `open001` 。"
}
}
}
],
"info": {
"title": "更新商品款式",
"version": "v20270301"
},
"authIndexes": [
"write_products"
]
}
```