---
title: "Create a variant"
description: "Create a variant for the specified product."
doc_type: openapi
doc_category: openapi
doc_version: v20270301
source_url:
html: 'https://developer.shopline.com/docs/admin-rest-api/product/product-variant/create-a-variant'
md: 'https://developer.shopline.com/docs/admin-rest-api/product/product-variant/create-a-variant.md'
---
# Create a variant
Create a variant for the specified product.
- **Base URL:** `https://{handle}.myshopline.com/admin/openapi`
- **Required Scopes:** `write_products`
- **API Version:** v20270301
- **API Type:** Admin
- **API Protocol:** RESTful
## Endpoint
```http
POST /products/:product_id/variants.json
```
## Base URL
* `https://{handle}.myshopline.com/admin/openapi`
* `{handle}`: `handle` : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is `open001.myshopline.com` , the store handle is `open001` .
## Required Permissions
* `write_products`
## Request
### Path Parameters
* `product_id`
string (required)
The unique identifier for the product.
Maximum length：64
### Request Headers
* `Content-Type`
string (required)
The field must be set to the fixed value `application/json; charset=utf-8`.
* `Authorization`
string (required)
The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format.
### Request Body
* `variant`
object
Variant information.
* `compare_at_price`
string
The original price of the variant. The value is rounded to two decimal places.
Default value: `0`
* `image`
object
The image of the variant.
* `alt`
string
The alternative textual description of the variant image, usually a word or phrase with the characteristics or content of the image.
Maximum length: 512
* `id`
string
The unique identifier for the variant image.
Maximum length：64
* `src`
string
The link to the variant image, represented as a URL.
Maximum length: 255
* `inventory_policy`
string
Indicates whether the variant is allowed to be oversold.
- `deny`: overselling not allowed
- `continue`: overselling allowed
Default value: `deny`
* `required_shipping`
boolean
Indicates whether the variant is required to be shipped.
- `true`: Shipping is required.
- `false`: Shipping is not required.
Default value: `true`
* `option2`
string
Information of the second option of the variant.
Maximum length: 255
* `option5`
string
Information of the fifth option of the variant.
Maximum length: 255
* `taxable`
boolean
Indicates whether the variant is subject to tax.
- `true`: Tax is required.
- `false`: Tax is not required.
Default value: `true`
* `weight`
string
The weight of the variant. The value is required to be greater than `0`，and rounded to two decimal places.
* `barcode`
string
The barcode of the variant.
Maximum length: 255
* `option1`
string
Information of the first option of the variant.
Maximum length: 255
* `option3`
string
Information of the third option of the variant.
Maximum length: 255
* `option4`
string
Information of the fourth option of the variant.
Maximum length: 255
* `weight_unit`
string
The unit of weight for the variant. Valid values are:
- `g`: gram
- `kg`: kilogram
- `lb`: pound
- `oz`: ounce
- `zh_kg`: kilogram
Default value: `g`
* `inventory_tracker`
boolean
Indicates whether the inventory tracking is enabled.
- ` true`: Inventory tracking is enabled.
- ` false`: Inventory tracking is not enabled.
Default value: `true`
* `price`
string
The selling price of the variant. The value is rounded to two decimal places.
Default value: `0`
* `sku`
string
The product SKU. It is distinct from `variant.id` returned by SHOPLINE.
Maximum size: 255
## Response
### Status Codes
* `200`
For the complete list of codes and messages, see [Http status code](https://developer.shopline.com/docs/apps/api-instructions-for-use/http-status-code.md?lang=en).
* `201`
* `401`
* `429`
### Response Headers
* `traceId`
A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise.
### Response Body
#### 200
* `variant`
object
Variant information.
* `barcode`
string
The barcode of the variant.
* `created_at`
string
The creation date and time of the product variant. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).
* `id`
string
The unique identifier for the variant.
* `image`
object
The image of the variant.
* `alt`
string
The alternative textual description of the variant image, usually a word or phrase with the characteristics or content of the image.
* `id`
string
The unique identifier for the variant image.
* `src`
string
The link to the variant image, represented as a URL.
* `option3`
string
Information of the third option of the variant.
* `option5`
string
Information of the fifth option of the variant.
* `required_shipping`
boolean
Indicates whether the variant is required to be shipped.
- `true`: Shipping is required.
- `false`: Shipping is not required.
* `weight_unit`
string
The unit of weight for the variant. Valid values are:
- `g`: gram
- `kg`: kilogram
- `lb`: pound
- `oz`: ounce
- `zh_kg`: kilogram
* `option1`
string
Information of the first option of the variant.
* `option4`
string
Information of the fourth option of the variant.
* `price`
string
The selling price of the variant. The value is rounded to two decimal places.
* `compare_at_price`
string
The original price of the variant. The value is rounded to two decimal places.
* `inventory_item_id`
string
The unique identifier for the inventory item.
* `inventory_policy`
string
Indicates whether the variant is allowed to be oversold.
- `deny`: overselling not allowed
- `continue`: overselling allowed
* `inventory_quantity`
integer
The total inventory quantity at all storage locations.
* `option2`
string
Information of the second option of the variant.
* `taxable`
boolean
Indicates whether the variant is subject to tax.
- `true`: Tax is required.
- `false`: Tax is not required.
* `updated_at`
string
The date and time when the variant was last updated. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).
* `inventory_tracker`
boolean
Indicates whether the inventory tracking is enabled.
- ` true`: Inventory tracking is enabled.
- ` false`: Inventory tracking is not enabled.
* `product_id`
string
The unique identifier for the product corresponding to the variant.
* `sku`
string
The product SKU. It is distinct from `variant.id` returned by SHOPLINE.
* `weight`
string
The weight of the variant. The value is rounded up if it exceeds two decimal places.
#### 201
* `errors`
string
Error message.
#### 401
* `errors`
string
Error message.
#### 429
* `errors`
string
Error message.
## OpenAPI Definition
```json
{
"tags": [
"Create a variant"
],
"description": "Create a variant for the specified product. ",
"externalDocs": {
"description": "Permission point used by the interface is `write_products` , For more information about the use of permission points, see",
"url": "ec20/3cv5d7wpfgr6a8z5/xabczf5442284vkq?lang=en",
"errorTableDescription": ""
},
"operationId": "zYmEnSCX",
"parameters": [
{
"name": "product_id",
"in": "path",
"description": "The unique identifier for the product.
\nMaximum length：64 ",
"required": true,
"style": "simple",
"schema": {
"name": "product_id",
"description": "The unique identifier for the product.
\nMaximum length：64 ",
"type": "string",
"example": "16057039432335097907370282"
},
"example": "16057039432335097907370282",
"examples": {
"Create a variant": {
"value": "16060895302856191591063144"
}
}
},
{
"name": "Content-Type",
"in": "header",
"description": "The field must be set to the fixed value `application/json; charset=utf-8`.",
"required": true,
"schema": {
"name": "Content-Type",
"type": "string",
"example": "application/json; charset=utf-8"
}
},
{
"name": "Authorization",
"in": "header",
"description": " The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. ",
"required": true,
"style": "string",
"schema": {
"name": "Authorization",
"description": " The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. ",
"type": "string",
"example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
},
"example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"name": "body",
"description": "Body location parameters",
"type": "object",
"properties": {
"variant": {
"name": "variant",
"description": "Variant information.",
"type": "object",
"properties": {
"compare_at_price": {
"name": "compare_at_price",
"description": "The original price of the variant. The value is rounded to two decimal places.
Default value: `0`",
"type": "string",
"example": "129.99"
},
"image": {
"name": "image",
"description": "The image of the variant.",
"type": "object",
"properties": {
"alt": {
"name": "alt",
"description": "The alternative textual description of the variant image, usually a word or phrase with the characteristics or content of the image.
\nMaximum length: 512",
"type": "string",
"example": "This is an image alt"
},
"id": {
"name": "id",
"description": "The unique identifier for the variant image.
\nMaximum length：64 ",
"type": "string",
"example": "5759070976424132652"
},
"src": {
"name": "src",
"description": "The link to the variant image, represented as a URL.
\nMaximum length: 255",
"type": "string",
"example": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
}
},
"example": {
"alt": "This is an image alt",
"id": "5759070976424132652",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
}
},
"inventory_policy": {
"name": "inventory_policy",
"description": "Indicates whether the variant is allowed to be oversold.\n- `deny`: overselling not allowed\n- `continue`: overselling allowed\n\nDefault value: `deny`",
"type": "string"
},
"required_shipping": {
"name": "required_shipping",
"description": "Indicates whether the variant is required to be shipped.\n- `true`: Shipping is required.\n- `false`: Shipping is not required.\n\nDefault value: `true`",
"type": "boolean"
},
"option2": {
"name": "option2",
"description": "Information of the second option of the variant.
\nMaximum length: 255",
"type": "string",
"example": "xl"
},
"option5": {
"name": "option5",
"description": "Information of the fifth option of the variant.
\nMaximum length: 255",
"type": "string",
"example": "red"
},
"taxable": {
"name": "taxable",
"description": "Indicates whether the variant is subject to tax.\n- `true`: Tax is required.\n- `false`: Tax is not required.\n\nDefault value: `true`",
"type": "boolean"
},
"weight": {
"name": "weight",
"description": "The weight of the variant. The value is required to be greater than `0`，and rounded to two decimal places. ",
"type": "string",
"example": "0.23"
},
"barcode": {
"name": "barcode",
"description": "The barcode of the variant.
\nMaximum length: 255",
"type": "string",
"example": "T0000001"
},
"option1": {
"name": "option1",
"description": "Information of the first option of the variant.
\nMaximum length: 255",
"type": "string",
"example": "red"
},
"option3": {
"name": "option3",
"description": "Information of the third option of the variant.
\nMaximum length: 255",
"type": "string",
"example": "cotton"
},
"option4": {
"name": "option4",
"description": "Information of the fourth option of the variant.
\nMaximum length: 255",
"type": "string",
"example": "short"
},
"weight_unit": {
"name": "weight_unit",
"description": "The unit of weight for the variant. Valid values are:\n- `g`: gram\n- `kg`: kilogram\n- `lb`: pound\n- `oz`: ounce\n- `zh_kg`: kilogram\n\nDefault value: `g`",
"type": "string"
},
"inventory_tracker": {
"name": "inventory_tracker",
"description": "Indicates whether the inventory tracking is enabled.\n- ` true`: Inventory tracking is enabled.\n- ` false`: Inventory tracking is not enabled.\n\nDefault value: `true`",
"type": "boolean"
},
"price": {
"name": "price",
"description": "The selling price of the variant. The value is rounded to two decimal places.
Default value: `0`",
"type": "string",
"example": "90.22"
},
"sku": {
"name": "sku",
"description": "The product SKU. It is distinct from `variant.id` returned by SHOPLINE.
\nMaximum size: 255",
"type": "string",
"example": "S0000001"
}
},
"example": {
"option2": "xl",
"barcode": "T0000001",
"compare_at_price": "129.99",
"option1": "red",
"option3": "cotton",
"option4": "short",
"weight": "0.23",
"image": {
"alt": "This is an image alt",
"id": "5759070976424132652",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
},
"inventory_policy": null,
"inventory_tracker": null,
"price": "90.22",
"required_shipping": null,
"sku": "S0000001",
"taxable": null,
"option5": "red",
"weight_unit": null
}
}
},
"example": {
"variant": {
"inventory_policy": null,
"option5": "red",
"price": "90.22",
"compare_at_price": "129.99",
"option4": "short",
"required_shipping": null,
"weight_unit": null,
"barcode": "T0000001",
"option1": "red",
"option3": "cotton",
"weight": "0.23",
"image": {
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png",
"alt": "This is an image alt",
"id": "5759070976424132652"
},
"inventory_tracker": null,
"option2": "xl",
"sku": "S0000001",
"taxable": null
}
}
},
"examples": {
"Create a variant": {
"description": "Create a variant.",
"value": {
"variant": {
"weight_unit": "kg",
"image": {
"alt": "This is an image alt",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
},
"inventory_policy": "continue",
"option1": "S",
"option2": "White",
"required_shipping": "true",
"weight": "0.5",
"barcode": "T0000001",
"compare_at_price": "99",
"inventory_tracker": "true",
"price": "90",
"sku": "S0000001",
"taxable": "true"
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "For the complete list of codes and messages, see [Http status code](https://developer.shopline.com/docs/apps/api-instructions-for-use/http-status-code.md?lang=en).",
"headers": {
"traceId": {
"description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise."
}
},
"content": {
"application/json": {
"schema": {
"name": "body",
"type": "object",
"properties": {
"variant": {
"name": "variant",
"description": "Variant information.",
"type": "object",
"properties": {
"barcode": {
"name": "barcode",
"description": "The barcode of the variant.",
"type": "string",
"example": "T000000001"
},
"created_at": {
"name": "created_at",
"description": "The creation date and time of the product variant. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).",
"type": "string",
"example": "2021-09-02T14:11:54+00:00"
},
"id": {
"name": "id",
"description": "The unique identifier for the variant.",
"type": "string",
"example": "18057039439794751459380282"
},
"image": {
"name": "image",
"description": "The image of the variant.",
"type": "object",
"properties": {
"alt": {
"name": "alt",
"description": "The alternative textual description of the variant image, usually a word or phrase with the characteristics or content of the image.",
"type": "string",
"example": "This is an image alt."
},
"id": {
"name": "id",
"description": "The unique identifier for the variant image.",
"type": "string",
"example": "5785060242207917075"
},
"src": {
"name": "src",
"description": "The link to the variant image, represented as a 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"
}
},
"option3": {
"name": "option3",
"description": "Information of the third option of the variant.",
"type": "string",
"example": "cotton"
},
"option5": {
"name": "option5",
"description": "Information of the fifth option of the variant.",
"type": "string",
"example": "casual"
},
"required_shipping": {
"name": "required_shipping",
"description": "Indicates whether the variant is required to be shipped.\n- `true`: Shipping is required.\n- `false`: Shipping is not required.",
"type": "boolean"
},
"weight_unit": {
"name": "weight_unit",
"description": "The unit of weight for the variant. Valid values are:\n- `g`: gram\n- `kg`: kilogram\n- `lb`: pound\n- `oz`: ounce\n- `zh_kg`: kilogram",
"type": "string"
},
"option1": {
"name": "option1",
"description": "Information of the first option of the variant.",
"type": "string",
"example": "red"
},
"option4": {
"name": "option4",
"description": "Information of the fourth option of the variant.",
"type": "string",
"example": "short"
},
"price": {
"name": "price",
"description": "The selling price of the variant. The value is rounded to two decimal places.",
"type": "string",
"example": "90.22"
},
"compare_at_price": {
"name": "compare_at_price",
"description": "The original price of the variant. The value is rounded to two decimal places.",
"type": "string",
"example": "129.99"
},
"inventory_item_id": {
"name": "inventory_item_id",
"description": "The unique identifier for the inventory item.",
"type": "string",
"example": "5985060242375689228"
},
"inventory_policy": {
"name": "inventory_policy",
"description": "Indicates whether the variant is allowed to be oversold.\n- `deny`: overselling not allowed\n- `continue`: overselling allowed",
"type": "string"
},
"inventory_quantity": {
"name": "inventory_quantity",
"description": "The total inventory quantity at all storage locations.",
"type": "integer",
"example": 99
},
"option2": {
"name": "option2",
"description": "Information of the second option of the variant.",
"type": "string",
"example": "xl"
},
"taxable": {
"name": "taxable",
"description": "Indicates whether the variant is subject to tax.\n- `true`: Tax is required.\n- `false`: Tax is not required.",
"type": "boolean"
},
"updated_at": {
"name": "updated_at",
"description": "The date and time when the variant was last updated. Format: [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).",
"type": "string",
"example": "2021-09-02T14:11:54+00:00"
},
"inventory_tracker": {
"name": "inventory_tracker",
"description": "Indicates whether the inventory tracking is enabled.\n- ` true`: Inventory tracking is enabled.\n- ` false`: Inventory tracking is not enabled.",
"type": "boolean"
},
"product_id": {
"name": "product_id",
"description": "The unique identifier for the product corresponding to the variant.",
"type": "string",
"example": "16057039432335097907370282"
},
"sku": {
"name": "sku",
"description": "The product SKU. It is distinct from `variant.id` returned by SHOPLINE. ",
"type": "string",
"example": "S00000001"
},
"weight": {
"name": "weight",
"description": "The weight of the variant. The value is rounded up if it exceeds two decimal places.",
"type": "string",
"example": "0.23"
}
},
"example": {
"id": "18057039439794751459380282",
"inventory_quantity": 99,
"inventory_tracker": null,
"option1": "red",
"option5": "casual",
"product_id": "16057039432335097907370282",
"weight": "0.23",
"barcode": "T000000001",
"compare_at_price": "129.99",
"option2": "xl",
"option3": "cotton",
"option4": "short",
"price": "90.22",
"taxable": null,
"updated_at": "2021-09-02T14:11:54+00:00",
"created_at": "2021-09-02T14:11:54+00:00",
"image": {
"id": "5785060242207917075",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png",
"alt": "This is an image alt."
},
"inventory_item_id": "5985060242375689228",
"required_shipping": null,
"weight_unit": null,
"inventory_policy": null,
"sku": "S00000001"
}
}
},
"example": {
"variant": {
"id": "18057039439794751459380282",
"inventory_policy": null,
"inventory_quantity": 99,
"option4": "short",
"price": "90.22",
"required_shipping": null,
"sku": "S00000001",
"created_at": "2021-09-02T14:11:54+00:00",
"inventory_tracker": null,
"option3": "cotton",
"taxable": null,
"barcode": "T000000001",
"compare_at_price": "129.99",
"option1": "red",
"option2": "xl",
"updated_at": "2021-09-02T14:11:54+00:00",
"image": {
"alt": "This is an image alt.",
"id": "5785060242207917075",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
},
"inventory_item_id": "5985060242375689228",
"option5": "casual",
"product_id": "16057039432335097907370282",
"weight": "0.23",
"weight_unit": null
}
}
}
}
}
},
"201": {
"headers": {
"traceId": {
"description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise."
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"name": "errors",
"description": "Error message. ",
"type": "string"
}
},
"required": [
"errors"
]
},
"examples": {
"Create a variant": {
"description": "Create a variant.",
"value": {
"variant": {
"weight_unit": "kg",
"created_at": "2023-08-29T15:32:54+08:00",
"inventory_item_id": "6089563439612587791",
"option1": "S",
"barcode": "T0000001",
"compare_at_price": "99.00",
"inventory_tracker": true,
"price": "90.00",
"updated_at": "2023-08-29T15:32:54+08:00",
"weight": "0.50",
"sku": "S0000001",
"id": "18060895634402500988513144",
"image": {
"alt": "This is an image alt",
"id": "6089563432963689533",
"src": "https://img.myshopline.com/image/official/e46e6189dd5641a3b179444cacdcdd2a.png"
},
"inventory_policy": "continue",
"option2": "White",
"required_shipping": true,
"taxable": true,
"product_id": "16060895302856191591063144"
}
}
}
}
}
}
},
"401": {
"headers": {
"traceId": {
"description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise."
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"description": "Error message. ",
"type": "string"
}
},
"required": [
"errors"
]
}
}
}
},
"429": {
"headers": {
"traceId": {
"description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise."
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"errors": {
"description": "Error message. ",
"type": "string"
}
},
"required": [
"errors"
]
}
}
}
}
},
"security": [
{
"oauth2": []
}
],
"method": "post",
"path": "/products/:product_id/variants.json",
"servers": [
{
"url": "https://{handle}.myshopline.com/admin/openapi",
"variables": {
"handle": {
"default": "openapiceshidianpu",
"description": "`handle` : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is `open001.myshopline.com` , the store handle is `open001` ."
}
}
}
],
"info": {
"title": "Create a variant",
"version": "v20270301"
},
"authIndexes": [
"write_products"
]
}
```