Query matching products and variants
catalog.query defaults to active sellable SKUs. Parent containers are excluded, and variants do not need separate lookups. Select the fields needed for the task and use cursor pagination for matching rows. IDs and currency companions of monetary fields are always included. Maximum page size: 500.
productIds, skus, and currencies. Set sellableOnly: false to include parent containers. These are catalog statuses, independent of marketplace listing status. Read-only credentials require catalog:read.
matchedCount counts the full filtered selection. Continue with nextCursor, the same filters/fields, and includeCount: false (include_count=False in Python) to avoid repeating the count. hasMore: true means the selection is incomplete.
Cost comparisons use each product’s catalog currency and valid recorded conversions. Missing costs and unavailable conversions are excluded and counted in diagnostics. Original cost and costCurrency are preserved; select costInCatalogCurrency and costConversion for the comparison amount and FX evidence. Currency conversion does not authorize swapping raw amounts between different currencies.
Submit a durable update
Supply 1–2,000 simple-product or variant updates in one request. Each entry can atomically set price and cost. Include the queriedexpectedUpdatedAt to reject changes made after review. Identical duplicates collapse in requested order; conflicting duplicates are rejected.
productId, price, salePrice, currency, costPrice, costPriceCurrency, and expectedUpdatedAt. Optional targets: [{ platform, accountId }] selects up to 25 exact connected stores for that update; omitted targets select all eligible listings. Setting costPrice to null clears it. Cost remains in Omni and never publishes to marketplaces. Existing eligible marketplace listings use the shared publishing and pricing rules when price sync is requested; this operation does not create new listings.
The default is syncToMarketplaces: false and verify: true. Requires catalog:write; status and state reads require catalog:read.
Reuse the same idempotency key with identical input after a transport failure. It retains the original targets and versions. Changed input with that key returns 409. Save operation IDs and let the submitting process finish: accepted work continues after disconnection. Per-target failures do not abort independent targets. Inspect saved receipts before retrying a failed target.
Read progress and evidence
success requires every requested target to succeed; partial failure remains explicit. verifiedCount distinguishes confirmed states from writes submitted with verification disabled.
The outer status counts refer to operations. Each entry in results contains that operation’s product counts.
Reports retain ordered per-target receipts, job IDs, errors and verification evidence. They return at most 100 rows per page across the requested operations. Continue with the numeric nextCursor and the same filters. Operation IDs belong in bulk.status, while ordinary job correlations retain their existing APIs.
For a new attempt after a terminal failure, review the current catalog values, use a new idempotency key, and select only the failed stores in targets. Reuse the saved absolute price/cost assignments when still correct; do not recalculate a swap from values already changed by the first operation. The old key continues to identify the original operation.
Delegated Computer requests automatically link to their authenticated chat. Linked operations appear in Runs and continue the conversation on completion, subject to current access, explicit stops and pending interactions. Other clients may supply an owned sessionId or retrieve status later.
Durable verification
Usecommerce.start_verification(idempotency_key=..., verification={"targets": [...]}) in Python or commerce.startVerification({ idempotencyKey, verification: { targets } }) in TypeScript for up to 2,000 product targets. The nested verification request uses the existing product verification contract. Read its returned operation IDs through bulk.status and bulk.results.
Targets must exist and be accessible at submission. Use the existing commerce.verifyState / commerce.verify_state API for already deleted products and fulfillment correlations.
Product price verification uses exact acknowledged marketplace prices matching the expected catalog amount and currency, including channel markups. Product, store, country and currency identities remain distinct. Missing evidence or a mismatched state remains a failure.