Docs
Catalog API
Variants Batch

Variants (Batch)

Get all variants

GET /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
  • id in query - integer

    Filter items by variant ID.

  • sku in query - string

    Filter items by variant SKU. To filter by product / base variant SKU, see Get all products.

  • upc in query - string

    Filter items by UPC.

  • include_fields in query - array

    Fields to include, in a comma-separated list. The ID and the specified fields will be returned.

    Type: array[string]

  • exclude_fields in query - array

    Fields to exclude, in a comma-separated list. The specified fields will be excluded from a response. The ID cannot be excluded.

    Type: array[string]

  • 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.

  • product_id:in in query - array

    A comma-separated list of IDs of products you want to request. For example, ?product_id:in=77,80,81.

    Type: array[integer]

example

Response

Body

object | application/json
  • data
    array[object]

  • meta
    object

    Data about the response, including pagination and collection totals.

example

Update Variants (Batch)

PUT /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

array | application/json
  • cost_price
    number

    The cost price of the variant. It is not affected by Price List prices. This value displays as null in the control panel when cost_price equals zero.

    Example: 40

  • price
    number

    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’s price field) will be used as the base price.

    Example: 40

  • sale_price
    number

    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_price
    number

    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

  • weight
    number

    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

  • width
    number

    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ʼs width field) will be used as the base width.

    Example: 5

  • height
    number

    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ʼs height field) will be used as the base height.

    Example: 5

  • depth
    number

    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ʼs depth field) will be used as the base depth.

    Example: 5

  • is_free_shipping
    boolean

    Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.

  • fixed_cost_shipping_price
    number

    A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.

  • purchasing_disabled
    boolean

    If true, this variant will not be purchasable on the storefront.

  • purchasing_disabled_message
    string

    If purchasing_disabled is true, this message should show on the storefront when the variant is selected.

    >= 0 characters<= 255 characters
  • upc
    string

    The UPC code used in feeds for shopping comparison sites and external channel integrations.

    Example: 1234

  • inventory_level
    integer

    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.

    Max: 2147483647

    Example: 21474

  • inventory_warning_level
    integer

    When the variant hits this inventory level, it is considered low stock.

    Max: 2147483647

    Example: 5474

  • bin_picking_number
    string

    Identifies where in a warehouse the variant is located.

    >= 0 characters<= 255 characters
  • id
    integer

    Example: 154

  • cost_price
    number

    The cost price of the variant. It is not affected by Price List prices. This value displays as null in the control panel when cost_price equals zero.

    Example: 40

  • price
    number

    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’s price field) will be used as the base price.

    Example: 40

  • sale_price
    number

    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_price
    number

    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

  • weight
    number

    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

  • width
    number

    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ʼs width field) will be used as the base width.

    Example: 5

  • height
    number

    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ʼs height field) will be used as the base height.

    Example: 5

  • depth
    number

    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ʼs depth field) will be used as the base depth.

    Example: 5

  • is_free_shipping
    boolean

    Flag used to indicate whether the variant has free shipping. If true, the shipping cost for the variant will be zero.

  • fixed_cost_shipping_price
    number

    A fixed shipping cost for the variant. If defined, this value will be used during checkout instead of normal shipping-cost calculation.

  • purchasing_disabled
    boolean

    If true, this variant will not be purchasable on the storefront.

  • purchasing_disabled_message
    string

    If purchasing_disabled is true, this message should show on the storefront when the variant is selected.

    >= 0 characters<= 255 characters
  • upc
    string

    The UPC code used in feeds for shopping comparison sites and external channel integrations.

    Example: 1234

  • inventory_level
    integer

    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.

    Max: 2147483647

    Example: 21474

  • inventory_warning_level
    integer

    When the variant hits this inventory level, it is considered low stock.

    Max: 2147483647

    Example: 5474

  • bin_picking_number
    string

    Identifies where in a warehouse the variant is located.

    >= 0 characters<= 255 characters
  • id
    integer

    Example: 154

example

Response

Body

object | application/json
  • data
    array[object]

  • meta
    object

    Data about the response, including pagination and collection totals.

example

Did you find what you were looking for?