Skip to main content

Product variations

The product variations API allows you to create, view, update, and delete individual, or a batch, of product variations.

Product variation properties​

AttributeTypeDescription
idintegerUnique identifier for the resource. READ-ONLY
date_createddate-timeThe date the variation was created, in the site's timezone. READ-ONLY
date_created_gmtdate-timeThe date the variation was created, as GMT. READ-ONLY
date_modifieddate-timeThe date the variation was last modified, in the site's timezone. READ-ONLY
date_modified_gmtdate-timeThe date the variation was last modified, as GMT. READ-ONLY
descriptionstringVariation description.
permalinkstringVariation URL. READ-ONLY
skustringUnique identifier.
global_unique_idstringGTIN, UPC, EAN or ISBN. A global unique identifier for the variation.
pricestringCurrent variation price. READ-ONLY
regular_pricestringVariation regular price.
sale_pricestringVariation sale price.
date_on_sale_fromdate-timeStart date of sale price, in the site's timezone.
date_on_sale_from_gmtdate-timeStart date of sale price, as GMT.
date_on_sale_todate-timeEnd date of sale price, in the site's timezone.
date_on_sale_to_gmtdate-timeEnd date of sale price, as GMT.
on_salebooleanShows if the variation is on sale. READ-ONLY
statusstringVariation status. Options: draft, pending, private and publish. Default is publish.
purchasablebooleanShows if the variation can be bought. READ-ONLY
virtualbooleanIf the variation is virtual. Default is false.
downloadablebooleanIf the variation is downloadable. Default is false.
downloadsarrayList of downloadable files. See Product variation - Downloads properties
download_limitintegerNumber of times downloadable files can be downloaded after purchase. Default is -1.
download_expiryintegerNumber of days until access to downloadable files expires. Default is -1.
tax_statusstringTax status. Options: taxable, shipping and none. Default is taxable.
tax_classstringTax class.
manage_stockboolean, stringStock management at variation level. Possible values are either a boolean or parent. Default is false.
stock_quantityintegerStock quantity.
stock_statusstringControls the stock status of the product. Options: instock, outofstock, onbackorder. Default is instock.
backordersstringIf managing stock, this controls if backorders are allowed. Options: no, notify and yes. Default is no.
backorders_allowedbooleanShows if backorders are allowed. READ-ONLY
backorderedbooleanShows if the variation is on backordered. READ-ONLY
weightstringVariation weight.
dimensionsobjectVariation dimensions. See Product variation - Dimensions properties
shipping_classstringShipping class slug.
shipping_class_idstringShipping class ID. READ-ONLY
imageobjectVariation image data. See Product variation - Image properties
attributesarrayList of attributes. See Product variation - Attributes properties
menu_orderintegerMenu order, used to custom sort products.
meta_dataarrayMeta data. See Product variation - Meta data properties

Product variation - Downloads properties​

AttributeTypeDescription
idstringFile ID.
namestringFile name.
filestringFile URL.

Product variation - Dimensions properties​

AttributeTypeDescription
lengthstringVariation length.
widthstringVariation width.
heightstringVariation height.

Product variation - Image properties​

AttributeTypeDescription
idintegerImage ID.
date_createddate-timeThe date the image was created, in the site's timezone. READ-ONLY
date_created_gmtdate-timeThe date the image was created, as GMT. READ-ONLY
date_modifieddate-timeThe date the image was last modified, in the site's timezone. READ-ONLY
date_modified_gmtdate-timeThe date the image was last modified, as GMT. READ-ONLY
srcstringImage URL.
namestringImage name.
altstringImage alternative text.

Product variation - Attributes properties​

AttributeTypeDescription
idintegerAttribute ID.
namestringAttribute name.
optionstringSelected attribute term name.

Product variation - Meta data properties​

AttributeTypeDescription
idintegerMeta ID. READ-ONLY
keystringMeta key.
valuestringMeta value.

Create a product variation​

This API helps you to create a new product variation.

POST /wp-json/wc/v3/products/<product_id>/variations
curl -X POST https://example.com/wp-json/wc/v3/products/22/variations \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "regular_price": "9.00",
  "image": {
    "id": 423
  },
  "attributes": [
    {
      "id": 6,
      "option": "Black"
    }
  ]
}'

