Skip to main content

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Product Variant

Requires products access scope.
Important

Listing, creating, updating, and deleting product variants is deprecated as of REST API 2024-04. For more information, refer to the guide to the new product model.

Important

Apps can no longer set inventory using inventory_quantity. For more information, refer to the Inventory Level resource.

A variant can be added to a Product resource to represent one version of a product with several options. The Product resource will have a variant for every possible combination of its options. Each product can have a maximum of three options and a maximum of 100 variants.
Was this section helpful?
#

Endpoints

Anchor to

The Product Variant resource

Anchor to

Properties

barcode
->
barcode

The barcode, UPC, or ISBN number for the product.

compare_at_price
->
compareAtPrice

The original price of the item before an adjustment or a sale.

created_at
->
createdAt

The date and time (ISO 8601 format) when the product variant was created.

fulfillment_service
->
fulfillmentService

The handle of a fulfillment service that stocks a product variant.

This is the handle of a third-party fulfillment service if the following conditions are met:

  1. The product variant is stocked by a single fulfillment service.
  2. The FulfillmentService is a third-party fulfillment service. Third-party fulfillment services don't have a handle with the value manual.
  3. The fulfillment service hasn't opted into SKU sharing.

If the conditions aren't met, then this is manual.

The relationship between a product variant and a fulfillment service was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommend that you use the InventoryLevel resource if you need to determine where a product variant is stocked.

If you previously set this field, then we recommend that you instead connect an inventory item to a location. Each Location is associated with a single FulfillmentService. The value of this field after setting it will be as described above.

If you need to determine whether a product is a gift card, then you should continue to use this field until an alternative is available.

Learn more about managing inventory quantities and states.

grams
deprecated

The weight of the product variant in grams.

id
->
id

The unique numeric identifier for the product variant.

image_id
->
image

The unique numeric identifier for a product's image. The image must be associated to the same product as the variant.

inventory_item_id
->
inventoryItem

The unique identifier for the inventory item, which is used in the Inventory API to query for inventory information.

inventory_management
->
inventoryLevel

The fulfillment service that tracks the number of items in stock for the product variant. Valid values:

Show inventory_management properties
  • shopify: You are tracking inventory yourself using the admin.
  • null: You aren't tracking inventory on the variant.
  • the handle of a fulfillment service that has inventory management enabled: This must be the same fulfillment service referenced by the fulfillment_service property.
inventory_policy
->
inventoryPolicy

Whether customers are allowed to place an order for the product variant when it's out of stock. Valid values:

Show inventory_policy properties
  • deny: Customers are not allowed to place orders for the product variant if it's out of stock.
  • continue: Customers are allowed to place orders for the product variant if it's out of stock.
Default value: deny.
inventory_quantity
read-only
->
inventoryQuantity

An aggregate of inventory across all locations. To adjust inventory at a specific location, use the InventoryLevel resource.

old_inventory_quantity
deprecated

This property is deprecated. Use the InventoryLevel resource instead.

Was this section helpful?
{}

The Product Variant resource

{
"barcode": "1234_pink",
"compare_at_price": "299.00",
"created_at": "2012-08-24T14:01:47-04:00",
"fulfillment_service": "manual",
"grams": 567,
"id": 808950810,
"image_id": 434522,
"inventory_item_id": 342916,
"inventory_management": "shopify",
"inventory_policy": "continue",
"inventory_quantity": 10,
"old_inventory_quantity": 5,
"option": {
"option1": "Pink"
},
"presentment_prices": {
"presentment_prices": [
{
"price": {
"currency_code": "USD",
"amount": "199.99"
},
"compare_at_price": {
"currency_code": "USD",
"amount": "249.99"
}
},
{
"price": {
"currency_code": "EUR",
"amount": "158.95"
},
"compare_at_price": {
"currency_code": "EUR",
"amount": "198.95"
}
},
{
"price": {
"currency_code": "GBP",
"amount": "143.00"
},
"compare_at_price": {
"currency_code": "GBP",
"amount": "179.00"
}
},
{
"price": {
"currency_code": "JPY",
"amount": "22400"
},
"compare_at_price": {
"currency_code": "JPY",
"amount": "28000"
}
}
]
},
"position": 1,
"price": "199.00",
"product_id": 632910392,
"requires_shipping": true,
"sku": "IPOD2008PINK",
"taxable": true,
"tax_code": "DA040000",
"title": "Pink",
"updated_at": "2012-08-24T14:01:47-04:00",
"weight": 100,
"weight_unit": "oz"
}

