Option Lists

Curated values for structured data

Option lists provide dropdown values for option-type attributes. Support hierarchical (nested) values with colors and sort order. Reference an option list from any attribute to enforce consistent, curated selections across your catalog.

Flat Lists

Simple lists of values like colors, sizes, or materials. Each value has a label, optional color, and sortOrder.

Hierarchical Lists

Nested values using parentId to create tree structures. Set hierarchical: true on the list to enable nesting.

Color Swatches

Each value can include a color hex code for visual display in the UI. Perfect for color pickers and material selectors.

Sort Order

Control the display order of values with the sortOrder field. Values are presented in ascending order.

Endpoints

Method	Path	Description
GET	`/option-lists`	List all option lists
POST	`/option-lists`	Create an option list
GET	`/option-lists/:id`	Get option list by ID
PUT	`/option-lists/:id`	Update an option list
DELETE	`/option-lists/:id`	Delete an option list
POST	`/option-lists/:id/values`	Add a value
PUT	`/option-lists/:id/values/:valueId`	Update a value
DELETE	`/option-lists/:id/values/:valueId`	Remove a value

GET /option-lists

Returns all option lists with their values.

curl https://api.sigma-pim.com/api/v1/option-lists \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
[
  {
    "id": "ol-colors",
    "alias": "colors",
    "name": "Colors",
    "hierarchical": false,
    "values": [
      { "id": "val-red", "alias": "red", "label": "Red", "sortOrder": 1, "color": "#ef4444" },
      { "id": "val-blue", "alias": "blue", "label": "Blue", "sortOrder": 2, "color": "#3b82f6" },
      { "id": "val-green", "alias": "green", "label": "Green", "sortOrder": 3, "color": "#22c55e" }
    ]
  },
  {
    "id": "ol-categories",
    "alias": "categories",
    "name": "Categories",
    "hierarchical": true,
    "values": [
      { "id": "val-clothing", "alias": "clothing", "label": "Clothing", "sortOrder": 1 },
      { "id": "val-tops", "alias": "tops", "label": "Tops", "sortOrder": 1, "parentId": "val-clothing" },
      { "id": "val-bottoms", "alias": "bottoms", "label": "Bottoms", "sortOrder": 2, "parentId": "val-clothing" }
    ]
  }
]

POST /option-lists

Create a new option list with initial values. Set hierarchical: true to enable nested values with parentId references.

Request Body

Field	Type	Description
`id`	`string`	Unique identifier for the option list
`alias`	`string`	URL-friendly alias
`name`	`string`	Display name
`hierarchical`	`boolean`	Whether values can be nested via parentId
`values`	`Value[]`	Array of value objects
`values[].id`	`string`	Unique value identifier
`values[].alias`	`string`	Value alias
`values[].label`	`string`	Display label
`values[].sortOrder`	`number`	Display sort position
`values[].color`	`string?`	Optional hex color code (e.g. "#ef4444")
`values[].parentId`	`string?`	Optional parent value ID (hierarchical only)

curl -X POST https://api.sigma-pim.com/api/v1/option-lists \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ol-colors",
    "alias": "colors",
    "name": "Colors",
    "hierarchical": false,
    "values": [
      { "id": "val-red", "alias": "red", "label": "Red", "sortOrder": 1, "color": "#ef4444" },
      { "id": "val-blue", "alias": "blue", "label": "Blue", "sortOrder": 2, "color": "#3b82f6" },
      { "id": "val-green", "alias": "green", "label": "Green", "sortOrder": 3, "color": "#22c55e" }
    ]
  }'

// Response — 201 Created
{
  "id": "ol-colors",
  "alias": "colors",
  "name": "Colors",
  "hierarchical": false,
  "values": [
    { "id": "val-red", "alias": "red", "label": "Red", "sortOrder": 1, "color": "#ef4444" },
    { "id": "val-blue", "alias": "blue", "label": "Blue", "sortOrder": 2, "color": "#3b82f6" },
    { "id": "val-green", "alias": "green", "label": "Green", "sortOrder": 3, "color": "#22c55e" }
  ]
}

GET /option-lists/:id

Retrieve a single option list by its ID, including all values.

Path Parameters

Parameter	Type	Description
`id`	`string`	The option list ID (e.g. `ol-colors`)

