Add Variant Option Values

Add variant option values to existing customer products. Variant option values are the actual selectable options within a variant type - for example, "Small", "Medium", "Large" for a size variant option.

POST /product/v1/customer-products/{customerProductId}/variant-values

Request Format

The request body must be a JSON array of variant option value definitions:

[
  {
    "variantOptionId": "size",
    "values": [
      {
        "value": "8x10",
        "attributeValues": [
          {
            "partModelId": "frame",
            "attributes": {
              "width": "8",
              "height": "10"
            }
          },
          {
            "partModelId": "poster-print-paper-premium",
            "attributes": {
              "width": "8",
              "height": "10"
            }
          }
        ],
        "isDefault": false
      },
      {
        "value": "11x14",
        "attributeValues": [
          {
            "partModelId": "frame",
            "attributes": {
              "width": "11",
              "height": "14"
            }
          },
          {
            "partModelId": "poster-print-paper-premium",
            "attributes": {
              "width": "11",
              "height": "14"
            }
          }
        ],
        "isDefault": true
      }
    ]
  }
]

Example curl request

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/customer-products/cp-550e8400-e29b-41d4-a716-446655440001/variant-values' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '[
  {
    "variantOptionId": "size",
    "values": [
      {
        "value": "8x10",
        "attributeValues": [
          {
            "partModelId": "frame",
            "attributes": {
              "width": "8",
              "height": "10"
            }
          },
          {
            "partModelId": "poster-print-paper-premium",
            "attributes": {
              "width": "8",
              "height": "10"
            }
          }
        ],
        "isDefault": false
      },
      {
        "value": "11x14",
        "attributeValues": [
          {
            "partModelId": "frame",
            "attributes": {
              "width": "11",
              "height": "14"
            }
          },
          {
            "partModelId": "poster-print-paper-premium",
            "attributes": {
              "width": "11",
              "height": "14"
            }
          }
        ],
        "isDefault": true
      }
    ]
  }
]'

Request Parameters

Parameter	Type	Required	Description
customerProductId	string	Required	Unique identifier of the customer product (URL path parameter)
variantOptionId	string	Required	ID of the variant option this value belongs to
values	array[object]	Required	Array of value objects for this variant option

Value Object Parameters

Parameter	Type	Required	Description
value	string	Required	The actual variant option value (e.g., "Small", "Red", "8x10")
attributeValues	array[object]	Required	Array of attribute value mappings for this variant option value
isDefault	boolean	Optional	Whether this is the default option. Default: false

Attribute Value Object Parameters

Parameter	Type	Required	Description
partModelId	string	Required	Identifier of the part/product model this value applies to
attributes	object	Required	Object containing attribute key-value pairs for this part model

Response Format

Returns the created variant option values with confirmation:

[
  {
    "variantOptionId": "size",
    "values": [
      {
        "value": "8x10",
        "attributeValues": [
          {
            "partModelId": "frame",
            "attributes": {
              "width": "8",
              "height": "10"
            }
          },
          {
            "partModelId": "poster-print-paper-premium",
            "attributes": {
              "width": "8",
              "height": "10"
            }
          }
        ],
        "isDefault": false
      },
      {
        "value": "11x14",
        "attributeValues": [
          {
            "partModelId": "frame",
            "attributes": {
              "width": "11",
              "height": "14"
            }
          },
          {
            "partModelId": "poster-print-paper-premium",
            "attributes": {
              "width": "11",
              "height": "14"
            }
          }
        ],
        "isDefault": true
      }
    ]
  }
]

Common Use Cases

Add Color Options:

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/customer-products/cp-550e8400-e29b-41d4-a716-446655440001/variant-values' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '[
  {
    "variantOptionId": "frame-color",
    "values": [
      {
        "value": "black",
        "attributeValues": [
          {
            "partModelId": "frame",
            "attributes": {
              "color": "#000000",
              "finish": "matte"
            }
          }
        ],
        "isDefault": false
      },
      {
        "value": "white",
        "attributeValues": [
          {
            "partModelId": "frame",
            "attributes": {
              "color": "#FFFFFF",
              "finish": "glossy"
            }
          }
        ],
        "isDefault": true
      }
    ]
  }
]'

Add Paper Format Options:

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/customer-products/cp-550e8400-e29b-41d4-a716-446655440001/variant-values' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '[
  {
    "variantOptionId": "format",
    "values": [
      {
        "value": "A4",
        "attributeValues": [
          {
            "partModelId": "paper",
            "attributes": {
              "PaperFormat": "210x297-mm",
              "orientation": "portrait"
            }
          }
        ],
        "isDefault": true
      },
      {
        "value": "A3",
        "attributeValues": [
          {
            "partModelId": "paper",
            "attributes": {
              "PaperFormat": "297x420-mm",
              "orientation": "portrait"
            }
          }
        ],
        "isDefault": false
      }
    ]
  }
]'

Add Multi-Part Product Values:

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/customer-products/cp-550e8400-e29b-41d4-a716-446655440001/variant-values' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '[
  {
    "variantOptionId": "size",
    "values": [
      {
        "value": "large",
        "attributeValues": [
          {
            "partModelId": "fabric",
            "attributes": {
              "width": "40",
              "height": "50"
            }
          },
          {
            "partModelId": "label",
            "attributes": {
              "width": "5",
              "height": "3"
            }
          }
        ],
        "isDefault": false
      }
    ]
  }
]'