Anchor to POST request, Create a new Product Variant
post
Create a new Product Variant

productCreate
productVariantsBulkCreate

Creates a new product variant

Anchor to Parameters of Create a new Product VariantParameters

api_version
string
required
product_id
string
required
Was this section helpful?

Anchor to post-products-product-id-variants-examplesExamples

Create a new product variant

Path parameters
product_id=632910392
string
required

Create a new product variant with a metafield

Path parameters
product_id=632910392
string
required

Create a new product variant with an image

Path parameters
product_id=632910392
string
required
Was this section helpful?
post

/admin/api/2025-07/products/632910392/variants.json

curl -d '{"variant":{"option1":"Yellow","price":"1.00"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-07/products/632910392/variants.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 201 Created
{
"variant": {
"id": 1070325531,
"product_id": 632910392,
"title": "Yellow",
"price": "1.00",
"position": 5,
"inventory_policy": "deny",
"compare_at_price": null,
"option1": "Yellow",
"option2": null,
"option3": null,
"created_at": "2025-07-24T17:07:31-04:00",
"updated_at": "2025-07-24T17:07:32-04:00",
"taxable": true,
"barcode": null,
"fulfillment_service": "manual",
"grams": 0,
"inventory_management": "shopify",
"requires_shipping": true,
"sku": null,
"weight": 0,
"weight_unit": "lb",
"inventory_item_id": 1070325471,
"inventory_quantity": 0,
"old_inventory_quantity": 0,
"presentment_prices": [
{
"price": {
"amount": "1.00",
"currency_code": "USD"
},
"compare_at_price": null
}
],
"admin_graphql_api_id": "gid://shopify/ProductVariant/1070325531",
"image_id": null
}
}

Anchor to GET request, Retrieves a list of product variants
get
Retrieves a list of product variants

productVariants

Retrieves a list of product variants. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.

Anchor to Parameters of Retrieves a list of product variantsParameters

api_version
string
required
product_id
string
required
fields

A comma-separated list of fields to include in the response

limit
≤ 250
default 50

Return up to this many results per page

presentment_currencies

Return presentment prices in only certain currencies, specified by a comma-separated list of ISO 4217 currency codes.

since_id

Restrict results to after the specified ID

Was this section helpful?

Anchor to get-products-product-id-variants-examplesExamples

Retrieve all variants for a product

Path parameters
product_id=632910392
string
required

Retrieve all variants for a product after a specified ID

Path parameters
product_id=632910392
string
required
Query parameters
since_id=49148385

Restrict results to after the specified ID

Retrieve all variants for a product with prices in specified presentment currencies

Path parameters
product_id=632910392
string
required
Query parameters
presentment_currencies=USD,CAD

Return presentment prices in only certain currencies, specified by a comma-separated list of ISO 4217 currency codes.

Was this section helpful?
get

