Catalog workflow
When you create a catalog from scratch, create the items in this order, because each step depends on the ones before it:
1. Images → 2. Brands → 3. Categories → 4. Products → 5. Variants → 6. Stock
| Step | Requires |
|---|---|
| 1. Images | – |
| 2. Brands | Images |
| 3. Categories | Images |
| 4. Products | Brands, categories, images |
| 5. Variants | Products |
| 6. Stock | Variants with slugs |
All examples use:
BASE=https://api.pulpoar.com/vto-partner/<project-key>
KEY=<api-key>
1. Upload images
The API downloads images from your URLs, validates them and stores them.
- Allowed types: JPEG, PNG, WebP
- Max file size: 2 MB
- Max dimensions: 4096 × 4096
curl -X POST "$BASE/images" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{
"images": [
{ "url": "https://example.com/brand-logo.jpg", "title": "Brand Logo" },
{ "url": "https://example.com/product-image.png", "title": "Product Image" }
]
}'
Save the returned file_id values. You need them as image_id for brands, categories and products.
2. Create brands
curl -X POST "$BASE/brands" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{
"brands": [
{ "name": "Example Brand", "slug": "example-brand", "image_id": "<file_id>" }
]
}'
3. Create categories
curl -X POST "$BASE/categories" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{
"categories": [
{ "name": "Lipstick", "slug": "lipstick", "image_id": "<file_id>" }
]
}'
4. Create products
Products reference brands and categories by slug:
curl -X POST "$BASE/products" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{
"products": [
{
"name": "Velvet Matte Lipstick",
"slug": "velvet-matte-lipstick",
"brand_slug": "example-brand",
"category_slug": "lipstick",
"status": "published",
"image_id": "<file_id>"
}
]
}'
If a product with the same slug exists, its image is updated, it's linked to the project if needed, and the response status is updated instead of created.
5. Create variants
Variants are the shades users apply. Each variant has a digitalization config (config) that defines how it looks in the try-on. It's the same setting as Digitalization in Studio:
curl -X POST "$BASE/variants" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{
"variants": [
{
"product_key": "velvet-matte-lipstick",
"variant": {
"name": "Red Lipstick",
"slug": "red-lipstick",
"thumbnail_color": "#E35169",
"config": { "module": "makeup", "type": 8, "color": "#E35169" }
}
}
]
}'
Config object
| Field | Required | Description |
|---|---|---|
module | Yes | "makeup" or "nailpolish" |
type | Yes | Type ID (see the tables below) |
color | Yes | Hex color, for example #E35169 |
opacity | No | 0 to 1. Overrides the type's default opacity. |
Makeup types
| Type | Category | Default opacity |
|---|---|---|
| 0 | Foundation | 0.8 |
| 1 | Blush | 0.5 |
| 2 | Contour | 0.8 |
| 3 | Eyeshadow | 1.0 |
| 4 | Eyeliner | 1.0 |
| 5 | Eye Pencil | 1.0 |
| 6 | Highlighter | 1.0 |
| 7 | Mascara | 1.0 |
| 8 | Lipstick | 1.0 |
| 9 | Lip Pencil | 0.8 |
| 10 | Eyebrow | 1.0 |
| 11 | Funmask | 1.0 |
| 12 | Concealer | 1.0 |
| 13 | Bronzer | 0.8 |
| 14 | Lip & Cheek | 0.5 |
Nail polish types
| Type | Mode | Default opacity |
|---|---|---|
| 0 | Color (solid) | 0.8 |
| 1 | Textured | 0.8 |
| 2 | With effect | 0.8 |
Variant slugs are what you pass to applyVariants and the stock API. Using your own SKU as the slug keeps both systems aligned.
6. Update stock
Update stock by variant slug, up to 200 updates per request:
curl -X PATCH "https://api.pulpoar.com/vto-partner/stock" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{
"project_key": "<project-key>",
"updates": [
{ "variant_slug": "red-lipstick", "stock_status": "out-of-stock" },
{ "variant_slug": "pink-nailpolish", "stock_status": "in-stock" }
]
}'
stock_status is either in-stock or out-of-stock.
Updating existing items
PATCH endpoints update items in batches. For variants (up to 100 per request), choose the lookup with lookup=slug or lookup=id:
curl -X PATCH "$BASE/variants?lookup=slug" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{
"updates": [
{ "key": "red-lipstick", "updates": { "stock_status": "out-of-stock" } },
{ "key": "blue-eyeshadow", "updates": { "name": "New Blue", "web_link": "https://example.com" } }
]
}'
For stock-only changes, use the stock endpoint. It supports larger batches (200 vs 100).
Reading data
List endpoints support filters and pagination. For example, to list variants:
curl "$BASE/variants?stock_status=in-stock&has_slug=true&limit=100&offset=0" \
-H "X-API-Key: $KEY"
| Parameter | Description |
|---|---|
status | Filter by variant status |
stock_status | Filter by stock status |
slugs | Comma-separated slugs |
has_slug | Only variants that have a slug |
limit | Results per page (max 1000) |
offset | Pagination offset |
For all endpoints and fields, see the API reference.