VTEX Integration

Connect your VTEX store with ZenFlow to automatically import orders, sync inventory, and streamline your fulfillment operations at enterprise scale.

This integration supports VTEX Commerce in any country. Compatible with VTEX’s OMS (Order Management System).

Features

Import Orders

Import orders in “ready-for-handling” status

Real-time Feed

Receive status changes via Feed or Webhooks

Inventory Sync

Stock synchronization by warehouse to VTEX

Multi-warehouse

Support for multiple VTEX warehouses

Setup Guide

Step 1: Get API Credentials in VTEX

In your VTEX admin, go to Account settings > Application keys
Click Generate new key
Assign the following permissions:
- OMS - Full access
- Logistics - Full access
Copy the App Key and App Token

The App Token is only shown once. Store it securely.

Step 2: Connect in ZenFlow

Go to Settings > Integrations in ZenFlow
Click Connect VTEX
Enter:
- Account Name: Your VTEX account name (e.g., mystore)
- App Key: The application key
- App Token: The application token
Click Connect

Step 3: Select VTEX Warehouse

After connecting, select the VTEX warehouse you want to sync:

Go to Integrations > VTEX > Settings
Select the VTEX warehouse from the list
Enable order and/or inventory synchronization

Step 4: Configure Notifications (Optional)

Choose how to receive new order notifications:

Feed (Recommended)

ZenFlow polls VTEX every 30 seconds. More reliable.

Webhooks

VTEX notifies ZenFlow in real-time. Faster but may miss events.

Order Flow

API Reference

Connect Account

POST /api/v1/integrations/vtex/connect

Request:

{
  "account_name": "mystore",
  "app_key": "vtexappkey-mystore-XXXXXX",
  "app_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "environment": "vtexcommercestable"
}

Response:

{
  "success": true,
  "data": {
    "id": "cred_abc123",
    "account_name": "mystore",
    "status": "active",
    "connected_at": "2024-01-15T10:30:00Z"
  }
}

Get Connection Status

GET /api/v1/integrations/vtex/status

Response:

{
  "success": true,
  "data": {
    "connected": true,
    "account_name": "mystore",
    "status": "active",
    "vtex_warehouse_id": "warehouse_1",
    "feed_configured": true,
    "hook_configured": false,
    "sync_orders": true,
    "sync_stock": true,
    "last_sync_at": "2024-01-20T15:45:00Z"
  }
}

Update Configuration

PUT /api/v1/integrations/vtex/config

Request:

{
  "sync_orders": true,
  "sync_stock": true
}

List VTEX Warehouses

GET /api/v1/integrations/vtex/warehouses

Response:

{
  "success": true,
  "data": {
    "warehouses": [
      {
        "id": "warehouse_1",
        "name": "Main Warehouse",
        "is_active": true
      },
      {
        "id": "warehouse_2",
        "name": "North Branch",
        "is_active": true
      }
    ]
  }
}

Set Warehouse

POST /api/v1/integrations/vtex/warehouses/set

Request:

{
  "vtex_warehouse_id": "warehouse_1"
}

Configure Feed

POST /api/v1/integrations/vtex/feed/configure

Configures the polling feed to receive order changes.

Configure Webhooks

POST /api/v1/integrations/vtex/hook/configure

Registers webhooks in VTEX for real-time notifications.

Manually Sync Orders

POST /api/v1/integrations/vtex/sync/orders

Request:

{
  "date_from": "2024-01-01",
  "date_to": "2024-01-31"
}

Sync Stock to VTEX

POST /api/v1/integrations/vtex/sync/stock

List Product Mappings

GET /api/v1/integrations/vtex/mappings

Response:

{
  "success": true,
  "data": {
    "mappings": [
      {
        "id": "map_abc123",
        "product_id": 100,
        "product_sku": "PROD-001",
        "vtex_sku_id": "123456",
        "vtex_product_id": "789",
        "sync_stock": true,
        "last_stock_sync": "2024-01-20T15:45:00Z"
      }
    ]
  }
}

Create Product Mapping

POST /api/v1/integrations/vtex/mappings

Request:

{
  "product_id": 100,
  "vtex_sku_id": "123456",
  "vtex_product_id": "789",
  "sync_stock": true
}

Delete Mapping

DELETE /api/v1/integrations/vtex/mappings/:id

Disconnect Account

POST /api/v1/integrations/vtex/disconnect

Order Notifications

Feed (Polling)

Feed is the recommended method for receiving notifications:

ZenFlow polls VTEX every 30 seconds
Processes status changes in batch
Confirms processed items to avoid duplicates
More reliable than webhooks (doesn’t miss events)