/admin/api/2025-07/products/632910392/variants.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/products/632910392/variants.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"variants": [
{
"id": 39072856,
"product_id": 632910392,
"title": "Green",
"price": "199.00",
"position": 3,
"inventory_policy": "continue",
"compare_at_price": null,
"option1": "Green",
"option2": null,
"option3": null,
"created_at": "2025-07-24T09:25:35-04:00",
"updated_at": "2025-07-24T09:25:35-04:00",
"taxable": true,
"barcode": "1234_green",
"fulfillment_service": "manual",
"grams": 567,
"inventory_management": "shopify",
"requires_shipping": true,
"sku": "IPOD2008GREEN",
"weight": 1.25,
"weight_unit": "lb",
"inventory_item_id": 39072856,
"inventory_quantity": 30,
"old_inventory_quantity": 30,
"presentment_prices": [
{
"price": {
"amount": "199.00",
"currency_code": "USD"
},
"compare_at_price": null
}

Anchor to GET request, Receive a count of all Product Variants
get
Receive a count of all Product Variants

productVariantsCount

Retrieves a count of product variants

Anchor to Parameters of Receive a count of all Product VariantsParameters

api_version
string
required
product_id
string
required
Was this section helpful?

Anchor to get-products-product-id-variants-count-examplesExamples

Retrieve a count all variants for a product

Path parameters
product_id=632910392
string
required
Was this section helpful?
get

/admin/api/2025-07/products/632910392/variants/count.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/products/632910392/variants/count.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"count": 4
}

Anchor to GET request, Receive a single Product Variant
get
Receive a single Product Variant

productVariant

Retrieves a single product variant by ID

Anchor to Parameters of Receive a single Product VariantParameters

api_version
string
required
variant_id
string
required
fields

A comma-separated list of fields to include in the response

Was this section helpful?

Anchor to get-variants-variant-id-examplesExamples

Retrieve a product variant by ID

Path parameters
variant_id=808950810
string
required
Was this section helpful?
get

/admin/api/2025-07/variants/808950810.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/variants/808950810.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"variant": {
"id": 808950810,
"product_id": 632910392,
"title": "Pink",
"price": "199.00",
"position": 1,
"inventory_policy": "continue",
"compare_at_price": null,
"option1": "Pink",
"option2": null,
"option3": null,
"created_at": "2025-07-24T09:25:35-04:00",
"updated_at": "2025-07-24T09:25:35-04:00",
"taxable": true,
"barcode": "1234_pink",
"fulfillment_service": "manual",
"grams": 567,
"inventory_management": "shopify",
"requires_shipping": true,
"sku": "IPOD2008PINK",
"weight": 1.25,
"weight_unit": "lb",
"inventory_item_id": 808950810,
"inventory_quantity": 10,
"old_inventory_quantity": 10,
"presentment_prices": [
{
"price": {
"amount": "199.00",
"currency_code": "USD"
},
"compare_at_price": null
}
],
"tax_code": "DA040000",
"admin_graphql_api_id": "gid://shopify/ProductVariant/808950810",
"image_id": 562641783
}
}

Anchor to PUT request, Modify an existing Product Variant
put
Modify an existing Product Variant

productVariantsBulkUpdate

Updates an existing product variant

Anchor to Parameters of Modify an existing Product VariantParameters

api_version
string
required
variant_id
string
required
Was this section helpful?

Anchor to put-variants-variant-id-examplesExamples

Add a metafield to an existing variant

Path parameters
variant_id=808950810
string
required

Add an existing image to an existing variant

Path parameters
variant_id=808950810
string
required

Update the title and price of an existing variant

Path parameters
variant_id=808950810
string
required
Was this section helpful?
put

/admin/api/2025-07/variants/808950810.json

curl -d '{"variant":{"id":808950810,"metafields":[{"key":"new","value":"newvalue","type":"single_line_text_field","namespace":"global"}]}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2025-07/variants/808950810.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 200 OK
{
"variant": {
"id": 808950810,
"product_id": 632910392,
"title": "Pink",
"price": "199.00",
"position": 1,
"inventory_policy": "continue",
"compare_at_price": null,
"option1": "Pink",
"option2": null,
"option3": null,
"created_at": "2025-07-24T09:25:35-04:00",
"updated_at": "2025-07-24T09:25:35-04:00",
"taxable": true,
"barcode": "1234_pink",
"fulfillment_service": "manual",
"grams": 567,
"inventory_management": "shopify",
"requires_shipping": true,
"sku": "IPOD2008PINK",
"weight": 1.25,
"weight_unit": "lb",
"inventory_item_id": 808950810,
"inventory_quantity": 10,
"old_inventory_quantity": 10,
"presentment_prices": [
{
"price": {
"amount": "199.00",
"currency_code": "USD"
},
"compare_at_price": null
}
],
"admin_graphql_api_id": "gid://shopify/ProductVariant/808950810",
"image_id": 562641783
}
}

Anchor to DELETE request, Remove an existing Product Variant
del
Remove an existing Product Variant

productVariantsBulkDelete

Anchor to Parameters of Remove an existing Product VariantParameters

api_version
string
required
product_id
string
required
variant_id
string
required
Was this section helpful?

Anchor to delete-products-product-id-variants-variant-id-examplesExamples

Delete a product variant

Was this section helpful?
del

/admin/api/2025-07/products/632910392/variants/808950810.json

curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-07/products/632910392/variants/808950810.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{}