Retrieve a product variation​

This API lets you retrieve and view a specific product variation by ID.

GET /wp-json/wc/v3/products/<product_id>/variations/<id>
curl https://example.com/wp-json/wc/v3/products/22/variations/732 \
	-u consumer_key:consumer_secret

List all product variations​

This API helps you to view all the product variations.

GET /wp-json/wc/v3/products/<product_id>/variations
curl https://example.com/wp-json/wc/v3/products/22/variations \
	-u consumer_key:consumer_secret

Available parameters​

ParameterTypeDescription
contextstringScope under which the request is made; determines fields present in response. Options: view and edit. Default is view.
pageintegerCurrent page of the collection. Default is 1.
per_pageintegerMaximum number of items to be returned in result set. Default is 10.
searchstringLimit results to those matching a string.
afterstringLimit response to resources published after a given ISO8601 compliant date.
beforestringLimit response to resources published before a given ISO8601 compliant date.
dates_are_gmtbooleanInterpret after and before as UTC dates when true.
excludearrayEnsure result set excludes specific IDs.
includearrayLimit result set to specific ids.
offsetintegerOffset the result set by a specific number of items.
orderstringOrder sort attribute ascending or descending. Options: asc and desc. Default is desc.
orderbystringSort collection by object attribute. Options: date, modified, id, include, title and slug. Default is date.
parentarrayLimit result set to those of particular parent IDs.
parent_excludearrayLimit result set to all items except those of a particular parent ID.
slugstringLimit result set to products with a specific slug.
statusstringLimit result set to products assigned a specific status. Options: any, draft, pending, private and publish. Default is any.
include_statusstringLimit result set to product variations with any of the specified statuses. Multiple statuses can be provided as a comma-separated list. Takes precedence over the status parameter. Options: any, future, trash, draft, pending, private, and publish.
exclude_statusstringExclude product variations from result set with any of the specified statuses. Multiple statuses can be provided as a comma-separated list. Takes precedence over the include_status parameter. Options: future, trash, draft, pending, private, and publish.
skustringLimit result set to products with a specific SKU.
tax_classstringLimit result set to products with a specific tax class. Default options: standard, reduced-rate and zero-rate.
on_salebooleanLimit result set to products on sale.
min_pricestringLimit result set to products based on a minimum price.
max_pricestringLimit result set to products based on a maximum price.
stock_statusstringLimit result set to products with specified stock status. Options: instock, outofstock and onbackorder.
virtualbooleanLimit result set to virtual product variations
downloadablebooleanLimit result set to downloadable product variations.

Update a product variation​

This API lets you make changes to a product variation.

PUT /wp-json/wc/v3/products/<product_id>/variations/<id>
curl -X PUT https://example.com/wp-json/wc/v3/products/22/variations/733 \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "regular_price": "10.00"
}'

Delete a product variation​

This API helps you delete a product variation.

DELETE /wp-json/wc/v3/products/<product_id>/variations/<id>
curl -X DELETE https://example.com/wp-json/wc/v3/products/22/variations/733?force=true \
	-u consumer_key:consumer_secret

Available parameters​

ParameterTypeDescription
forcestringRequired to be true, as resource does not support trashing.

Batch update product variations​

This API helps you to batch create, update and delete multiple product variations.

note

Note: By default it's limited to up to 100 objects to be created, updated or deleted.

POST /wp-json/wc/v3/products/<product_id>/variations/batch
curl -X POST https://example.com/wp-json/wc/v3/products/22/variations/batch \
	-u consumer_key:consumer_secret \
	-H "Content-Type: application/json" \
	-d '{
  "create": [
    {
      "regular_price": "10.00",
      "attributes": [
        {
          "id": 6,
          "option": "Blue"
        }
      ]
    },
    {
      "regular_price": "10.00",
      "attributes": [
        {
          "id": 6,
          "option": "White"
        }
      ]
    }
  ],
  "update": [
    {
      "id": 733,
      "regular_price": "10.00"
    }
  ],
  "delete": [
    732
  ]
}'

Use of your personal data

We and our partners process your personal data (such as browsing data, IP Addresses, cookie information, and other unique identifiers) based on your consent and/or our legitimate interest to optimize our website, marketing activities, and your user experience.