Skip to main content

​
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

  1. In your VTEX admin, go to Account settings > Application keys
  2. Click Generate new key
  3. Assign the following permissions:
    • OMS - Full access
    • Logistics - Full access
  4. Copy the App Key and App Token
The App Token is only shown once. Store it securely.

​
Step 2: Connect in ZenFlow

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

​
Step 3: Select VTEX Warehouse

After connecting, select the VTEX warehouse you want to sync:
  1. Go to Integrations > VTEX > Settings
  2. Select the VTEX warehouse from the list
  3. 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:
EventDescriptionZenFlow Action
Status changes to ready-for-handlingOrder readyImports and starts handling
Status changes to handlingIn preparationUpdates status
Status changes to invoicedShippedMarks as completed
Status changes to canceledCancelledCancels order

​
Product Mapping

​
Automatic Matching

When an order is imported, ZenFlow attempts to match products automatically:
  1. Looks for existing mapping by vtex_sku_id
  2. If not found, searches by SKU or barcode in ZenFlow
  3. If found, creates the mapping automatically

​
Manual Mapping

For products that don’t auto-match:
  1. Go to Integrations > VTEX > Product Mapping
  2. Filter by “Unmapped”
  3. Select the corresponding ZenFlow product

​
Status Mapping

VTEX StatusZenFlow Status
order-createdPending
payment-approvedReady to pick
ready-for-handlingReady to pick
start-handlingIn progress
handlingIn progress
invoiceReady for dispatch
invoicedShipped
canceledCancelled

​
Inventory Synchronization

Stock synchronization works as follows:
  1. ZenFlow calculates available stock (total - reserved)
  2. Updates inventory in VTEX for the configured warehouse
  3. 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

Make sure the App Key and App Token are correct. Generate new credentials if needed.
Credentials need full access to OMS and Logistics. Verify permissions in VTEX Admin.
The account_name must be exactly your VTEX account name (without “.vtexcommercestable.com.br”).

​
Orders Not Importing

Only orders in “ready-for-handling” status are imported. Check the order flow in VTEX.
Make sure you’ve selected the correct VTEX warehouse in the configuration.
Verify that feed is configured (recommended) or that webhooks are active.

​
Stock Not Syncing

The product must be mapped and have sync_stock enabled.
The VTEX warehouse must be configured in the integration.
Credentials need Logistics permissions to update inventory.

​
Rate Limits

OperationLimit
API calls100 requests/second
Maximum per minute6000 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