Create Variation

Create a new product variation for a store product. The variation name is automatically generated from the selected option values.

Endpoint

POST /v1/store-products/{id}/variations

Authentication

Requires an API key with the store:write scope.

Parameters

Parameter	Type	Location	Description
id	integer	path	The store product ID

Request Body

Field	Type	Required	Description
sku	string	No	Stock keeping unit for this variation (max 255 characters)
price_override	number	No	Price override for this variation (min 0). Omit or set to null to use the base product price.
stock_quantity	integer	No	Initial stock quantity (min 0, default: 0)
option_values	array	Yes	Array of option value objects (min 1 item)
option_values[].option_id	integer	Yes	The variation option ID (must belong to this product)
option_values[].value	string	Yes	The selected value for this option (max 100 characters)

tip

The variation name is auto-generated by joining the option values with " / " (e.g., selecting "Small" for Size and "Red" for Color produces the name "Small / Red").

Response

Success (201 Created)

{
  "data": {
    "id": 1,
    "name": "Small / Red",
    "sku": "WIDGET-SM-R",
    "price_override": 15.99,
    "stock_quantity": 25,
    "option_values": [
      {
        "option_id": 1,
        "option_name": "Size",
        "value": "Small"
      },
      {
        "option_id": 2,
        "option_name": "Color",
        "value": "Red"
      }
    ],
    "created_at": "2026-02-15T12:00:00+00:00",
    "updated_at": "2026-02-15T12:00:00+00:00"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-15T12:00:00+00:00"
  }
}

Errors

Status	Code	Description
401	authentication_required	No API key provided
401	invalid_api_key	Invalid API key
403	insufficient_scope	API key lacks store:write scope
404	resource_not_found	Store product does not exist
422	validation_error	Invalid request body
422	variations_not_enabled	Product does not have variations enabled
422	variation_error	An option_id does not belong to this product, or every option_values entry was blank

note

The option_id values in option_values must reference variation options that belong to the specified store product. Providing an option ID from a different product returns a 422 variation_error.

Values register themselves

Creating a variation adds each value to its variation option's values list automatically, so you don't have to maintain that list separately — sending {"option_id": 3, "value": "S"} makes "S" a known value of that option.

Example Request

curl -X POST "https://app.equipdash.com/api/v1/store-products/1/variations" \
  -H "Authorization: Bearer eqd_live_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "WIDGET-SM-R",
    "price_override": 15.99,
    "stock_quantity": 25,
    "option_values": [
      {
        "option_id": 1,
        "value": "Small"
      },
      {
        "option_id": 2,
        "value": "Red"
      }
    ]
  }'