VTEX WooCommerce Integration Setup

Documentation for

What this plugin does

VTEX Orders Sync for WooCommerce connects one VTEX account to WooCommerce through the VTEX OMS, Catalog and Logistics APIs. It imports orders every 15 minutes, can start handling on import, posts invoices with tracking when you fulfil, cancels on VTEX, and pushes stock to a warehouse every hour.

Jobs run on Action Scheduler (WP-Cron as a fallback) once Enable syncing is ticked.

Requirements

WordPress 5.8 or later and PHP 7.4 or later
WooCommerce 7.0 or later, HPOS or legacy order storage
A VTEX account and an Application Key with OMS (orders) and, for stock, Logistics (inventory) roles
WooCommerce SKUs that match your VTEX RefIds

Installation

Upload the zip at Plugins → Add New → Upload Plugin and activate it with WooCommerce active.
Open WooCommerce → VTEX Sync. Tabs: Settings, Sync log, Status.

Connecting your VTEX account

In VTEX Admin go to Account Settings → Account → Security → Application Keys and generate a key.
Give the key roles that allow reading orders (OMS) and, if you want stock sync, managing inventory (Logistics).
In the plugin enter your account name (the part before .vtexcommercestable.com.br), leave Environment as vtexcommercestable unless VTEX told you otherwise, and paste the App Key and App Token.
Optionally enter a Sales channel to import only that channel’s orders.
Save, press Test connection, then tick Enable syncing.

VTEX Orders Sync settings with account name, environment, App Key, App Token and sales channel fields — WooCommerce → VTEX Sync: account name, environment, App Key, App Token and optional sales channel.

Settings reference

Setting	What it does
Account name	Your VTEX account, e.g. `mystore`.
Environment	Normally `vtexcommercestable`.
App Key / App Token	Application key credentials. Stored encrypted.
Sales channel (optional)	Import only orders from this sales channel ID.
Enable syncing	Master switch for scheduled jobs.
Import	Import VTEX orders every 15 minutes, and optionally start handling on VTEX as soon as an order is imported.
Import orders with status	Which VTEX orders to import — usually ready-for-handling.
Status for imported orders	WooCommerce status for new orders, usually Processing.
Invoice on VTEX when status becomes	When the order reaches this status (usually Completed), an Output invoice with courier and tracking is posted.
Cancel on VTEX when status becomes	Cancelling in WooCommerce with this status, before invoicing, cancels on VTEX.
Look back (days)	How far back each import looks, up to 30 days.
Stock sync	Push stock to VTEX every hour, SKU matched to the VTEX RefId.
Warehouse ID	The VTEX warehouse that receives quantities.

Buttons on the settings screen

Button	What it does
Test connection	Calls the OMS API with your key and token and logs the result.
Sync orders now	Imports immediately.
Push stock now	Sends stock immediately.
Clear cached SKU map	Forgets RefId → SKU ID lookups. Use after adding products in VTEX.

How orders are imported

Every 15 minutes the plugin lists VTEX orders with your chosen status within the look-back window and fetches each one. It becomes a WooCommerce order with customer and shipping data, items, shipping charges, discounts and tax — every VTEX amount converted from cents — and the VTEX order ID, sequence and status recorded.

Items are matched by SKU against the VTEX RefId; unmatched items become placeholders with a warning note. Three-letter country codes are converted to two-letter codes, and the map can be extended with rau_vos_country_map. Imports are keyed on the VTEX order ID.

With start handling on, each imported order is moved to handling on VTEX immediately and the time is recorded on the order.

Invoicing, tracking and cancelling

The VTEX panel on the order screen shows the VTEX order ID, sequence, status and whether handling has started and the order has been invoiced. Enter the courier, tracking number and tracking URL there and save.

When the order reaches Invoice on VTEX when status becomes, the plugin posts an Output invoice — invoice number, value, courier and tracking — which moves the order on VTEX. Adjust it with rau_vos_invoice_payload if you need your own invoice numbering. Use Update tracking to change tracking on an invoice that already exists.

Cancelling in WooCommerce with the mapped status, before invoicing, cancels the order on VTEX.

WooCommerce order with the VTEX panel showing order ID, sequence, invoiced status, Correios courier and tracking number — A VTEX order in WooCommerce. The panel shows the VTEX order ID, sequence and status, when handling started and that it was invoiced, with courier, tracking number, tracking URL and an Update tracking button.

Stock sync

VTEX inventory is addressed by SKU ID, so the plugin looks each WooCommerce SKU up by RefId in the catalogue and caches the result. SKUs with no match are remembered as misses and skipped — press Clear cached SKU map after adding products. Quantities go to the warehouse you set; hold back a buffer with rau_vos_stock_buffer.

The sync log and Status tab

The Sync log records imports, handling, invoices, tracking updates, cancellations, stock pushes and errors with raw API detail, linked to orders and kept for seven days.

The Status tab shows connection and syncing state, API base, warehouse, last and next sync, last stock push, orders this month, errors in the last 24 hours and the scheduler.

VTEX Orders Sync log with imports, start handling, invoice and stock sync entries — Two VTEX orders imported, one moved to handling, one invoiced with Correios tracking, and an hourly stock push.

What the free version includes

Up to 100 imported orders per month
One VTEX account
15-minute order sync and hourly stock sync
30-day order look-back
7-day log retention
One warehouse for stock sync

Troubleshooting

What you see	What to do
401 or 403 on Test connection	Wrong App Key/Token pair, or the key lacks the OMS role. Stock sync additionally needs a Logistics role.
Totals 100× too high	This plugin converts cents; if you see it, another integration is also writing to the order. Check the log for which one.
Invoice rejected	The order must be in handling first. Enable start handling on import, or move it in VTEX.
Stock sync skips SKUs	The WooCommerce SKU doesn’t match any VTEX RefId, or the map is stale — Clear cached SKU map.
Wrong country on addresses	Add the three-letter code to the map with the rau_vos_country_map filter.

For developers: hooks

Every hook below is part of the plugin’s public surface and safe to use from a theme’s functions.php or a small site plugin.

Hook	Type	Use it to
`rau_vos_order_imported`	action	Run code after a VTEX order is created. Receives the WC_Order and the VTEX order.
`rau_vos_invoice_payload`	filter	Change the invoice posted to VTEX. Receives the invoice array and the WC_Order.
`rau_vos_country_map`	filter	Extend the three-letter → two-letter country map.
`rau_vos_stock_buffer`	filter	Hold back a safety quantity per product.
`rau_vos_unmanaged_stock_value`	filter	Quantity for products that don’t manage stock.
`rau_vos_stock_rows`	filter	Adjust rows before stock is pushed.
`rau_vos_loaded`	action	Fires once the plugin has booted.

// Use your own invoice numbering on VTEX.
add_filter( 'rau_vos_invoice_payload', function ( $invoice, $order ) {
	$invoice['invoiceNumber'] = 'NF-' . $order->get_order_number();
	return $invoice;
}, 10, 2 );

Uninstalling

Deleting the plugin removes its settings, SKU map, counters and log table. Imported orders remain in WooCommerce.

Questions people ask

Does it work for VTEX marketplace sellers?

Yes — any VTEX account whose Application Key can read the orders you fulfil.

VTEX Orders Sync for WooCommerce — Documentation