How do I include variant option values when creating or updating products with variants via the External API?

Overview

When you create or update a product that includes inline variants (via the variants array in the request body), each variant must include its option values. Without them, the product will be rejected at the API level, and—even if it were saved—it could not be published to Shopify correctly.

Required field: `product_variants`

Each object inside the variants array must contain a product_variants key:

{
  "name": "Classic T-Shirt",
  "sku": "SHIRT-001",
  "category_id": 5,
  "variants": [
    {
      "name": "Classic T-Shirt – Small",
      "sku": "SHIRT-001-S",
      "product_variants": [
        { "variant_name": "Size", "variant_terms": ["S"] }
      ]
    },
    {
      "name": "Classic T-Shirt – Medium",
      "sku": "SHIRT-001-M",
      "product_variants": [
        { "variant_name": "Size", "variant_terms": ["M"] }
      ]
    }
  ]
}

Shape rules:

variant_name — required string; the option axis label (e.g., "Size", "Color").
variant_terms — required non-empty array of strings; the values for this variant (e.g., ["S"]). For a variant, this should contain exactly one value.

You may also use variant_attributes in place of product_variants — the two keys are interchangeable (the API accepts whichever you provide).

For a variant with two option axes:

"product_variants": [
  { "variant_name": "Size",  "variant_terms": ["M"] },
  { "variant_name": "Color", "variant_terms": ["Red"] }
]

Unit-of-measure defaults

If you omit default_selling_unit_id, default_purchase_unit_id, and unit_class_id from a new product payload, Luminous automatically assigns the account's configured base unit (e.g., "ea" / "eaches"). You only need to pass these fields when you want a non-default UOM.

If the account has no UOM configured at all, the API returns a 422 error with a message explaining what to set up first.

Validation errors you may see

Error message	Cause	Fix
`Each variant must include product_variants with option name and terms`	A `variants` array entry is missing `product_variants`	Add the `product_variants` array to every variant object
`Products with variant_parent_id … must include product_variants`	A standalone product upsert with `variant_parent_id` set has no option values	Include `product_variants` in the same request
`No unit of measure is configured for this account`	Account has no UOM catalog set up	Create at least one UOM (e.g., ea) under Settings → Units of Measure

Updating a variant that already has option values

If you PUT a product that already has option values saved and you do not send product_variants in the update, the existing option values are preserved. You only need to include product_variants when you want to change or set them.