Skip to main content
POST
/
api
/
public
/
product
/
create
/
{promptBlockId}
Create products
curl --request POST \
  --url https://api.vambe.me/api/public/product/create/{promptBlockId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
[
  {
    "name": "<string>",
    "description": "<string>",
    "price": 1,
    "external_id": "<string>",
    "metadata": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "file_url": "<string>",
    "sku": "<string>"
  }
]
'

​
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

ParameterTypeRequiredDescription
promptBlockIdstringYesProduct block ID to add products to

​
Request Body

Array of product objects (1-2000 products):
FieldTypeRequiredDescription
namestringYesProduct name
descriptionstringYesNatural language description for AI (max 8192 chars)
pricenumberYesProduct price (must be positive)
currencystringYesCurrency code (USD, EUR, CLP, etc.)
typestringYesProduct type (PRODUCT or SERVICE)
external_idstringYesYour unique identifier for this product
file_urlstringNoURL to product image or file
skustringNoProduct SKU. Falls back to sku key in metadata
metadataarrayYesArray 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

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

{
  "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

TypeUse For
PRODUCTPhysical or digital products
SERVICEServices, consultations, subscriptions

​
Currency Codes

Supported currencies: USD, EUR, GBP, CLP, MXN, COP, ARS, PEN, BRL, and more.

​
Create vs Upsert

FeatureCreate (This Endpoint)Upsert
New Products✅ Creates✅ Creates
Existing Products✅ Updates (by external_id)✅ Updates
Other Products✅ Keeps unchanged❌ Deletes if not in request
Use WhenAdding/updating specific itemsFull catalog sync

​
Error Responses

Status CodeDescription
400Bad Request - Invalid product data
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Product block not found
500Internal Server Error

Headers

​
x-api-key
string
required

API key needed to authorize the request

Path Parameters

​
promptBlockId
string
required

The prompt block ID to create the products

Body

application/json

The payload to send with the products

Required array length: 1 - 2000 elements
​
name
string
required
Minimum string length: 1
​
description
string
required

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

Required string length: 1 - 8192
​
type
enum<string>
required
Available options:
shopify,
vambe,
woocommerce,
axis,
vtex,
jumpseller,
odoo,
tiendanube,
magento,
custom_app
​
currency
enum<string>
required
Available options:
CLP,
USD,
MXN,
BRL,
UF,
ARS,
COP,
UYU,
PEN,
EUR,
HNL,
BOB,
PYG,
GTQ,
NIO,
PAB,
CRC,
DOP,
VES,
BZD,
SRD,
GYD
​
price
number
required
Required range: x > 0
​
external_id
string
required
​
metadata
object[]
required
​
file_url
string
​
sku
string

Response

Products created successfully.