Skip to main content
Long-running and batch operations in MerchantOps run as jobs. A job groups many items into one tracked operation so you can watch it finish, see how much succeeded, and catch what failed — without refreshing individual products. This page explains what a job records, what each status means, and what you can do to a job that needs attention. For the shared vocabulary, see Core concepts.

​
What a job tracks

Imports, enrichment runs, document ingestion, publishing, and exports all run as jobs. Each job records its type and its progress as it works through its items:
​
one of eleven types
What the job is doing. Every type is filterable on the Jobs page: Enrichment, Crawl, Ingestion (document extraction), Import, Connector Sync (a catalog import from a connected store — see Shopify), Price Import, Price Publish, Catalog Publish, Oracle Sync (a scheduled inbound feed), Export, and Bulk Delete.
​
count
How many items the job set out to process.
​
count
How many items have finished so far.
​
count
How many items couldn’t be completed.
​
count
How many items finished with a warning rather than cleanly — for example, an enrichment run that found no new data to add, or one the AI provider refused part-way through (see Provider errors).
​
count
How many items were stopped by a cancellation before they were attempted. These are not folded into processed — a cancelled item was never tried, so counting it as processed would report a run that published nothing as fully processed. A cancelled job’s counts therefore read as a gap plus an explicit cancelled count, for example 574 / 593 with 19 cancelled.
​
count
How many items still need a review to be finished with. While this is above zero the job cannot finish — see Awaiting review below. An item you have already approved stays in this count until its result is written, so a count above zero does not always mean something is waiting on you; the job’s review panel says which of the two it is.
​
percentage
How far along the job is, computed from processed against total.
​
text
What the job is working on: the file names for an ingestion or import, the batch name for a publish, or the product keys for an enrichment run. Shown in the Job Log’s Description column and matched by search (see Monitoring jobs). Jobs created before this field existed may not have one.

​
Job statuses

A job’s final status is derived from those counters, so the status tells you exactly what happened without opening the job.
completed means zero failures and zero warnings — always. A job with failed items never lands on completed. If some items succeeded and some failed, the status is partial_success (“Completed with Errors”); if nothing succeeded at all, it’s failed. So after a run with failures, partial_success is the status to look for — it is the normal outcome, not an anomaly.

​
Publish job status comes from its own counters

A catalog publish job and the batch it publishes carry two separate indicators, and they are allowed to disagree. The batch badge is decided by a success ratio — 95% of its records, so anything short of that reads Partial. The job’s status is decided by the job’s own counters, the same ladder as every other job type: some items done and some failed is partial_success (“Completed with Errors”), and only a run where nothing was processed is failed.
A catalog publish that mostly succeeded used to report Failed on the Jobs page: the batch’s Partial verdict was written straight onto the job, overriding its counters. A run that published 558 of 596 records — 94% — showed as a total loss. That no longer happens: such a run reports Completed with Errors, with the failed count telling you how much to re-drive, and only a run where nothing published at all reports Failed.
The batch verdict is still recorded on the job as its error message (“Catalog batch publish ended as partial”). Read it as a diagnostic about the batch, not as the job’s verdict — an error message on a Completed with Errors job is expected, not a contradiction.

​
Awaiting review

awaiting_review is the one non-terminal end state: the run did all the work it could, but some items need a human decision before the job can settle. The Jobs page shows it in purple, labelled Awaiting review; hovering explains that the job is paused on a person and nothing advances until it’s resolved. Once the reviews are cleared the job resumes its normal status ladder — nothing is lost in the meantime. Two things park a job here, and they’re resolved in different places:
  • Document ingestion. An uploaded product PDF whose extraction didn’t clear the confidence bar pauses for review. Resolve it on the document’s extraction review page — opening the job takes you there. This is the common case: the default ingestion setting parks a great many product PDFs this way.
  • Enrichment escalations. When escalation is enabled for your organization, an enrichment run that isn’t confident enough to apply a match raises it for review instead of guessing. These are resolved in the Agent Inbox.
Open the job to see which of the two is waiting; the job links you to the right screen. Approving an extraction review is not quite the end of the job. The approved products are written to the lakehouse afterwards, and the job stays open until that finishes — so a job can have a review count above zero with nothing left for you to do. The job’s review panel tells the two apart: a document still waiting on you keeps its Review extraction call to action, while an approved one is listed as Approved … — committing with a read-only View review link. When every document in the job has been approved, the badge reads Review approved — committing instead of Paused. See After you approve.
Agent Inbox appears in the sidebar with a pending-review count. It is the destination for enrichment escalations only — an escalation is a match the enrichment pipeline was not confident enough to apply, raised for a person rather than guessed at. Escalations are not produced unless escalation is switched on for your organization, so for most organizations the Agent Inbox stays empty. Documents parked for extraction review are not routed here: they are resolved on the document’s own review page.
Two different statuses render on the same yellow badge: completed_with_warnings (“Warnings”) and partial_success (“Completed with Errors”). They mean very different things — the second has item failures counted against the job, while the first generally does not. Read the label and the counts, not the color — and on a Warnings job, check the Retry Unfinished count too, because a provider error leaves items to re-run without moving the failed count.

