VTEX ERP Integration: SAP, Oracle, NetSuite and custom APIs

Integration between VTEX and ERP is one of the most critical steps in an e-commerce implementation. When done well, the operation flows automatically: orders land in the ERP, invoices are issued, inventory updates in real time and the catalog stays synchronized. When done poorly, it generates manual rework, overselling, price discrepancies and billing delays. This guide covers integration architecture, major ERPs and best practices for a robust integration.

Integration architecture

VTEX exposes documented REST APIs for all system entities: catalog (products, SKUs, categories, brands), pricing (price tables, fixed prices, promotions), inventory (warehouses, inventory levels), orders (orders, feed, hook) and logistics (SLAs, docks, carriers). ERP integration can be done in three ways. Direct: the ERP calls VTEX APIs and vice versa. Via middleware: an intermediary service (Node.js, Python, or iPaaS platform) orchestrates communication between both systems. Via ready connector: solutions like Celigo, MuleSoft and specific connectors that abstract complexity. For large operations, dedicated middleware is the recommended approach as it offers full control over data transformation, failure retry and detailed logging.

Integration with SAP

SAP is the most common ERP in enterprise operations running VTEX. Typical integration covers: catalog (SAP sends materials, VTEX receives as products/SKUs), pricing (SAP sends price tables by commercial condition), inventory (SAP updates availability via inventory API), orders (VTEX sends invoiced orders to SAP for invoice generation) and returns (SAP notifies VTEX about reverse logistics status). The most common connector is via SAP Commerce Cloud Integration or a dedicated Node.js middleware that translates IDocs/BAPIs to REST calls on VTEX. Key concerns: field mapping between SAP and VTEX (material codes vs SKU IDs), handling inventory discrepancy under high concurrency and retry queues for calls that fail due to timeout.

Integration with Oracle and NetSuite

Oracle ERP Cloud and NetSuite are widely used in mid-market and enterprise operations globally. Integration with VTEX follows similar patterns to SAP but with different APIs. Oracle provides REST APIs for catalog, inventory, pricing and orders. NetSuite uses SuiteTalk (SOAP) and REST web services. The typical flow: ERP publishes products via VTEX Catalog API, syncs inventory via Inventory API, receives orders via feed or webhook and returns invoice data. Tools like Celigo and MuleSoft offer ready connectors that reduce implementation time from months to weeks. For operations needing customization beyond the standard connector, a Node.js middleware with Fastify is the most flexible approach.

Integration with lightweight ERPs

Lightweight ERPs focused on e-commerce (like Brightpearl, TradeGecko/QuickBooks Commerce, or Cin7) are popular among small-to-mid operations. Most offer REST APIs and some have native VTEX integrations via the app marketplace. These integrations sync catalog, pricing, inventory and orders through official apps or direct API calls. Setup is simpler: install the app in VTEX admin, configure ERP credentials and map fields. Within days the integration is operational. The concern is volume: for operations with more than 500 orders per day, validate whether the ERP plan supports the necessary throughput without throttling.

Middleware: when and how to build

A middleware integration is recommended when: systems cannot communicate directly (incompatible formats), the operation needs complex data transformation, business rules exist that belong to neither the ERP nor VTEX, or volume requires queues and automatic retry. The recommended stack for VTEX middleware is: Node.js with Fastify for high performance, queues with Redis or SQS for async processing, structured logging with Pino for debugging, health checks and alerts to detect failures quickly. The middleware must be idempotent: processing the same message twice must not generate duplicates. Use correlation IDs to trace an order from start to finish. Monitor latency and error rate. A healthy middleware processes messages in under 2 seconds with an error rate below 0.1%.

Catalog and pricing synchronization

Catalog synchronization is the foundation of every integration. The ERP is the master of product data: name, description, attributes, weight, dimensions. VTEX is the presentation system: images, SEO, visual categories. The typical flow: ERP sends product via VTEX Catalog API (POST /api/catalog/pvt/product), then sends SKUs (POST /api/catalog/pvt/stockkeepingunit), then prices (PUT /api/pricing/prices/sku-id), then inventory (PUT /api/logistics/pvt/inventory/skus/sku-id/warehouses/warehouse-id). Synchronization can be polling-based (periodic) or event-driven (ERP webhook). For catalog, polling every 15-30 minutes is acceptable. For inventory in high-volume operations, event-driven or 1-2 minute polling is necessary to prevent overselling.

Order flow and invoicing

The integrated order flow follows: customer buys on VTEX, order enters OMS with payment-approved status, VTEX notifies ERP via feed or webhook, ERP processes the order (reserves inventory, generates invoice), ERP returns invoice to VTEX via invoice API (POST /api/oms/pvt/orders/order-id/invoice), VTEX updates status to invoiced and sends confirmation email to customer. To capture orders, use VTEX Order Feed or Order Hook. Feed is pull-based (you query periodically), Hook is push-based (VTEX sends to your endpoint). Hook is more efficient but requires an always-available endpoint. In both cases, process orders asynchronously with queues to avoid losing events during traffic peaks.

Best practices and common mistakes

Always use authentication via VTEX appKey and appToken. Never expose credentials in the frontend. Implement retry with exponential backoff for calls that fail due to timeout or rate limit. VTEX has rate limits per endpoint; respect X-RateLimit headers. Validate data before sending: products without images, SKUs without prices or negative inventory cause silent errors. Monitor the integration queue: orders stuck for more than 30 minutes indicate a problem. Create alerts for inventory discrepancy between ERP and VTEX. Document field mapping between systems. Test integration in staging before production. And most importantly: plan for failure. Systems go down, APIs get slow, data arrives incomplete. A robust integration handles all these scenarios without manual intervention.