> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchantops.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# VTEX (reference connector)

> How MerchantOps publishes catalog and pricing to VTEX — one example of a publishing connector.

VTEX is a **built-in connector** for publishing to a
[VTEX](https://vtex.com) storefront. It's one example of the generic
[publishing target](/publishing/overview) 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](/publishing/overview) 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.

<Note>
  MerchantOps does **not** auto-create brands or categories in VTEX, or define new
  specification **fields**. If a product's brand or category doesn't exist in the
  store yet, publishing surfaces a warning instead of guessing — add it in VTEX
  and the next publish picks it up. See [publish status](/publishing/publish-status)
  for how these warnings appear.
</Note>

### 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](/publishing/overview) arrives.

<Note>
  MerchantOps currently publishes fixed, effective-now prices to VTEX — the price
  is set when the batch publishes. Future-dated price windows within VTEX itself
  aren't used yet.
</Note>

## 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](/publishing/publish-status) to interpret them.

## Next steps

<CardGroup cols={2}>
  <Card title="Publishing overview" icon="rocket" href="/publishing/overview">
    Batches, targets, approval, scheduling, and promotion.
  </Card>

  <Card title="Build your own connector" icon="plug" href="/publishing/connectors">
    Publish to a system MerchantOps doesn't support out of the box.
  </Card>
</CardGroup>