VTEX (reference connector)

VTEX is a built-in connector for publishing to a VTEX storefront. It’s one example of the generic publishing target pattern: you approve a batch, choose a VTEX target and environment, and MerchantOps pushes the changes into VTEX for you. Everything on this page is VTEX-specific detail; the batch, approval, scheduling, and status model is the same for any connector. VTEX comes in two targets you configure independently:

• VTEX Catalog (vtex_catalog) — publishes product data.
• VTEX Pricing (vtex_pricing) — publishes prices.

Each is set up under Settings › Publish Targets as an integration pointing at a VTEX store and environment, with that store’s credentials. An organization can have separate QA and production VTEX targets enabled at the same time and promote batches between them.

​

Publishing catalog to VTEX

When a catalog batch publishes to VTEX, MerchantOps reconciles each product and its variants with the store — creating what’s missing and updating what exists:

• Products. Matches the MerchantOps product to a VTEX product by reference. If none exists, it creates the product; otherwise it updates the name, description, and other product-level fields.
• SKUs (variants). Matches each variant to a VTEX SKU by reference, creating or updating as needed, including the SKU’s derived name and dimensions.
• Specifications and attributes. Writes structured specifications (such as color, size, and width) and other named attributes onto the product and its SKUs. Never-before-seen specification values (for example a new color name) are created automatically.

​

SKUs need an image to go live

VTEX won’t activate a SKU until it has at least one image attached. Real product imagery usually arrives later from your own asset workflow, so to keep an approved SKU from being stuck inactive, MerchantOps attaches a placeholder image automatically right after publishing the SKU. This unblocks activation without waiting on your image pipeline.

• If the SKU already has an image, MerchantOps leaves it alone — it never overwrites real imagery with the placeholder.
• You can point the placeholder at your own image per VTEX integration; if you don’t, a default placeholder is used.
• The same step also syncs the variant’s UPC/EAN to VTEX.

This step is best-effort: if it fails, the SKU publish still counts as succeeded and the issue is recorded in the record’s outcome for review, rather than failing the whole publish.

​

Publishing pricing to VTEX

When a price batch publishes to VTEX, MerchantOps resolves each variant to its VTEX SKU and sets that SKU’s price in the store. Prices are applied as the batch’s effective date arrives.

​

Retries and outcomes

Publishing to VTEX runs in the background and retries transient problems automatically — for example VTEX rate limits or temporary server errors are retried before a record is marked failed. Permanent problems (such as a variant that has no matching SKU in the store) are recorded as a failure on that record without retrying. Every record gets an outcome stamped per target and per environment, so a QA publish and a production publish of the same product are tracked separately. See Reading publish status to interpret them.

​

Next steps