Publishing overview

Publishing is how approved product and pricing changes leave MerchantOps and land in the systems that run your storefront. This page explains the model — batches, targets, approval, scheduling, promotion, and status — for merchandisers reviewing changes and developers wiring MerchantOps into their stack. Publishing is a generic connector pattern: MerchantOps holds the approved, versioned records and hands them to a target. Two targets ship with MerchantOps — VTEX and Shopify — and others you build yourself against a pull-based API. The concepts below are the same regardless of the destination.

​

Batches

Changes publish in batches, not one record at a time. A batch groups a set of catalog or pricing records so they can be reviewed together, approved once, and published as a unit. Catalog batches carry product changes (names, descriptions, properties, specifications); price batches carry price records. See Price batches for the pricing workflow. A batch moves through a lifecycle: it starts as a draft you can edit, goes to pending approval for review, becomes approved, and is then published to its target. What you can edit narrows as the batch advances: The target stays editable at pending approval and at approved by design. Approval does not require a target, so a batch can reach approved without one; setting the target then is the way to rescue it rather than rebuilding the batch. The target locks as soon as publishing is attempted — from that point the recorded outcomes are keyed to it, so it can no longer move.

​

Reviewing records inside a batch

A catalog batch can be approved as a whole — the confirmation says plainly that you are approving every product without per-product review — but the point of a batch is usually to look at the products first. Select records in the batch’s product list and choose Review to open the review panel. It takes over the page and walks the selection one product at a time, showing that product’s property values as the publish will send them. The version shown is the one pinned to the record, so you are reading exactly what will be published, not whatever the product looks like right now. Approve or reject each product as you go — there are keyboard shortcuts for stepping through, approving, and rejecting with a reason — and the batch’s counts update as you stamp them. The same selection toolbar can reject the selected records outright, or remove them from the batch entirely. A record can also be rejected or removed from its row’s ⋯ menu without opening the panel. Rejecting asks for a reason, which is required in the dashboard for a single record and for a bulk reject alike. The rejection, with its reason, is logged to the batch’s activity history. Removing a single record asks you to confirm first. Click a record’s row to open that product; Cmd/Ctrl-click opens it in a new tab, as does Open product ↗ in the row’s ⋯ menu. The Publish column shows each record’s publish pill for the batch’s target, including scheduled for a record in an approved batch whose effective date is still ahead.

​

Choosing what reviewers see

Which properties the review panel shows is configuration, not a fixed list. Each product type can have its own set of visible properties, and an organization can set a default that applies to every type without one. If neither is set, the panel falls back to a sensible selection; operational and system properties (vendor identifiers and similar) are hidden by default so reviewers see the content fields first. Edit the list from the review panel’s field-configuration dialog; clearing a type’s own list returns it to the organization default.

​

Publishing targets

A publishing target is a destination for a batch. A target is the combination of: Each destination + environment pair is configured once as an integration under Settings › Publish Targets, and a batch points at one of them.

​

Scheduling by effective date

Every batch carries an effective date. Once a batch is approved and has a target, MerchantOps waits until that date arrives, then publishes the batch automatically — no manual “publish now” step. This lets you approve a price change or catalog update ahead of time and have it go live on schedule. Publishing runs in the background as a job you can track. A batch approved without a target stays active in MerchantOps and is never published — the scheduler skips it.

​

Publishing manually

Waiting for the effective date is the normal path, not the only one.

​

Promotion between environments

When you keep the same destination in more than one environment (say, QA and production), you promote a published batch from one environment to the next rather than rebuilding it by hand. In both cases promotion creates a new draft batch aimed at the destination, requires the source to have published fully, requires the destination to differ from the source’s target and environment, and requires the destination target to be enabled. How the child gets its content differs by batch type. Either way the child is an ordinary draft: give it an effective date, submit it for review, approve it, and let it publish on schedule or with Publish now. Promotion does not cascade a cancellation: cancelling a source batch does not cancel a batch already promoted from it. Each batch in the chain is independent, and the UI shows the relationship so you can decide what to do.

​

Batch activity history

Each catalog batch has an Activity history card listing every step in order: created, submitted, approved, records rejected, publish started, published or partially published, stalled, reset, cancelled, enriched, promoted, and so on. Each entry shows the exact date and time (the relative time is on hover), the member who acted, and, for publishing entries, the target and a link to the job. A publish that started automatically on its effective date is logged too, as scheduled · approved by the batch’s approver. Promotion is linked in both directions: the source batch’s Promoted entry links to the new batch, and the new batch’s Promoted from entry links back. Pricing batches have the same card; see Price batches.

​

Reading publish status

After a batch publishes, MerchantOps records an outcome per target and per environment for every record — so a single record can carry an independent QA result and production result without collision. At the product level, one pill per target tells you where a product is published, whether its live data has drifted from what’s in MerchantOps, whether the last attempt failed, and whether a publish is scheduled. Hover a pill to see who published it, from which batch, and in which job. Once every record has reported, the batch itself rolls up to a final state. A batch whose publish never finishes reporting stays in its publishing state and can be reset so it can be published again. See Reading publish status for the full status model — including the rollup states and how to reset a stuck publish — and get_product_publish_status and get_price_publish_status to query it from an agent.

​

Next steps