{
  "openapi": "3.0.3",
  "info": {
    "title": "VTO Partner API",
    "version": "1.0.0",
    "description": "## Overview\n\nThe VTO Partner API gives you **full control over your Virtual Try-On catalog and digitalization process**. With this API, you can:\n\n- **Build and manage your product catalog** - Create brands, categories, products, and variants programmatically\n- **Upload and organize product images** - Manage all visual assets for your VTO experience\n- **Configure digitalization settings** - Define how each variant appears in the virtual try-on\n- **Control inventory availability** - Update stock status in real time. Out-of-stock variants stay visible with an out-of-stock label; to hide a variant, set its status to draft or archived\n- **Automate catalog updates** - Sync your existing product database with the VTO platform\n\nYou can create or update a ready-to-use catalog at any time, giving you the flexibility to manage your VTO experience independently without manual intervention.\n\n---\n\n## Setup\n\n1. Get your API key from your account manager\n2. Set the `api_key` variable in your requests\n3. Set `project_key` to your project slug\n\n## Authentication\n\nAll requests require the `X-API-Key` header.\n\n## Workflow Order\n\nWhen creating data from scratch, follow this order:\n\n1. **Images** - Upload images first (required for brands, categories, products)\n2. **Brands** - Create brands (required for products)\n3. **Categories** - Create categories (required for products)\n4. **Products** - Create products (requires brands, categories, images)\n5. **Variants** - Create variants with digitizer config (requires products)\n6. **Stock** - Update stock status for variants"
  },
  "servers": [
    {
      "url": "{base_url}",
      "description": "API Server",
      "variables": {
        "base_url": {
          "default": "https://api.pulpoar.com",
          "description": "Base URL for the API"
        }
      }
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "x-postman-collection-variables": [{ "key": "api_key", "value": "", "type": "string" }, { "key": "project_key", "value": "", "type": "string" }],
  "tags": [
    { "name": "1. Images", "description": "Upload and manage images for brands, categories, and products" },
    { "name": "2. Brands", "description": "Create and manage brands" },
    { "name": "3. Categories", "description": "Create and manage categories" },
    { "name": "4. Products", "description": "Create and manage products" },
    { "name": "5. Variants", "description": "Create, list, and update variants with digitizer config" },
    { "name": "6. Stock", "description": "Manage variant stock status" }
  ],
  "paths": {
    "/vto-partner/{project_key}/images": {
      "post": {
        "operationId": "upload-images",
        "summary": "Upload Images",
        "description": "**Step 1: Upload images first** - Images are required for creating brands, categories, and products.\n\nDownloads images from the provided URLs, validates them, and stores them in your organization's file storage.\n\n**Validation:**\n- Allowed types: JPEG, PNG, WebP\n- Max file size: 2MB\n- Max dimensions: 4096x4096\n\n**Important:** Save the returned `file_id` values - you'll need them for creating brands, categories, and products.",
        "tags": ["1. Images"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImageUploadRequest"
              },
              "example": {
                "images": [
                  {
                    "url": "https://example.com/brand-logo.jpg",
                    "title": "Brand Logo"
                  },
                  {
                    "url": "https://example.com/product-image.png",
                    "title": "Product Image"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Images processed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageUploadResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "get": {
        "operationId": "list-images",
        "summary": "List Images",
        "description": "List uploaded images for your project.\n\nReturns only image files (JPEG, PNG, WebP) that belong to your organization.",
        "tags": ["1. Images"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (default: 100, max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset (default: 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Images retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageListResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/vto-partner/{project_key}/brands": {
      "post": {
        "operationId": "create-brands",
        "summary": "Create Brands",
        "description": "**Step 2: Create brands** - Required before creating products.\n\nBatch create brands with upsert semantics. If a brand with the same slug exists, it will be updated with the provided image.",
        "tags": ["2. Brands"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BrandCreateRequest"
              },
              "example": {
                "brands": [
                  {
                    "name": "MAC Cosmetics",
                    "slug": "mac",
                    "image_id": "550e8400-e29b-41d4-a716-446655440000"
                  },
                  {
                    "name": "Urban Decay",
                    "slug": "urban-decay",
                    "image_id": "550e8400-e29b-41d4-a716-446655440001"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brands processed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandCreateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "get": {
        "operationId": "list-brands",
        "summary": "List Brands",
        "description": "List all brands (global, not project-scoped).",
        "tags": ["2. Brands"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (default: 100, max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset (default: 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Brands retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandListResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "patch": {
        "operationId": "update-brands",
        "summary": "Update Brands",
        "description": "Batch update brands (max 100 per request).\n\nUse `lookup=slug` for slug-based updates or `lookup=id` for UUID-based updates.",
        "tags": ["2. Brands"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "lookup",
            "in": "query",
            "description": "Lookup method: 'slug' for slug-based updates, 'id' for UUID-based updates",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["slug", "id"]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BrandUpdateRequest"
              },
              "example": {
                "updates": [
                  {
                    "key": "mac",
                    "updates": {
                      "name": "M.A.C Cosmetics",
                      "description": "Professional quality cosmetics"
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Brands updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BrandUpdateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/vto-partner/{project_key}/categories": {
      "post": {
        "operationId": "create-categories",
        "summary": "Create Categories",
        "description": "**Step 3: Create categories** - Required before creating products.\n\nBatch create categories with upsert semantics. If a category with the same slug exists, it will be updated with the provided image.",
        "tags": ["3. Categories"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CategoryCreateRequest"
              },
              "example": {
                "categories": [
                  {
                    "name": "Lipstick",
                    "slug": "lipstick",
                    "image_id": "550e8400-e29b-41d4-a716-446655440000"
                  },
                  {
                    "name": "Eyeshadow",
                    "slug": "eyeshadow",
                    "image_id": "550e8400-e29b-41d4-a716-446655440001"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Categories processed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryCreateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "get": {
        "operationId": "list-categories",
        "summary": "List Categories",
        "description": "List all categories (global, not project-scoped).",
        "tags": ["3. Categories"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (default: 100, max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset (default: 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Categories retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryListResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "patch": {
        "operationId": "update-categories",
        "summary": "Update Categories",
        "description": "Batch update categories (max 100 per request).\n\nUse `lookup=slug` for slug-based updates or `lookup=id` for UUID-based updates.",
        "tags": ["3. Categories"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "lookup",
            "in": "query",
            "description": "Lookup method: 'slug' for slug-based updates, 'id' for UUID-based updates",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["slug", "id"]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CategoryUpdateRequest"
              },
              "example": {
                "updates": [
                  {
                    "key": "lipstick",
                    "updates": {
                      "name": "Lipsticks & Lip Colors",
                      "description": "All lip products"
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Categories updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryUpdateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/vto-partner/{project_key}/products": {
      "post": {
        "operationId": "create-products",
        "summary": "Create Products",
        "description": "**Step 4: Create products** - Required before creating variants.\n\nBatch create products with upsert semantics. Requires brands, categories, and images to be created first.\n\nIf a product with the same slug exists:\n- Updates the product's image with the provided `image_id`\n- Links the product to the project if not already linked\n- Returns `updated` status instead of `created`",
        "tags": ["4. Products"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductCreateRequest"
              },
              "example": {
                "products": [
                  {
                    "name": "Velvet Matte Lipstick",
                    "slug": "velvet-matte-lipstick",
                    "brand_slug": "mac",
                    "category_slug": "lipstick",
                    "status": "published",
                    "image_id": "550e8400-e29b-41d4-a716-446655440000"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Products processed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductCreateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "get": {
        "operationId": "list-products",
        "summary": "List Products",
        "description": "List products linked to your project with optional filtering.",
        "tags": ["4. Products"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by status: published, draft, archived",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["published", "draft", "archived"]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (default: 100, max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset (default: 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Products retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductListResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "patch": {
        "operationId": "update-products",
        "summary": "Update Products",
        "description": "Batch update products within project scope (max 100 per request).\n\nUse `lookup=slug` for slug-based updates or `lookup=id` for UUID-based updates.",
        "tags": ["4. Products"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "lookup",
            "in": "query",
            "description": "Lookup method: 'slug' for slug-based updates, 'id' for UUID-based updates",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["slug", "id"]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductUpdateRequest"
              },
              "example": {
                "updates": [
                  {
                    "key": "velvet-matte-lipstick",
                    "updates": {
                      "name": "New Product Name",
                      "status": "published"
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Products updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductUpdateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/vto-partner/{project_key}/variants": {
      "post": {
        "operationId": "create-variants",
        "summary": "Create Variants",
        "description": "**Step 5: Create variants** - Requires products to be created first.\n\nCreate variants with digitizer configuration for virtual try-on.\n\n## Config Object\n\n- `module` (required): `\"makeup\"` or `\"nailpolish\"`\n- `type` (required): Type ID (see tables below)\n- `color` (required): Hex color code (e.g., `#E35169`)\n- `opacity` (optional): Color opacity 0-1, overrides type default\n\n## Makeup Types (0-14)\n\n| Type | Category | Default Opacity |\n|------|----------|----------------|\n| 0 | Foundation | 0.8 |\n| 1 | Blush | 0.5 |\n| 2 | Contour | 0.8 |\n| 3 | Eyeshadow | 1.0 |\n| 4 | Eyeliner | 1.0 |\n| 5 | Eye Pencil | 1.0 |\n| 6 | Highlighter | 1.0 |\n| 7 | Mascara | 1.0 |\n| 8 | Lipstick | 1.0 |\n| 9 | Lip Pencil | 0.8 |\n| 10 | Eyebrow | 1.0 |\n| 11 | Funmask | 1.0 |\n| 12 | Concealer | 1.0 |\n| 13 | Bronzer | 0.8 |\n| 14 | Lip & Cheek | 0.5 |\n\n## Nailpolish Types (0-2)\n\n| Type | Mode | Default Opacity |\n|------|------|----------------|\n| 0 | Color (solid) | 0.8 |\n| 1 | Textured | 0.8 |\n| 2 | WithEffect | 0.8 |",
        "tags": ["5. Variants"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "lookup",
            "in": "query",
            "description": "How to interpret `product_key`: `id` for UUID, `slug` for slug",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["id", "slug"]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VariantCreateRequest"
              },
              "examples": {
                "makeup": {
                  "summary": "Makeup variant",
                  "value": {
                    "variants": [
                      {
                        "product_key": "velvet-matte-lipstick",
                        "variant": {
                          "name": "Red Lipstick",
                          "slug": "red-lipstick",
                          "thumbnail_color": "#E35169",
                          "config": {
                            "module": "makeup",
                            "type": 8,
                            "color": "#E35169"
                          }
                        }
                      },
                      {
                        "product_key": "velvet-matte-lipstick",
                        "variant": {
                          "name": "Custom Opacity Example",
                          "slug": "custom-opacity",
                          "thumbnail_color": "#151518",
                          "config": {
                            "module": "makeup",
                            "type": 5,
                            "color": "#151518",
                            "opacity": 0.36
                          }
                        }
                      }
                    ]
                  }
                },
                "nailpolish": {
                  "summary": "Nailpolish variant",
                  "value": {
                    "variants": [
                      {
                        "product_key": "nailpolish-product-slug",
                        "variant": {
                          "name": "Pink Nailpolish",
                          "slug": "pink-nailpolish",
                          "thumbnail_color": "#e5488c",
                          "config": {
                            "module": "nailpolish",
                            "type": 0,
                            "color": "#e5488c"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Variants processed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VariantCreateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "get": {
        "operationId": "list-variants",
        "summary": "List Variants",
        "description": "List variants in your project with optional filtering.",
        "tags": ["5. Variants"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filter by variant status",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["published", "draft", "archived"]
            }
          },
          {
            "name": "stock_status",
            "in": "query",
            "description": "Filter by stock status",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["in-stock", "out-of-stock"]
            }
          },
          {
            "name": "slugs",
            "in": "query",
            "description": "Comma-separated slugs to filter",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_slug",
            "in": "query",
            "description": "Only return variants with a slug",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (max: 1000)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Variants retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VariantsListResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      },
      "patch": {
        "operationId": "update-variants",
        "summary": "Update Variants",
        "description": "Batch update variants (max 100 per request).\n\nUse `lookup=slug` for slug-based updates or `lookup=id` for UUID-based updates.\n\n**Tip:** For stock-only updates, consider the Stock API which supports larger batches (200 vs 100).",
        "tags": ["5. Variants"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "lookup",
            "in": "query",
            "description": "Lookup method: 'slug' for slug-based updates, 'id' for UUID-based updates",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["slug", "id"]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VariantUpdateRequest"
              },
              "example": {
                "updates": [
                  {
                    "key": "red-lipstick",
                    "updates": { "stock_status": "out-of-stock" }
                  },
                  {
                    "key": "blue-eyeshadow",
                    "updates": { "name": "New Blue", "web_link": "https://example.com" }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Variants updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VariantUpdateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/vto-partner/{project_key}/variants/{variant_key}": {
      "get": {
        "operationId": "get-single-variant",
        "summary": "Get Single Variant",
        "description": "Get a single variant by UUID or slug.",
        "tags": ["5. Variants"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "variant_key",
            "in": "path",
            "description": "Variant UUID or slug",
            "required": true,
            "schema": {
              "type": "string",
              "example": "red-lipstick"
            }
          },
          {
            "name": "lookup",
            "in": "query",
            "description": "Force lookup method when the key is ambiguous",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["id", "slug"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Variant retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VariantSingleResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/vto-partner/{project_key}/stock": {
      "get": {
        "operationId": "get-stock",
        "summary": "Get Stock",
        "description": "Get stock status for variants in your project.",
        "tags": ["6. Stock"],
        "parameters": [
          {
            "name": "project_key",
            "in": "path",
            "description": "Project slug or UUID",
            "required": true,
            "schema": {
              "type": "string",
              "example": "your-project-slug"
            }
          },
          {
            "name": "variants",
            "in": "query",
            "description": "Comma-separated variant slugs to filter",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "has_slug",
            "in": "query",
            "description": "Only return variants with non-empty slug",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (default: 1000, max: 5000)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5000,
              "default": 1000
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Stock status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StockGetResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/vto-partner/stock": {
      "patch": {
        "operationId": "update-stock",
        "summary": "Update Stock",
        "description": "**Step 6: Update stock status** - Use variant slugs to update availability.\n\nUpdate stock status for one or more variants (max 200 per request). Requires variants to have slugs assigned.\n\n**Note:** `stock_status` can also be updated via the Variants API if you need to update multiple fields at once or lookup by UUID.",
        "tags": ["6. Stock"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StockUpdateRequest"
              },
              "example": {
                "project_key": "your-project-slug",
                "updates": [
                  { "variant_slug": "red-lipstick", "stock_status": "out-of-stock" },
                  { "variant_slug": "pink-nailpolish", "stock_status": "in-stock" }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Stock updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StockUpdateResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "Validation error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "Forbidden": {
        "description": "API key not authorized for this project",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [false],
            "example": false
          },
          "error": {
            "type": "string",
            "description": "Error message",
            "example": "Validation failed"
          },
          "details": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Detailed error reasons",
            "example": ["Invalid stock_status value"]
          },
          "retry_after": {
            "type": "integer",
            "description": "Seconds until rate limit resets (only present on 429 responses)",
            "example": 900
          }
        },
        "required": ["success", "error"]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": { "type": "integer", "description": "Total number of results", "example": 100 },
          "limit": { "type": "integer", "description": "Results per page", "example": 100 },
          "offset": { "type": "integer", "description": "Current offset", "example": 0 },
          "has_next": { "type": "boolean", "description": "Whether more results exist", "example": false },
          "next_offset": { "type": "integer", "nullable": true, "description": "Offset for next page, or null if no more results" }
        },
        "required": ["total", "limit", "offset", "has_next", "next_offset"]
      },
      "ImageId": {
        "type": "string",
        "format": "uuid",
        "description": "File UUID from image upload",
        "example": "550e8400-e29b-41d4-a716-446655440000"
      },
      "VariantConfig": {
        "type": "object",
        "description": "Digitizer configuration for virtual try-on",
        "properties": {
          "module": {
            "type": "string",
            "enum": ["makeup", "nailpolish"],
            "description": "VTO module type"
          },
          "type": {
            "type": "integer",
            "minimum": 0,
            "description": "Type ID (0-14 for makeup, 0-2 for nailpolish)"
          },
          "color": {
            "type": "string",
            "pattern": "^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$",
            "description": "Hex color code (defaults to #000000 if not provided)",
            "default": "#000000",
            "example": "#E35169"
          },
          "opacity": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Color opacity 0-1, overrides type default"
          }
        },
        "required": ["module", "type"]
      },
      "ImageUploadRequest": {
        "type": "object",
        "properties": {
          "images": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "object",
              "properties": {
                "url": { "type": "string", "format": "uri", "description": "Public URL of the image" },
                "title": { "type": "string", "description": "Image title (defaults to filename)" }
              },
              "required": ["url"]
            }
          }
        },
        "required": ["images"]
      },
      "ImageUploadResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "project_id": { "type": "string", "format": "uuid" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "url": { "type": "string", "format": "uri" },
                "status": { "type": "string", "enum": ["uploaded", "failed"] },
                "file_id": { "type": "string", "format": "uuid", "description": "Use this ID for image_id references" },
                "width": { "type": "integer" },
                "height": { "type": "integer" },
                "error": { "type": "string", "description": "Error message when status is failed" }
              },
              "required": ["url", "status"]
            }
          }
        },
        "required": ["success", "project_id", "results"]
      },
      "ImageListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "pagination": { "$ref": "#/components/schemas/Pagination" },
          "images": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "format": "uuid", "description": "File UUID (use this for image_id references)" },
                "title": { "type": "string", "nullable": true },
                "filename": { "type": "string" },
                "type": { "type": "string", "description": "MIME type (image/jpeg, image/png, image/webp)" },
                "width": { "type": "integer" },
                "height": { "type": "integer" },
                "filesize": { "type": "integer", "description": "File size in bytes" },
                "date_created": { "type": "string", "format": "date-time" }
              },
              "required": ["id", "filename", "type", "width", "height", "filesize", "date_created"]
            }
          }
        },
        "required": ["success", "pagination", "images"]
      },
      "BrandCreateRequest": {
        "type": "object",
        "properties": {
          "brands": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string", "description": "Display name" },
                "slug": { "type": "string", "description": "URL-safe identifier (auto-lowercased)" },
                "image_id": { "$ref": "#/components/schemas/ImageId" }
              },
              "required": ["name", "slug", "image_id"]
            }
          }
        },
        "required": ["brands"]
      },
      "BrandCreateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "processed": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": { "type": "string" },
                "status": { "type": "string", "enum": ["created", "updated", "image_not_found", "image_access_denied", "image_invalid_type"] },
                "id": { "type": "string", "format": "uuid" },
                "message": { "type": "string" }
              },
              "required": ["slug", "status"]
            }
          }
        },
        "required": ["success", "processed", "results"]
      },
      "BrandListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "pagination": { "$ref": "#/components/schemas/Pagination" },
          "brands": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "format": "uuid" },
                "name": { "type": "string" },
                "slug": { "type": "string" },
                "description": { "type": "string", "nullable": true },
                "image": { "type": "object", "nullable": true }
              },
              "required": ["id", "name", "slug"]
            }
          }
        },
        "required": ["success", "pagination", "brands"]
      },
      "BrandUpdateRequest": {
        "type": "object",
        "properties": {
          "updates": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string", "description": "Brand slug" },
                "updates": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "slug": { "type": "string" },
                    "description": { "type": "string" },
                    "image_id": { "$ref": "#/components/schemas/ImageId" }
                  }
                }
              },
              "required": ["key", "updates"]
            }
          }
        },
        "required": ["updates"]
      },
      "BrandUpdateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "processed": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string" },
                "status": {
                  "type": "string",
                  "enum": ["updated", "not_found", "slug_duplicate", "image_not_found", "image_access_denied", "image_invalid_type"]
                },
                "brand": { "type": "object" },
                "message": { "type": "string" }
              },
              "required": ["key", "status"]
            }
          }
        },
        "required": ["success", "processed", "results"]
      },
      "CategoryCreateRequest": {
        "type": "object",
        "properties": {
          "categories": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string", "description": "Display name" },
                "slug": { "type": "string", "description": "URL-safe identifier (auto-lowercased)" },
                "image_id": { "$ref": "#/components/schemas/ImageId" }
              },
              "required": ["name", "slug", "image_id"]
            }
          }
        },
        "required": ["categories"]
      },
      "CategoryCreateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "processed": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": { "type": "string" },
                "status": { "type": "string", "enum": ["created", "updated", "image_not_found", "image_access_denied", "image_invalid_type"] },
                "id": { "type": "string", "format": "uuid" },
                "message": { "type": "string" }
              },
              "required": ["slug", "status"]
            }
          }
        },
        "required": ["success", "processed", "results"]
      },
      "CategoryListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "pagination": { "$ref": "#/components/schemas/Pagination" },
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "format": "uuid" },
                "name": { "type": "string" },
                "slug": { "type": "string" },
                "description": { "type": "string", "nullable": true },
                "image": { "type": "object", "nullable": true }
              },
              "required": ["id", "name", "slug"]
            }
          }
        },
        "required": ["success", "pagination", "categories"]
      },
      "CategoryUpdateRequest": {
        "type": "object",
        "properties": {
          "updates": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string", "description": "Category slug" },
                "updates": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "slug": { "type": "string" },
                    "description": { "type": "string" },
                    "image_id": { "$ref": "#/components/schemas/ImageId" }
                  }
                }
              },
              "required": ["key", "updates"]
            }
          }
        },
        "required": ["updates"]
      },
      "CategoryUpdateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "processed": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string" },
                "status": {
                  "type": "string",
                  "enum": ["updated", "not_found", "slug_duplicate", "image_not_found", "image_access_denied", "image_invalid_type"]
                },
                "category": { "type": "object" },
                "message": { "type": "string" }
              },
              "required": ["key", "status"]
            }
          }
        },
        "required": ["success", "processed", "results"]
      },
      "ProductCreateRequest": {
        "type": "object",
        "properties": {
          "products": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string", "description": "Display name" },
                "slug": { "type": "string", "description": "URL-safe identifier (auto-lowercased)" },
                "brand_slug": { "type": "string", "description": "Slug of existing brand" },
                "category_slug": { "type": "string", "description": "Slug of existing category" },
                "image_id": { "$ref": "#/components/schemas/ImageId" },
                "status": { "type": "string", "enum": ["published", "draft", "archived"], "default": "draft" }
              },
              "required": ["name", "slug", "brand_slug", "category_slug", "image_id"]
            }
          }
        },
        "required": ["products"]
      },
      "ProductCreateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "processed": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": { "type": "string" },
                "status": {
                  "type": "string",
                  "enum": [
                    "created",
                    "updated",
                    "link_failed",
                    "updated_link_failed",
                    "brand_not_found",
                    "category_not_found",
                    "image_not_found",
                    "image_access_denied",
                    "image_invalid_type"
                  ]
                },
                "id": { "type": "string", "format": "uuid" },
                "message": { "type": "string" }
              },
              "required": ["slug", "status"]
            }
          }
        },
        "required": ["success", "processed", "results"]
      },
      "ProductListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "pagination": { "$ref": "#/components/schemas/Pagination" },
          "products": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "format": "uuid" },
                "name": { "type": "string" },
                "slug": { "type": "string" },
                "status": { "type": "string", "enum": ["published", "draft", "archived"] },
                "description": { "type": "string", "nullable": true },
                "brand": { "type": "object", "nullable": true },
                "category": { "type": "object", "nullable": true },
                "image": { "type": "object", "nullable": true }
              },
              "required": ["id", "name", "slug", "status"]
            }
          }
        },
        "required": ["success", "pagination", "products"]
      },
      "ProductUpdateRequest": {
        "type": "object",
        "properties": {
          "updates": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string", "description": "Product slug" },
                "updates": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string", "maxLength": 255 },
                    "slug": { "type": "string" },
                    "status": { "type": "string", "enum": ["published", "draft", "archived"] },
                    "description": { "type": "string", "maxLength": 10000 },
                    "brand_slug": { "type": "string" },
                    "category_slug": { "type": "string" },
                    "image_id": { "$ref": "#/components/schemas/ImageId" }
                  }
                }
              },
              "required": ["key", "updates"]
            }
          }
        },
        "required": ["updates"]
      },
      "ProductUpdateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "processed": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string" },
                "status": {
                  "type": "string",
                  "enum": [
                    "updated",
                    "not_found",
                    "slug_duplicate",
                    "brand_not_found",
                    "category_not_found",
                    "image_not_found",
                    "image_access_denied",
                    "image_invalid_type"
                  ]
                },
                "product": { "type": "object" },
                "message": { "type": "string" }
              },
              "required": ["key", "status"]
            }
          }
        },
        "required": ["success", "processed", "results"]
      },
      "VariantCreateRequest": {
        "type": "object",
        "properties": {
          "variants": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "product_key": { "type": "string", "description": "Product ID or slug (based on lookup param)" },
                "variant": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string", "description": "Display name" },
                    "slug": { "type": "string", "description": "URL-safe identifier" },
                    "custom_slug": { "type": "string", "description": "Custom identifier (not used for lookups)" },
                    "status": { "type": "string", "enum": ["published", "draft", "archived"] },
                    "stock_status": { "type": "string", "enum": ["in-stock", "out-of-stock"] },
                    "thumbnail_color": {
                      "type": "string",
                      "pattern": "^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$",
                      "description": "Hex color code"
                    },
                    "web_link": { "type": "string", "format": "uri", "description": "Product page URL" },
                    "barcode": { "type": "string", "description": "Barcode" },
                    "config": { "$ref": "#/components/schemas/VariantConfig" }
                  },
                  "required": ["name", "thumbnail_color"]
                }
              },
              "required": ["product_key", "variant"]
            }
          }
        },
        "required": ["variants"]
      },
      "VariantCreateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "project_id": { "type": "string", "format": "uuid" },
          "created": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "product_key": { "type": "string" },
                "status": { "type": "string", "enum": ["created", "product_not_found", "slug_duplicate", "validation_error", "error"] },
                "variant": { "$ref": "#/components/schemas/VariantRecord" },
                "message": { "type": "string" }
              },
              "required": ["product_key", "status"]
            }
          }
        },
        "required": ["success", "project_id", "created", "results"]
      },
      "VariantRecord": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid", "description": "Variant UUID" },
          "name": { "type": "string", "description": "Display name" },
          "slug": { "type": "string", "description": "URL-safe identifier" },
          "custom_slug": { "type": "string", "nullable": true, "description": "Custom identifier (not used for lookups)" },
          "status": { "type": "string", "enum": ["published", "draft", "archived"] },
          "stock_status": { "type": "string", "enum": ["in-stock", "out-of-stock"] },
          "thumbnail_color": { "type": "string", "description": "Hex color code", "example": "#FF0000" },
          "web_link": { "type": "string", "format": "uri", "description": "Product page URL" },
          "barcode": { "type": "string", "nullable": true, "description": "Barcode" },
          "config": { "$ref": "#/components/schemas/VariantConfig" },
          "product_slug": { "type": "string", "nullable": true, "description": "Linked product slug" },
          "date_updated": { "type": "string", "format": "date-time", "nullable": true }
        },
        "required": ["id", "name", "slug", "status", "stock_status"]
      },
      "VariantsListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "project_id": { "type": "string", "format": "uuid" },
          "pagination": { "$ref": "#/components/schemas/Pagination" },
          "variants": { "type": "array", "items": { "$ref": "#/components/schemas/VariantRecord" } }
        },
        "required": ["success", "project_id", "pagination", "variants"]
      },
      "VariantSingleResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "project_id": { "type": "string", "format": "uuid" },
          "variant": { "$ref": "#/components/schemas/VariantRecord" }
        },
        "required": ["success", "project_id", "variant"]
      },
      "VariantUpdateRequest": {
        "type": "object",
        "properties": {
          "updates": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string", "description": "Variant identifier (slug or UUID depending on lookup param)" },
                "updates": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "slug": { "type": "string" },
                    "custom_slug": { "type": "string" },
                    "product_slug": { "type": "string", "description": "Relink variant to a different product by slug" },
                    "status": { "type": "string", "enum": ["published", "draft", "archived"] },
                    "stock_status": { "type": "string", "enum": ["in-stock", "out-of-stock"] },
                    "thumbnail_color": { "type": "string" },
                    "web_link": { "type": "string", "format": "uri" },
                    "barcode": { "type": "string" },
                    "config": { "$ref": "#/components/schemas/VariantConfig" }
                  }
                }
              },
              "required": ["key", "updates"]
            }
          }
        },
        "required": ["updates"]
      },
      "VariantUpdateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "project_id": { "type": "string", "format": "uuid" },
          "processed": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": { "type": "string" },
                "status": { "type": "string", "enum": ["updated", "not_found", "product_not_found", "slug_duplicate", "error"] },
                "variant": { "$ref": "#/components/schemas/VariantRecord" },
                "message": { "type": "string" }
              },
              "required": ["key", "status"]
            }
          }
        },
        "required": ["success", "project_id", "processed", "results"]
      },
      "StockRecord": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "stock_status": { "type": "string", "enum": ["in-stock", "out-of-stock"] },
          "date_updated": { "type": "string", "format": "date-time", "nullable": true }
        },
        "required": ["id", "slug", "name", "stock_status"]
      },
      "StockGetResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "project_id": { "type": "string", "format": "uuid" },
          "pagination": { "$ref": "#/components/schemas/Pagination" },
          "variants": { "type": "array", "items": { "$ref": "#/components/schemas/StockRecord" } }
        },
        "required": ["success", "project_id", "pagination", "variants"]
      },
      "StockUpdateRequest": {
        "type": "object",
        "properties": {
          "project_key": { "type": "string", "description": "Project slug or UUID" },
          "updates": {
            "type": "array",
            "maxItems": 200,
            "items": {
              "type": "object",
              "properties": {
                "variant_slug": { "type": "string", "description": "Variant slug (case-insensitive)" },
                "stock_status": { "type": "string", "enum": ["in-stock", "out-of-stock"] }
              },
              "required": ["variant_slug", "stock_status"]
            }
          }
        },
        "required": ["project_key", "updates"]
      },
      "StockUpdateResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "project_id": { "type": "string", "format": "uuid" },
          "processed": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "variant_slug": { "type": "string" },
                "status": { "type": "string", "enum": ["updated", "not_found", "conflict", "error"] },
                "stock_status": { "type": "string", "enum": ["in-stock", "out-of-stock"] },
                "message": { "type": "string" }
              },
              "required": ["variant_slug", "status"]
            }
          }
        },
        "required": ["success", "project_id", "processed", "results"]
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "All API requests require authentication via the X-API-Key header. Set the `api_key` variable in your environment."
      }
    }
  }
}
