Tools

Publish

publish_master_v1 starts a background publish through the same admission, locking, and orchestration the app uses. Its response confirms acceptance; operation reads report what reached Shopify.

This mutates your live Shopify stores.

It requires the Read, write & publish tier — pim:publish is grantable only through the browser consent flow, never through any other credential surface.

publish_master_v1

publish_master_v1pim:publish

Argument	Type	Description
`id`	string, required	Item id. Must belong to the token's account; cross-account ids return "not found".
`channel_ids`	string[]	Restrict the publish to these store ids (validated against the account). Omit or leave empty to publish to every store the item has a per-store version on.

What the orchestration does

Admission resolves the stores, acquires the item's dependency locks, and queues the operation. The background worker publishes each store's changes: unchanged work can be skipped, isolated field changes can take a narrowed path, and other changes use the full entity pipeline. A product publish includes its eligible variants and media; a collection publish reconciles its sources. Product hand-picked collection changes are published through their owning collections.

Acceptance, progress, and partial failure

The successful tool result has this shape:

{"accepted": true, "operation_id": "…", "status": "queued", "total": 1}

This is not a completed publish. Poll get_publish_operation_v1 with id: operation_id until the run is terminal, then read get_publish_operation_recap_v1 for item and per-store outcomes. get_publish_failures_v1 explains current failures and names responsible fields. Already-published stores stay live if another store fails or the operation is canceled. Fix the cause and retry the failed stores with channel_ids.

For a selection, publish_batch_v1 returns an {operation: {...}} envelope; poll its operation.id. See Publish operations for batch publication, locks, progress, recap, and cancellation.

The 120 s timeout — and what a timeout means

The tool has a 120 s admission budget; the background run has its own lifecycle. If the call times out, an operation may already have been queued. Inspect list_publish_operations_v1 and the item's publish state before retrying. Other long-running tools also have extended budgets — see Security & limits.

Before publishing

Review get_pending_changes_v1 for fields and relationships that still need publishing, including related items that require their own publish.
Check where the item is visible today with the sales-channel reads if channel placement matters.
Conflicting publishes and edits return 409; query_publish_locks_v1 identifies the operation holding the dependency locks.
If a variant's product does not exist on the selected store yet, the endpoint can require parent-publication confirmation. The current MCP tools cannot submit that confirmation; complete the first publication in the app, where the product and variant scope can be reviewed.
During an import/refresh reconciliation, the account is write-locked (423) — see Security & limits.