跳转到内容

Products & Catalog

此内容尚不支持你的语言。

A product has a base SKU, title, description, price, and optional variants (size, colour, etc.).

{
"id": "uuid",
"title": "Acme Ceramic Mug",
"slug": "acme-ceramic-mug",
"description": "...",
"sku": "ACME-MUG",
"price": 24.00,
"currency": "USD",
"inventory_quantity": 142,
"weight": 0.4,
"weight_unit": "kg",
"is_active": true,
"categories": [{ "id": "uuid", "name": "Gear", "slug": "gear" }]
}
Terminal window
curl -X POST /api/v1/products \
-H "Authorization: Bearer <key>" \
-H "Content-Type: application/json" \
-d '{
"title": "Acme Ceramic Mug",
"slug": "acme-ceramic-mug",
"sku": "ACME-MUG",
"price": 24.00,
"currency": "USD",
"inventory_quantity": 142,
"weight": 0.4,
"weight_unit": "kg",
"is_active": true
}'

Products can have variants for size, colour, etc. Each variant has its own SKU, price, and inventory.

Terminal window
# List variants
GET /api/v1/products/:id/variants
# Create variant
POST /api/v1/products/:id/variants
{
"sku": "ACME-MUG-LARGE",
"title": "Large",
"price": 24.00,
"inventory_quantity": 100
}

Products belong to one or more categories. Categories are managed separately and linked via product_categories.

Terminal window
# List categories
GET /api/v1/categories
# Products in a category
GET /api/v1/products?category=gear
Terminal window
# Upload image
POST /api/v1/products/:id/images
Content-Type: multipart/form-data
# List images
GET /api/v1/products/:id/images

Stock levels are tracked per product (or per variant). The checkout reserves inventory atomically when a cart is created.

Terminal window
# Check stock
GET /api/v1/products/:id
# → inventory_quantity: 142
# Adjust stock
PATCH /api/v1/products/:id
{ "inventory_quantity": 250 }

Products should include weight data for accurate shipping calculation:

{
"weight": 1.1,
"weight_unit": "kg"
}

Weight units: kg, lb, oz. Stored internally in kg.