Catalog - Product Variants
Get All Variants
GET /stores/{store_hash}/v3/catalog/variants
Request
Returns a list of all variants in your catalog. Optional parameters can be passed in.
Authentication
- X-Auth-Token in header - required
Parameters
- store_hash in path - string
- Accept in header with default of application/json - string - required
The MIME type of the response body.
- id in query - integer
Filter items by ID.
- sku in query - string
Filter items by SKU.
- upc in query - string
Filter items by UPC.
- page in query - integer
Specifies the page number in a limited (paginated) list of products.
- limit in query - integer
Controls the number of items per page in a limited (paginated) list of products.
- include_fields in query - string
Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
- exclude_fields in query - string
Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.
- product_id in query - string
A comma-separated list of IDs of products whose variants were requested. For example:
?product_id:in=77,80,81
example
Response
Body
dataarray[object]
metaobject
Data about the response, including pagination and collection totals.
example
Update Variants (Batch)
PUT /stores/{store_hash}/v3/catalog/variants
Request
Updates a batch of variant
objects. Currently the limit is 50 variants however this is subject to change.
Required Fields
To update an existing variant:
- id (variant ID)
To create a new variant:
- product_id
- sku
- option_values
- id (option_value ID - Example: 146)
- option_id (Option ID - Example: 151)
Authentication
- X-Auth-Token in header - required
Parameters
- store_hash in path - string
- Content-Type in header with default of application/json - string - required
The MIME type of the request body.
Body
cost_pricenumber
The cost price of the variant. Not affected by Price List prices.
Example: 40
pricenumber
This variant’s base price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is
null
, the product’s default price (set in the Product resource’sprice
field) will be used as the base price.Example: 40
sale_pricenumber
This variant’s sale price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s sale price (set in the Product resource’s
price
field) will be used as the sale price.Example: 40
retail_pricenumber
This variant’s retail price on the storefront. If a Price List ID is used, the Price List value will be used. If a Price List ID is not used, and this value is null, the product’s retail price (set in the Product resource’s
price
field) will be used as the retail price.Example: 40
weightnumber
This variant’s base weight on the storefront. If this value is null, the product’s default weight (set in the Product resource’s weight field) will be used as the base weight.
Example: 5
widthnumber
Width of the variant, which can be used when calculating shipping costs. If this value is
null
, the productʼs default width (set in the Product resourceʼswidth
field) will be used as the base width.Example: 5
heightnumber
Height of the variant, which can be used when calculating shipping costs. If this value is
null
, the productʼs default height (set in the Product resourceʼsheight
field) will be used as the base height.Example: 5
depthnumber
Depth of the variant, which can be used when calculating shipping costs. If this value is
null
, the productʼs default depth (set in the Product resourceʼsdepth
field) will be used as the base depth.Example: 5
is_free_shippingboolean
Flag used to indicate whether the variant has free shipping. If
true
, the shipping cost for the variant will be zero.fixed_cost_shipping_pricenumber
A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.
purchasing_disabledboolean
If
true
, this variant will not be purchasable on the storefront.purchasing_disabled_messagestring
>= 0 characters<= 255 charactersIf
purchasing_disabled
istrue
, this message should show on the storefront when the variant is selected.upcstring
The UPC code used in feeds for shopping comparison sites and external channel integrations.
Example: 1234
inventory_levelinteger
Inventory level for the variant, which is used when the product’s inventory_tracking is set to
variant
. The Catalog API returns the inventory for only the default location.The inventory for a variant cannot exceed 2,147,483,647 in the catalog. The sum of the variant inventories, or the total inventory for a product, cannot exceed 2,147,483,647.
If you exceed the limit, the store sets the variant inventory to the limit if no other variant inventories are set. If other variant inventories are set, the store does not save the variant inventory rather than setting the variant inventory to the remaining limit.
The Catalog API handles limits in a different way than the Inventory API. For more information, see Limit handling.
Example: 21474
inventory_warning_levelinteger
When the variant hits this inventory level, it is considered low stock.
Example: 5474
bin_picking_numberstring
>= 0 characters<= 255 charactersIdentifies where in a warehouse the variant is located.
idinteger
Example: 154
example
Response
Body
dataarray[object]
metaobject
Data about the response, including pagination and collection totals.