Catalog workflows

Use catalog endpoints to keep products, variations, categories, and vendor profiles aligned with your system of record.

Product creation requires at least one variation. Category and vendor create endpoints accept the fields shown in the API reference.

Before you write data

List capabilities

Confirm which resources and actions your application can use.

cURL

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  "https://api.vantr.ai/v2/capabilities"

Pick scopes

Add write scopes only for the resources your workflow changes: products.write, categories.write, or vendors.write.

Create supporting records first

Create or look up categories and vendors before creating products that reference them.

Create a product

This example creates a product with one sellable variation.

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -X POST "https://api.vantr.ai/v2/products" \
  -d '{
    "name": "Blue Corn Tortilla Chips",
    "description": "12 oz bag",
    "category_id": "4fb0f601-2f67-47b8-9d87-c9a9fbb94984",
    "tags": ["grocery", "snacks"],
    "square_sync_enabled": true,
    "variations": [
      {
        "name": "12 oz",
        "price": 4.49,
        "unit": "EA",
        "sku": "BCTC-12OZ",
        "barcode": "860123456789",
        "ebt_eligible": true,
        "organic_certified": true,
        "allergens": ["wheat"],
        "tax_code": "grocery"
      }
    ]
  }'

const credentials = Buffer
  .from(`${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`)
  .toString('base64');

const response = await fetch('https://api.vantr.ai/v2/products', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Blue Corn Tortilla Chips',
    description: '12 oz bag',
    category_id: '4fb0f601-2f67-47b8-9d87-c9a9fbb94984',
    tags: ['grocery', 'snacks'],
    square_sync_enabled: true,
    variations: [
      {
        name: '12 oz',
        price: 4.49,
        unit: 'EA',
        sku: 'BCTC-12OZ',
        barcode: '860123456789',
        ebt_eligible: true,
        organic_certified: true,
        allergens: ['wheat'],
        tax_code: 'grocery',
      },
    ],
  }),
});

if (!response.ok) {
  throw new Error(`Product create failed: ${response.status}`);
}

const data = await response.json();

Response

{
  "success": true,
  "product": {
    "id": "0ad6f113-904e-4505-bf7b-2f3c0d122f2c",
    "name": "Blue Corn Tortilla Chips",
    "description": "12 oz bag",
    "category_id": "4fb0f601-2f67-47b8-9d87-c9a9fbb94984",
    "tags": ["grocery", "snacks"],
    "is_archived": false,
    "square_sync_enabled": true,
    "created_at": "2026-06-01T18:25:00.000Z",
    "updated_at": "2026-06-01T18:25:00.000Z",
    "variations": [
      {
        "id": "e90bb535-b42d-42f2-8874-7f4d336a75b5",
        "product_id": "0ad6f113-904e-4505-bf7b-2f3c0d122f2c",
        "name": "12 oz",
        "price": 4.49,
        "unit": "EA",
        "sku": "BCTC-12OZ",
        "barcode": "860123456789",
        "ebt_eligible": true,
        "wic_eligible": false,
        "organic_certified": true,
        "kosher_certified": false,
        "tobacco": false,
        "alcohol_class": null,
        "controlled_class": null,
        "allergens": ["wheat"],
        "tax_code": "grocery",
        "tags": [],
        "is_archived": false,
        "square_sync_enabled": true
      }
    ]
  }
}

Product fields to plan for

string

required

Product name shown to operators and integrations.

object[]

required

One or more variations. Each variation can carry pricing, unit, SKU, barcode, tax, and eligibility fields.

boolean

default:"true"

Whether the product should participate in catalog sync behavior.

string[]

Supported values include gluten, dairy, nut, soy, shellfish, egg, wheat, fish, and sesame.

Create a category

Use categories to organize products and build category trees.

cURL

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -X POST "https://api.vantr.ai/v2/categories" \
  -d '{
    "name": "Snacks",
    "parent_category_id": null
  }'

Create a vendor

Vendor profiles support purchasing and catalog workflows that need supplier context.

cURL

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -X POST "https://api.vantr.ai/v2/vendors" \
  -d '{
    "vendor_name": "Desert Pantry Co.",
    "vendor_aliases": ["Desert Pantry"],
    "contact_info": "orders@desertpantry.example",
    "country": "US",
    "state": "AZ",
    "payment_terms": "Net 15",
    "currency": "USD",
    "is_active": true
  }'

Read after write

After creating or updating records, read them back before marking your sync job complete.

Get product

Verify product fields and generated variation IDs.

Category tree

Confirm category hierarchy.

Get vendor

Confirm vendor profile fields.

Start

Build

Operate

Catalog workflows

Catalog workflows

Before you write data

List capabilities

Pick scopes

Create supporting records first

Create a product

Product fields to plan for

Create a category

Create a vendor

Read after write

Get product

Category tree

Get vendor

​Catalog workflows

​Before you write data

List capabilities

Pick scopes

Create supporting records first

​Create a product

​Product fields to plan for

​Create a category

​Create a vendor

​Read after write

Get product

Category tree

Get vendor

Catalog workflows

Before you write data

Create a product

Product fields to plan for

Create a category

Create a vendor

Read after write