curl https://api.sigma-pim.com/api/v1/option-lists/ol-colors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response
{
  "id": "ol-colors",
  "alias": "colors",
  "name": "Colors",
  "hierarchical": false,
  "values": [
    { "id": "val-red", "alias": "red", "label": "Red", "sortOrder": 1, "color": "#ef4444" },
    { "id": "val-blue", "alias": "blue", "label": "Blue", "sortOrder": 2, "color": "#3b82f6" },
    { "id": "val-green", "alias": "green", "label": "Green", "sortOrder": 3, "color": "#22c55e" }
  ]
}

PUT /option-lists/:id

Update an option list. Provide the full option list object with updated fields.

curl -X PUT https://api.sigma-pim.com/api/v1/option-lists/ol-colors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ol-colors",
    "alias": "colors",
    "name": "Product Colors",
    "hierarchical": false,
    "values": [
      { "id": "val-red", "alias": "red", "label": "Red", "sortOrder": 1, "color": "#ef4444" },
      { "id": "val-blue", "alias": "blue", "label": "Blue", "sortOrder": 2, "color": "#3b82f6" },
      { "id": "val-green", "alias": "green", "label": "Green", "sortOrder": 3, "color": "#22c55e" },
      { "id": "val-black", "alias": "black", "label": "Black", "sortOrder": 4, "color": "#171717" }
    ]
  }'

DELETE /option-lists/:id

Delete an option list. Returns 204 No Content on success.

curl -X DELETE https://api.sigma-pim.com/api/v1/option-lists/ol-colors \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response — 204 No Content (empty body)

POST /option-lists/:id/values

Add a new value to an existing option list. For hierarchical lists, use parentId to nest under an existing value.

Request Body

Field	Type	Description
`id`	`string`	Unique value identifier
`alias`	`string`	Value alias
`label`	`string`	Display label
`sortOrder`	`number`	Display sort position
`color`	`string?`	Optional hex color code
`parentId`	`string?`	Optional parent value ID (hierarchical only)

curl -X POST https://api.sigma-pim.com/api/v1/option-lists/ol-colors/values \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "id": "val-yellow",
    "alias": "yellow",
    "label": "Yellow",
    "sortOrder": 4,
    "color": "#eab308"
  }'

// Response — the updated option list with the new value added
{
  "id": "ol-colors",
  "alias": "colors",
  "name": "Colors",
  "hierarchical": false,
  "values": [
    { "id": "val-red", "alias": "red", "label": "Red", "sortOrder": 1, "color": "#ef4444" },
    { "id": "val-blue", "alias": "blue", "label": "Blue", "sortOrder": 2, "color": "#3b82f6" },
    { "id": "val-green", "alias": "green", "label": "Green", "sortOrder": 3, "color": "#22c55e" },
    { "id": "val-yellow", "alias": "yellow", "label": "Yellow", "sortOrder": 4, "color": "#eab308" }
  ]
}

PUT /option-lists/:id/values/:valueId

Update a specific value within an option list. Only include the fields you want to change.

Request Body

Field	Type	Description
`label`	`string?`	Updated display label
`sortOrder`	`number?`	Updated sort position
`color`	`string?`	Updated hex color code
`parentId`	`string?`	Updated parent value ID

curl -X PUT https://api.sigma-pim.com/api/v1/option-lists/ol-colors/values/val-red \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "label": "Crimson Red", "color": "#dc2626" }'

DELETE /option-lists/:id/values/:valueId

Remove a value from an option list. If the list is hierarchical, child values of the removed value will become orphaned.

curl -X DELETE https://api.sigma-pim.com/api/v1/option-lists/ol-colors/values/val-yellow \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

// Response — the updated option list without the removed value
{
  "id": "ol-colors",
  "alias": "colors",
  "name": "Colors",
  "hierarchical": false,
  "values": [
    { "id": "val-red", "alias": "red", "label": "Red", "sortOrder": 1, "color": "#ef4444" },
    { "id": "val-blue", "alias": "blue", "label": "Blue", "sortOrder": 2, "color": "#3b82f6" },
    { "id": "val-green", "alias": "green", "label": "Green", "sortOrder": 3, "color": "#22c55e" }
  ]
}

Previous Dimensions Next Workflows