Skip to main content

​
Overview

The Product Variants API allows you to manage different variations of a product (e.g., different sizes, colors, or configurations). Each variant has its own SKU, price, and stock tracking. Base URL: http://localhost:8083

​
Create product variant

Create a new variant for a product. Requires ADMIN role.

​
Path parameters

​
productId
integer
required
Product ID to add variant to

​
Body parameters

​
sku
string
required
Unique SKU (Stock Keeping Unit) for this variant
​
name
string
required
Variant name (e.g., “Large”, “Blue”, “128GB”)
​
attributes
object
required
Variant attributes as key-value pairs
​
price
number
required
Price for this variant. Can differ from base product price.
​
stock
integer
required
Initial stock quantity
​
imageUrl
string
Optional variant-specific image URL

​
Example

curl -X POST http://localhost:8083/products/10/variants \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "TSHIRT-BLU-L",
    "name": "Blue - Large",
    "attributes": {
      "color": "Blue",
      "size": "L"
    },
    "price": 29.99,
    "stock": 50
  }'

​
List product variants

Get all variants for a specific product.

​
Path parameters

​
productId
integer
required
Product ID

​
Example

curl http://localhost:8083/products/10/variants

​
Update product variant

Update an existing product variant. Requires ADMIN role.

​
Path parameters

​
productId
integer
required
Product ID
​
variantId
integer
required
Variant ID to update

​
Body parameters

​
name
string
Updated variant name
​
attributes
object
Updated variant attributes
​
price
number
Updated price
​
stock
integer
Updated stock quantity
​
imageUrl
string
Updated image URL

​
Example

curl -X PUT http://localhost:8083/products/10/variants/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 24.99,
    "stock": 75
  }'

​
Delete product variant

Delete a product variant. Requires ADMIN role.

​
Path parameters

​
productId
integer
required
Product ID
​
variantId
integer
required
Variant ID to delete

​
Example

curl -X DELETE http://localhost:8083/products/10/variants/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Variant attributes

Variants use flexible key-value attributes. Common attribute keys include:
  • size: Clothing sizes (XS, S, M, L, XL, XXL)
  • dimensions: Physical dimensions (e.g., “10x15cm”)
  • capacity: Volume or capacity (e.g., “500ml”, “1L”)
  • color: Color name (e.g., “Red”, “Blue”, “Black”)
  • hexColor: Hex color code for precise color matching (e.g., “#FF0000”)
  • finish: Surface finish (e.g., “Matte”, “Glossy”, “Metallic”)
  • storage: Storage capacity for electronics (e.g., “64GB”, “256GB”)
  • memory: RAM amount (e.g., “8GB”, “16GB”)
  • processor: Processor type or speed
  • material: Material composition (e.g., “Cotton”, “Polyester”, “Leather”)

​
Next steps

Products API

Manage parent products

Inventory API

Track variant stock levels

Build docs developers (and LLMs) love

Get started for freeTalk to us