Webhooks

Webhooks provide real-time notifications:

Event	Description	ZenFlow Action
Status changes to `ready-for-handling`	Order ready	Imports and starts handling
Status changes to `handling`	In preparation	Updates status
Status changes to `invoiced`	Shipped	Marks as completed
Status changes to `canceled`	Cancelled	Cancels order

Product Mapping

Automatic Matching

When an order is imported, ZenFlow attempts to match products automatically:

Looks for existing mapping by vtex_sku_id
If not found, searches by SKU or barcode in ZenFlow
If found, creates the mapping automatically

Manual Mapping

For products that don’t auto-match:

Go to Integrations > VTEX > Product Mapping
Filter by “Unmapped”
Select the corresponding ZenFlow product

Status Mapping

VTEX Status	ZenFlow Status
`order-created`	Pending
`payment-approved`	Ready to pick
`ready-for-handling`	Ready to pick
`start-handling`	In progress
`handling`	In progress
`invoice`	Ready for dispatch
`invoiced`	Shipped
`canceled`	Cancelled

Inventory Synchronization

Stock synchronization works as follows:

ZenFlow calculates available stock (total - reserved)
Updates inventory in VTEX for the configured warehouse
Only syncs products with active mapping and sync_stock: true

// Update example
PUT /api/logistics/pvt/inventory/skus/{sku}/warehouses/{warehouse}
{
  "quantity": 50,
  "unlimitedQuantity": false
}

Troubleshooting

Cannot Connect

Check credentials

Make sure the App Key and App Token are correct. Generate new credentials if needed.

Check permissions

Credentials need full access to OMS and Logistics. Verify permissions in VTEX Admin.

Check account name

The account_name must be exactly your VTEX account name (without “.vtexcommercestable.com.br”).

Orders Not Importing

Check order status

Only orders in “ready-for-handling” status are imported. Check the order flow in VTEX.

Check configured warehouse

Make sure you’ve selected the correct VTEX warehouse in the configuration.

Check feed or webhooks

Verify that feed is configured (recommended) or that webhooks are active.

Stock Not Syncing

Check product mapping

The product must be mapped and have sync_stock enabled.

Check VTEX warehouse

The VTEX warehouse must be configured in the integration.

Check Logistics permissions

Credentials need Logistics permissions to update inventory.

Rate Limits

Operation	Limit
API calls	100 requests/second
Maximum per minute	6000 requests

ZenFlow handles rate limits automatically with wait and retry logic.

Requirements

Active VTEX account
App Key and App Token with permissions:
- OMS - Full access
- Logistics - Full access
At least one warehouse configured in VTEX

Support

VTEX APIs Documentation
VTEX Help Center
Contact [email protected] for integration help

​VTEX Integration

​Features

Import Orders

Real-time Feed

Inventory Sync

Multi-warehouse

​Setup Guide

​Step 1: Get API Credentials in VTEX

​Step 2: Connect in ZenFlow

​Step 3: Select VTEX Warehouse

​Step 4: Configure Notifications (Optional)

Feed (Recommended)

Webhooks

​Order Flow

​API Reference

​Connect Account

​Get Connection Status

​Update Configuration

​List VTEX Warehouses

​Set Warehouse

​Configure Feed

​Configure Webhooks

​Manually Sync Orders

​Sync Stock to VTEX

​List Product Mappings

​Create Product Mapping

​Delete Mapping

​Disconnect Account

​Order Notifications

​Feed (Polling)

​Webhooks

​Product Mapping

​Automatic Matching

​Manual Mapping

​Status Mapping

​Inventory Synchronization

​Troubleshooting

​Cannot Connect

​Orders Not Importing

​Stock Not Syncing

​Rate Limits

​Requirements

​Support

VTEX Integration

Features

Setup Guide

Step 1: Get API Credentials in VTEX

Step 2: Connect in ZenFlow

Step 3: Select VTEX Warehouse

Step 4: Configure Notifications (Optional)

Order Flow

API Reference

Connect Account

Get Connection Status

Update Configuration

List VTEX Warehouses

Set Warehouse

Configure Feed

Configure Webhooks

Manually Sync Orders

Sync Stock to VTEX

List Product Mappings

Create Product Mapping

Delete Mapping

Disconnect Account

Order Notifications

Feed (Polling)

Webhooks

Product Mapping

Automatic Matching

Manual Mapping

Status Mapping

Inventory Synchronization

Troubleshooting

Cannot Connect

Orders Not Importing

Stock Not Syncing

Rate Limits

Requirements

Support