> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vantr.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalog workflows

> Create products, categories, and vendors with realistic v2 API examples.

# Catalog workflows

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

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

## Before you write data

<Steps titleSize="h3">
  <Step title="List capabilities" icon="waypoints">
    Confirm which resources and actions your application can use.

    ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -u "$CLIENT_ID:$CLIENT_SECRET" \
      "https://api.vantr.ai/v2/capabilities"
    ```
  </Step>

  <Step title="Pick scopes" icon="list-checks">
    Add write scopes only for the resources your workflow changes: `products.write`, `categories.write`, or `vendors.write`.
  </Step>

  <Step title="Create supporting records first" icon="folder-tree">
    Create or look up categories and vendors before creating products that reference them.
  </Step>
</Steps>

## Create a product

This example creates a product with one sellable variation.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
        }
      ]
    }'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

```json Response theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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

<ParamField body="name" type="string" required>
  Product name shown to operators and integrations.
</ParamField>

<ParamField body="variations" type="object[]" required>
  One or more variations. Each variation can carry pricing, unit, SKU, barcode, tax, and eligibility fields.
</ParamField>

<ParamField body="square_sync_enabled" type="boolean" default="true">
  Whether the product should participate in catalog sync behavior.
</ParamField>

<ParamField body="allergens" type="string[]">
  Supported values include `gluten`, `dairy`, `nut`, `soy`, `shellfish`, `egg`, `wheat`, `fish`, and `sesame`.
</ParamField>

## Create a category

Use categories to organize products and build category trees.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

<Columns cols={3}>
  <Card title="Get product" icon="package-search" href="/api-reference/products/get-product">
    Verify product fields and generated variation IDs.
  </Card>

  <Card title="Category tree" icon="folder-tree" href="/api-reference/categories/get-category-tree">
    Confirm category hierarchy.
  </Card>

  <Card title="Get vendor" icon="building-2" href="/api-reference/vendors/get-vendor">
    Confirm vendor profile fields.
  </Card>
</Columns>