Skip to main content

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
StepRequires
1. Images–
2. BrandsImages
3. CategoriesImages
4. ProductsBrands, categories, images
5. VariantsProducts
6. StockVariants 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" }
]
}'
tip

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​

FieldRequiredDescription
moduleYes"makeup" or "nailpolish"
typeYesType ID (see the tables below)
colorYesHex color, for example #E35169
opacityNo0 to 1. Overrides the type's default opacity.

Makeup types​

TypeCategoryDefault opacity
0Foundation0.8
1Blush0.5
2Contour0.8
3Eyeshadow1.0
4Eyeliner1.0
5Eye Pencil1.0
6Highlighter1.0
7Mascara1.0
8Lipstick1.0
9Lip Pencil0.8
10Eyebrow1.0
11Funmask1.0
12Concealer1.0
13Bronzer0.8
14Lip & Cheek0.5

Nail polish types​

TypeModeDefault opacity
0Color (solid)0.8
1Textured0.8
2With effect0.8
Use your SKU as the slug

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"
ParameterDescription
statusFilter by variant status
stock_statusFilter by stock status
slugsComma-separated slugs
has_slugOnly variants that have a slug
limitResults per page (max 1000)
offsetPagination offset

For all endpoints and fields, see the API reference.