← API Documentation

Product Variants API

Manage product variants for your products. Product variants allow you to offer different versions of a product (e.g., different sizes, colors, configurations) with their own pricing and inventory.

Endpoints

List Product Variants - GET /api/v1/products/{id}/variants
Create Product Variant - POST /api/v1/products/{id}/variants
Get Product Variant - GET /api/v1/products/{id}/variants/{variant_id}
Update Product Variant - PUT /api/v1/products/{id}/variants/{variant_id}

List Product Variants

Retrieve all variants for a specific product.

Endpoint: GET /api/v1/products/{id}/variants

Permission Required: Read

Path Parameters

Parameter	Type	Description
`id`	string	Product public ID (e.g., `prd_abc123`)

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/prd_abc123/variants" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "variants": [
    {
      "id": "var_def456",
      "name": "Small Red",
      "price": 1999,
      "sale": null,
      "total_inventory": 50,
      "pounds": 0,
      "ounces": 8,
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:15:00Z"
    },
    {
      "id": "var_ghi789",
      "name": "Large Blue",
      "price": 2499,
      "sale": {
        "price": 1999,
        "end_date": "2023-12-31T23:59:59Z"
      },
      "total_inventory": 25,
      "pounds": 0,
      "ounces": 12,
      "created_at": "2023-01-01T10:30:00Z",
      "updated_at": "2023-01-01T11:00:00Z"
    }
  ]
}

Error Responses

Missing product ID

Status: 400 Bad Request

{
  "error": "Product ID is required",
  "code": "MISSING_FIELD"
}

Product not found

Status: 404 Not Found

{
  "error": "Product not found",
  "code": "NOT_FOUND"
}

Failed to get product

Status: 500 Internal Server Error

{
  "error": "Failed to get product",
  "code": "GET_ERROR"
}

Create Product Variant

Create a new variant for a specific product.

Endpoint: POST /api/v1/products/{id}/variants

Permission Required: Write

Path Parameters

Parameter	Type	Description
`id`	string	Product public ID (e.g., `prd_abc123`)

Request Body

{
  "name": "Medium Green",
  "description": "Medium size in green color",
  "price": 2199,
  "pounds": 0,
  "ounces": 10
}

Fields

Field	Type	Required	Description
`name`	string	Yes	Variant name
`description`	string	Yes	Variant description
`price`	integer	Yes	Price in cents (must be non-negative)
`pounds`	integer	Yes	Weight in pounds
`ounces`	integer	Yes	Additional weight in ounces

Request

curl -X POST "https://studio.easel.engineering/api/v1/products/prd_abc123/variants" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Medium Green",
    "description": "Medium size in green color",
    "price": 2199,
    "pounds": 0,
    "ounces": 10
  }'

Response

Returns the created variant.

Status: 201 Created

{
  "id": "var_jkl012",
  "name": "Medium Green",
  "price": 2199,
  "sale": null,
  "total_inventory": 0,
  "pounds": 0,
  "ounces": 10,
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z"
}

Error Responses

Missing product ID

Status: 400 Bad Request

{
  "error": "Product ID is required",
  "code": "MISSING_FIELD"
}

Invalid JSON body

Status: 400 Bad Request

{
  "error": "Invalid JSON body",
  "code": "INVALID_JSON"
}

Missing required field

Status: 400 Bad Request

{
  "error": "Variant name is required",
  "code": "MISSING_FIELD"
}

Invalid price

Status: 400 Bad Request

{
  "error": "Price must be non-negative",
  "code": "INVALID_FIELD"
}

Failed to create variant

Status: 500 Internal Server Error

{
  "error": "Failed to create variant",
  "code": "CREATE_ERROR"
}

Variant created but failed to retrieve

Status: 500 Internal Server Error

{
  "error": "Variant created but failed to retrieve",
  "code": "GET_ERROR"
}

Get Product Variant

Retrieve a single product variant by its ID.

Endpoint: GET /api/v1/products/{id}/variants/{variant_id}

Permission Required: Read

Path Parameters

Parameter	Type	Description
`id`	string	Product public ID (e.g., `prd_abc123`)
`variant_id`	string	Variant public ID (e.g., `var_def456`)

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/prd_abc123/variants/var_def456" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "id": "var_def456",
  "name": "Small Red",
  "price": 1999,
  "sale": null,
  "total_inventory": 50,
  "pounds": 0,
  "ounces": 8,
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:15:00Z"
}

Error Responses

Missing product ID

Status: 400 Bad Request

{
  "error": "Product ID is required",
  "code": "MISSING_FIELD"
}

Missing variant ID

Status: 400 Bad Request

{
  "error": "Variant ID is required",
  "code": "MISSING_FIELD"
}

Variant not found

Status: 404 Not Found

{
  "error": "Variant not found",
  "code": "NOT_FOUND"
}

Failed to get variant

Status: 500 Internal Server Error

{
  "error": "Failed to get variant",
  "code": "GET_ERROR"
}

Update Product Variant

Update an existing product variant's price and weight.

Endpoint: PUT /api/v1/products/{id}/variants/{variant_id}

Permission Required: Write

Path Parameters

Parameter	Type	Description
`id`	string	Product public ID (e.g., `prd_abc123`)
`variant_id`	string	Variant public ID (e.g., `var_def456`)

Request Body

{
  "price": 2299,
  "pounds": 0,
  "ounces": 9
}

Fields

Field	Type	Required	Description
`price`	integer	Yes	Price in cents (must be non-negative)
`pounds`	integer	Yes	Weight in pounds
`ounces`	integer	Yes	Additional weight in ounces

Request

curl -X PUT "https://studio.easel.engineering/api/v1/products/prd_abc123/variants/var_def456" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 2299,
    "pounds": 0,
    "ounces": 9
  }'

Response

Returns the updated variant.

Status: 200 OK

{
  "id": "var_def456",
  "name": "Small Red",
  "price": 2299,
  "sale": null,
  "total_inventory": 50,
  "pounds": 0,
  "ounces": 9,
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T13:30:00Z"
}

Error Responses

Missing product ID

Status: 400 Bad Request

{
  "error": "Product ID is required",
  "code": "MISSING_FIELD"
}

Missing variant ID

Status: 400 Bad Request

{
  "error": "Variant ID is required",
  "code": "MISSING_FIELD"
}

Invalid JSON body

Status: 400 Bad Request

{
  "error": "Invalid JSON body",
  "code": "INVALID_JSON"
}

Invalid price

Status: 400 Bad Request

{
  "error": "Price must be non-negative",
  "code": "INVALID_FIELD"
}

Variant not found

Status: 404 Not Found

{
  "error": "Variant not found",
  "code": "NOT_FOUND"
}

Failed to update variant

Status: 500 Internal Server Error

{
  "error": "Failed to update variant",
  "code": "UPDATE_ERROR"
}

Variant updated but failed to retrieve

Status: 500 Internal Server Error

{
  "error": "Variant updated but failed to retrieve",
  "code": "GET_ERROR"
}

Product Variant Object

Fields

Field	Type	Description
`id`	string	Variant public ID
`name`	string	Variant name
`price`	integer	Regular price in cents
`sale`	object\|null	Sale information if on sale
`total_inventory`	integer	Total inventory count
`pounds`	integer	Weight in pounds
`ounces`	integer	Additional weight in ounces
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Sale Object

When a variant is on sale, the sale field contains:

Field	Type	Description
`price`	integer	Sale price in cents
`end_date`	string	ISO 8601 timestamp when sale ends

Weight Calculation

Total weight = pounds + (ounces / 16)

Example: A variant with pounds: 1 and ounces: 8 weighs 1.5 pounds total.