> ## Documentation Index > Fetch the complete documentation index at: https://docs.vambe.me/llms.txt > Use this file to discover all available pages before exploring further. # Create products > Create and update products without deleting existing ones. This endpoint only creates new products and updates existing ones. ## Overview Create or update products in a product block WITHOUT deleting existing ones. This endpoint is additive - it only creates new products and updates existing ones based on `external_id`, leaving other products unchanged. Perfect for incrementally adding products to your catalog without affecting the rest. ## Use Cases * **Add New Products**: Add products as they become available * **Update Specific Products**: Update only certain products without touching others * **Incremental Sync**: Sync new/changed products without full catalog refresh * **Safe Updates**: Modify products without risking deletion of others ## Authentication ``` x-api-key: your_api_key_here ``` ## Path Parameters | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ----------------------------------- | | `promptBlockId` | string | Yes | Product block ID to add products to | ## Request Body Array of product objects (1-2000 products): | Field | Type | Required | Description | | ------------- | ------ | -------- | ---------------------------------------------------- | | `name` | string | Yes | Product name | | `description` | string | Yes | Natural language description for AI (max 8192 chars) | | `price` | number | Yes | Product price (must be positive) | | `currency` | string | Yes | Currency code (USD, EUR, CLP, etc.) | | `type` | string | Yes | Product type (PRODUCT or SERVICE) | | `external_id` | string | Yes | Your unique identifier for this product | | `file_url` | string | No | URL to product image or file | | `sku` | string | No | Product SKU. Falls back to `sku` key in metadata | | `metadata` | array | Yes | Array of key-value pairs for additional data | **Description Best Practice**: Use natural language that helps AI understand the product. Avoid URLs, prices (already in price field), or structured data. Focus on features, benefits, and use cases. ## Example Request ```bash theme={null} curl --request POST \ 'https://api.vambe.me/api/public/product/create/block-abc123' \ --header 'Content-Type: application/json' \ --header 'x-api-key: your_api_key_here' \ --data-raw '[ { "name": "Premium Coffee Beans", "description": "High-quality arabica coffee beans from Colombia. Rich flavor with hints of chocolate and caramel. Perfect for espresso or filter coffee.", "price": 24.99, "currency": "USD", "type": "PRODUCT", "external_id": "coffee-premium-001", "file_url": "https://example.com/images/coffee.jpg", "sku": "COFFEE-PREM-001", "metadata": [ { "key": "origin", "value": "Colombia" }, { "key": "roast", "value": "Medium" }, { "key": "weight", "value": "500g" } ] }, { "name": "Delivery Service", "description": "Fast delivery service for orders. Next-day delivery available in selected areas. Professional handling of all packages.", "price": 5.00, "currency": "USD", "type": "SERVICE", "external_id": "service-delivery-001", "metadata": [ { "key": "delivery_time", "value": "1-2 days" }, { "key": "coverage", "value": "Nationwide" } ] } ]' ``` ## Example Response ```json theme={null} { "created": 2, "updated": 0, "products": [ { "id": "prod-uuid-001", "external_id": "coffee-premium-001", "name": "Premium Coffee Beans" }, { "id": "prod-uuid-002", "external_id": "service-delivery-001", "name": "Delivery Service" } ] } ``` ## Product Types | Type | Use For | | --------- | -------------------------------------- | | `PRODUCT` | Physical or digital products | | `SERVICE` | Services, consultations, subscriptions | ## Currency Codes Supported currencies: USD, EUR, GBP, CLP, MXN, COP, ARS, PEN, BRL, and more. ## Create vs Upsert | Feature | Create (This Endpoint) | Upsert | | --------------------- | ------------------------------ | --------------------------- | | **New Products** | ✅ Creates | ✅ Creates | | **Existing Products** | ✅ Updates (by external\_id) | ✅ Updates | | **Other Products** | ✅ Keeps unchanged | ❌ Deletes if not in request | | **Use When** | Adding/updating specific items | Full catalog sync | ## Error Responses | Status Code | Description | | ----------- | ----------------------------------------- | | 400 | Bad Request - Invalid product data | | 401 | Unauthorized - Invalid or missing API key | | 403 | Forbidden - Insufficient permissions | | 404 | Not Found - Product block not found | | 500 | Internal Server Error | ## Related Endpoints * [GET /api/public/product/product-blocks](/reference/product/get-product-blocks) - List available blocks * [POST /api/public/product/upsert/{promptBlockId}](/reference/product/upsert-products) - Full catalog sync * [POST /api/public/product/delete/{promptBlockId}](/reference/product/delete-products) - Delete products ## OpenAPI ````yaml post /api/public/product/create/{promptBlockId} openapi: 3.0.0 info: title: Vambe AI API description: Vambe AI documentation version: '1.0' contact: {} servers: - url: https://api.vambe.me description: Production Server security: [] tags: - name: Vambe AI description: '' paths: /api/public/product/create/{promptBlockId}: post: tags: - Product summary: Create products description: >- Create and update products without deleting existing ones. This endpoint only creates new products and updates existing ones. operationId: PublicProductController_createProducts parameters: - name: promptBlockId required: true in: path description: The prompt block ID to create the products schema: type: string - name: x-api-key in: header description: API key needed to authorize the request required: true schema: type: string requestBody: required: true description: The payload to send with the products content: application/json: schema: $ref: '#/components/schemas/PublicCreateProducts' responses: '201': description: Products created successfully. '400': description: Bad request. '401': description: Unauthorized. '403': description: Forbidden. components: schemas: PublicCreateProducts: type: array minItems: 1 maxItems: 2000 items: type: object properties: name: type: string minLength: 1 file_url: type: string description: description: >- In the description you only need to add words that help the AI do a semantic search, avoide placing here prices, links or other type of data that is not natural language type: string minLength: 1 maxLength: 8192 type: type: string enum: - shopify - vambe - woocommerce - axis - vtex - jumpseller - odoo - tiendanube - magento - custom_app x-enumNames: - Shopify - Vambe - WooCommerce - Axis - Vtex - Jumpseller - Odoo - TiendaNube - Magento - CustomApp currency: type: string enum: - CLP - USD - MXN - BRL - UF - ARS - COP - UYU - PEN - EUR - HNL - BOB - PYG - GTQ - NIO - PAB - CRC - DOP - VES - BZD - SRD - GYD x-enumNames: - CLP - USD - MXN - BRL - UF - ARS - COP - UYU - PEN - EUR - HNL - BOB - PYG - GTQ - NIO - PAB - CRC - DOP - VES - BZD - SRD - GYD price: type: number minimum: 0 exclusiveMinimum: false external_id: type: string sku: type: string metadata: type: array items: type: object properties: key: type: string minLength: 1 value: type: string minLength: 1 required: - key - value required: - name - description - type - currency - price - external_id - metadata ````