← API Documentation

Product Options API

Manage product options and their values. Options describe the choices a
customer makes, for example Size or Color. Each option has an ordered list of
values such as Small, Medium, and Large.

Endpoints

Options:

List Product Options - GET /api/v1/products/{product_id}/options/
Create Product Option - POST /api/v1/products/{product_id}/options/
Update Product Option - PUT /api/v1/products/{product_id}/options/{option_id}/
Delete Product Option - DELETE /api/v1/products/{product_id}/options/{option_id}/

Values:

Create Product Option Value - POST /api/v1/products/{product_id}/options/{option_id}/values/
Update Product Option Value - PUT /api/v1/products/{product_id}/options/{option_id}/values/{value_id}/
Move Product Option Value Up - POST /api/v1/products/{product_id}/options/{option_id}/values/{value_id}/move-up/
Delete Product Option Value - DELETE /api/v1/products/{product_id}/options/{option_id}/values/{value_id}/

List Product Options

Retrieve all options for a product, including each option's values. This
endpoint is not paginated.

Endpoint: GET /api/v1/products/{product_id}/options/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/options/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "pop_d0b6fmv28q6vn14peun0",
      "name": "Color",
      "type": "color",
      "values": [
        {
          "id": "pov_d0b6fmv28q6vn14peun0",
          "value": "Red",
          "position": 0,
          "hex": "#ff0000"
        },
        {
          "id": "pov_xk3mq7r41p8nt26zv9w0",
          "value": "Blue",
          "position": 1,
          "hex": "#0000ff"
        }
      ],
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:15:00Z"
    }
  ]
}

Create Product Option

Create an option for a product.

Endpoint: POST /api/v1/products/{product_id}/options/

Permission Required: Write

Request Body

{
  "name": "Size",
  "type": "text"
}

Field	Type	Required	Description
`name`	string	Yes	Option name
`type`	string	Yes	`text` or `color`

Request

curl -X POST "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/options/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{"name": "Size", "type": "text"}'

Response

Status: 201 Created

{
  "id": "pop_d0b6fmv28q6vn14peun0",
  "name": "Size",
  "type": "text",
  "values": [],
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

Missing required field

Status: 400 Bad Request

{
  "error": "Name is required",
  "code": "MISSING_FIELD"
}

Invalid option type

Status: 400 Bad Request

{
  "error": "Type is required",
  "code": "MISSING_FIELD"
}

Update Product Option

Rename an option.

Endpoint: PUT /api/v1/products/{product_id}/options/{option_id}/

Permission Required: Write

Request Body

{
  "name": "Sizing"
}

Field	Type	Required	Description
`name`	string	Yes	Option name

Request

curl -X PUT "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/options/pop_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{"name": "Sizing"}'

Response

Status: 200 OK

{
  "id": "pop_d0b6fmv28q6vn14peun0",
  "name": "Sizing",
  "type": "text",
  "values": [],
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:30:00Z"
}

Delete Product Option

Delete an option and its values.

Endpoint: DELETE /api/v1/products/{product_id}/options/{option_id}/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/options/pop_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Create Product Option Value

Add a value to an option. Values are ordered by position, starting at 0.

Endpoint: POST /api/v1/products/{product_id}/options/{option_id}/values/

Permission Required: Write

Request Body

{
  "value": "Small",
  "hex": null
}

Field	Type	Required	Description
`value`	string	Yes	Value text
`hex`	string	No	Hex color for `color` options (e.g. `#ff0000`)

Request

curl -X POST "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/options/pop_d0b6fmv28q6vn14peun0/values/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-13579" \
  -d '{"value": "Small"}'

Response

Status: 201 Created

{
  "id": "pov_d0b6fmv28q6vn14peun0",
  "value": "Small",
  "position": 0
}

Update Product Option Value

Update a value's text and color.

Endpoint: PUT /api/v1/products/{product_id}/options/{option_id}/values/{value_id}/

Permission Required: Write

Request Body

{
  "value": "Extra Small",
  "hex": null
}

Request

curl -X PUT "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/options/pop_d0b6fmv28q6vn14peun0/values/pov_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-24680" \
  -d '{"value": "Extra Small"}'

Response

Status: 200 OK

{
  "id": "pov_d0b6fmv28q6vn14peun0",
  "value": "Extra Small",
  "position": 0
}

Move Product Option Value Up

Move a value one position earlier in the option's list.

Endpoint: POST /api/v1/products/{product_id}/options/{option_id}/values/{value_id}/move-up/

Permission Required: Write

Request

curl -X POST "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/options/pop_d0b6fmv28q6vn14peun0/values/pov_d0b6fmv28q6vn14peun0/move-up/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Idempotency-Key: unique-request-id-11223"

Response

Status: 204 No Content

There is no move-down endpoint. To reorder downward, move the other values up.

Delete Product Option Value

Delete a value from an option.

Endpoint: DELETE /api/v1/products/{product_id}/options/{option_id}/values/{value_id}/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/options/pop_d0b6fmv28q6vn14peun0/values/pov_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Product Option Object

Fields

Field	Type	Description
`id`	string	Option public ID
`name`	string	Option name
`type`	string	`text` or `color`
`values`	array	Option values
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Product Option Value Object

Fields

Field	Type	Description
`id`	string	Value public ID
`value`	string	Value text
`position`	integer	Sort position, starting at 0
`hex`	string\|null	Hex color for `color` options