​
Provider errors during enrichment

Enrichment calls an AI provider to write content and standardize values. Occasionally the provider refuses a call outright — a plan or budget limit reached, an authorization rejection, or a request the provider declines to serve. That is not a problem with your product: nothing about the record is wrong, the call simply never happened. A refused call used to disappear quietly. The affected fields were left empty, the run still reported itself finished, and the job could land on Completed, green and warning-free, while some products were quietly missing generated content. That no longer happens:
  • The run keeps whatever it did get. Data already gathered from the lakehouse, the brand site, and calls that did succeed is still saved.
  • The job records a warning naming the refusal, so it finishes as Warnings instead of a clean Completed.
  • The affected item is marked as not finished, which makes it eligible for Retry Unfinished on that same job.
A provider refusal bumps the job’s warned count, not its failed count — the run did complete and persist what it had. So the job settles on completed_with_warnings (“Warnings”), and has items waiting to be retried. This is the one case where a Warnings job is not simply “finished, nothing lost”: open it and check the Retry Unfinished count.
Provider refusals are usually transient. Retrying the job a little later is normally all that’s needed. If a retry immediately produces the same warning, the provider is still refusing — wait for it to clear rather than retrying in a loop, since each attempt re-runs the same calls.

​
Monitoring jobs

Track jobs on the Jobs page, which shows each job’s type, status, counts, and progress percentage in real time. Filter by status, by any of the eleven job types, or by date. Search (two characters or more) matches a job’s ID, file names, batch name, product keys, site URL, or shop domain, and runs across all pages — not just the ones currently loaded. You can also read a job’s progress through the API when you’re wiring MerchantOps into your own systems.
Integrating against GET /api/jobs? The list response is a summary: each item carries description but not the per-item metadata logs (published prices, errors, import URLs, connector-sync detail). Fetch the single job (GET /api/jobs/{job_id}) for those. The search query parameter applies the same match described above.
1

Start a batch operation

Import or export a set of products, upload a document, publish a batch, or let enrichment run — each creates a job.
2

Watch progress

The job’s progress percentage climbs as its processed count rises toward total.
3

Resolve anything paused

If the job shows Awaiting review, open it and clear the review. It won’t finish on its own.
4

Review the outcome

Check the final status and the failed count. Completed with Errors means some items need a second look.
A job that finishes as Warnings did finish — for enrichment it usually means the product already had everything, or no trustworthy source produced anything new, and nothing was lost. The exception is a provider error, which leaves items to re-run. Check the Retry Unfinished count before you close the job out.

​
Acting on a job

An Export job that finished successfully shows a Download button on its detail page, for any export kind — including the per-product exports started through the MCP server. An export that produced no rows shows a message instead of a failing download. Open a job to act on it:
  • Retry Unfinished — re-queues only the items that never finished, on the same job, so you keep watching one job from start to finish instead of chasing a second one. The button shows how many items it would re-queue. If nothing is left to retry, every remaining failure is terminal (for example a product key that doesn’t resolve) and would just fail again. Enrichment items degraded by a provider error are not terminal — this is how you re-run exactly those, and only those. Re-queued items are fresh enrichment work, so a retry is checked against your enrichment allowance for the number of items shown on the button.
  • Cancel Job — stops a job that is still pending, queued, or in progress. Jobs that have already finished can’t be cancelled. See Cancelling a catalog publish for what a cancel does to work that is already under way.
From the Jobs list you can also select several jobs at once and Cancel the in-flight ones, Archive finished ones (they move out of the Active view — switch View to Archived to see them again), or Delete them permanently. A job must be finished or archived before it can be deleted; cancel it first if it’s still running.

​
Cancelling a catalog publish

Cancelling a Catalog Publish job stops the publish. Records that have not yet been sent to the target are stopped and counted as cancelled; nothing further is sent for them. This applies to any catalog publish — one that started on its effective date and one you started with Publish now alike.
Cancel stops work; it never undoes it. Records that already reached the target before the cancel took effect stay published there. Cancelling is not a rollback — to reverse what already landed, publish a corrected batch.
What you see afterwards:
  • The job settles as Cancelled, and stays cancelled. Records that were already in flight when you pressed cancel can no longer re-stamp it as Failed.
  • The counts line reports both halves: what published before the cancel took effect (in processed), what failed, and what the cancel stopped (in cancelled).
  • The batch it was publishing is moved to a terminal state — Partial if at least one record published, Failed if none did — so it never strands in its publishing state. The cancellation is recorded in the batch’s activity history.
  • Because the batch is already terminal, it can be published again straight away. You do not need Reset publishing after a cancel; that action is for a publish that stopped reporting on its own. See Fixing a partial batch.
Cancelling an enrichment job also stops queued work — items that hadn’t started are left unfinished so Retry Unfinished can resume exactly where the run stopped. For other job types, cancelling records the job as Cancelled, but work already in progress may still run to completion.

Data ingestion

How products get into MerchantOps — the imports that create jobs.

How enrichment works

Enrichment runs as a background job over your products.