Skip to main content
This guide explains how to specify product variants when submitting an order through the API, ensuring the correct options are selected for each purchase.

​
Retrieving variant information

Use the product lookup endpoint to retrieve available variants for a product: 
const product = await client.products.lookup({ url: productUrl });

// product.variantDimensions — available option labels and values
// e.g. [{ label: "Color", values: ["Red", "Blue"] }, { label: "Size", values: ["S", "M", "L"] }]

// product.variants — each variant with its dimensions, price, availability, and images

​
Using variantSelections

When creating a checkout intent, pass the option labels and values from the product data: 
[
  { "label": "Size", "value": "8.5" },
  { "label": "Color", "value": "Blue" }
]
  • Labels are matched with minor fuzzy tolerance (e.g., “Colour” will match “Color”), but values must match exactly (case-insensitive).
  • If no variant matches the provided selections, the API returns a variant_selections_invalid error.
  • When variantSelections is provided, it takes precedence over any variant ID embedded in the productUrl.
Alternatively, you can provide a productUrl that points directly to the correct variant. If the URL already includes the variant identifier, you don’t need to include variantSelections.

​
Notes

  • You only need one approach — either variantSelections or a variant-specific URL. If both are provided, variantSelections takes precedence.