Add Attribute Values

Add multiple new attribute values to an existing attribute. Attribute values define the specific options customers can choose from - such as colors, sizes, materials, or finishes.

POST /product/v1/attributes/{attributeId}/values

Request Format

The request body must be a JSON array of attribute value objects. Each object defines a new value option for the attribute.

[
  {
    "id": "red",
    "description": "Bright red color for premium products",
    "properties": {
      "hexCode": "#FF0000",
      "pantone": "PANTONE 18-1664 TPX",
      "displayOrder": "1"
    },
    "isCustom": false,
    "isDefault": true
  },
  {
    "id": "blue", 
    "description": "Navy blue color for professional products",
    "properties": {
      "hexCode": "#000080",
      "pantone": "PANTONE 19-4052 TPX",
      "displayOrder": "2"
    },
    "isCustom": false,
    "isDefault": false
  }
]

Example curl request

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/attributes/attr-color/values' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '[
  {
    "id": "red",
    "description": "Bright red color for premium products", 
    "properties": {
      "hexCode": "#FF0000",
      "pantone": "PANTONE 18-1664 TPX",
      "displayOrder": "1"
    },
    "isCustom": false,
    "isDefault": true
  },
  {
    "id": "blue",
    "description": "Navy blue color for professional products",
    "properties": {
      "hexCode": "#000080",
      "pantone": "PANTONE 19-4052 TPX",
      "displayOrder": "2"
    },
    "isCustom": false,
    "isDefault": false
  }
]'

Request Parameters

Parameter	Type	Required	Description
attributeId	string	Required	Unique identifier of the attribute (URL path parameter)
id	string	Required	Unique identifier for the attribute value. Must contain only lowercase letters, numbers, underscores, periods, and hyphens. Used in ProductUIDs for ordering.
description	string	Optional	Human-readable description displayed in user interfaces and product catalogs
properties	object	Optional	Flexible key-value pairs for additional metadata (color codes, Pantone references, measurements, display ordering, etc.)
isCustom	boolean	Optional	Indicates if this is a custom value that can accept any input (e.g., page count, custom text). Default: false
isDefault	boolean	Optional	Marks this as the default selection when the attribute is added to new product models. Default: false

Response Format

Returns the created attribute values with server-generated fields and computed properties:

[
  {
    "id": "red",
    "attributeId": "attr-color",
    "description": "Bright red color for premium products",
    "properties": {
      "hexCode": "#FF0000",
      "rgb": "255,0,0",
      "pantone": "PANTONE 18-1664 TPX",
      "displayOrder": "1"
    },
    "isCustom": false,
    "isDefault": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "blue",
    "attributeId": "attr-color", 
    "description": "Navy blue color for professional products",
    "properties": {
      "hexCode": "#000080",
      "rgb": "0,0,128",
      "pantone": "PANTONE 19-4052 TPX",
      "displayOrder": "2"
    },
    "isCustom": false,
    "isDefault": false,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  }
]

Common Use Cases

Adding Size Options:

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/attributes/attr-size/values' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '[
  {
    "id": "small",
    "description": "Small - 10cm x 15cm",
    "properties": {
      "dimensions": "10x15cm",
      "width": "10",
      "height": "15",
      "sortOrder": 1
    },
    "isDefault": false
  },
  {
    "id": "medium",
    "description": "Medium - 15cm x 20cm",
    "properties": {
      "dimensions": "15x20cm", 
      "width": "15",
      "height": "20",
      "sortOrder": 2
    },
    "isDefault": true
  }
]'

Adding Material Options:

curl --location --request POST 'https://connect.gelatoapis.com/product/v1/attributes/attr-material/values' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-api-key' \
--data-raw '[
  {
    "id": "organic-cotton",
    "description": "100% Organic Cotton",
    "properties": {
      "composition": "100% organic cotton",
      "weight": "180gsm",
      "certifications": ["GOTS", "OEKO-TEX"],
      "sustainability": "certified organic"
    },
    "isDefault": true
  }
]'