Marketplace Catalog Sync

• Building a seller connector that needs to push new SKUs into a VTEX marketplace and handle the suggestion (send → pending → approved/denied) lifecycle.
• Implementing the Change Notification flow to detect whether a SKU already exists in the marketplace (200 OK) or needs a new suggestion (404 Not Found).
• Synchronizing price and inventory changes via the /notificator/{sellerId}/changenotification/{sellerSkuId}/price and /inventory endpoints.
• Implementing the seller-side Fulfillment Simulation endpoint (POST /pvt/orderForms/simulation) that must respond within 2.5 seconds.

• You are performing marketplace-side catalog operations such as direct POST /api/catalog/pvt/product or POST /api/catalog/pvt/stockkeepingunit writes — those are not seller-connector flows.
• You need order fulfillment or invoice handling logic (see the marketplace-fulfillment skill instead).
• You need rate-limiting patterns in isolation, decoupled from catalog notification flows (see the marketplace-rate-limiting skill instead).

Seller connectors must use POST .../changenotification/{sellerId}/{sellerSkuId} — not the single-segment changenotification/{skuId} route, which expects a marketplace VTEX SKU ID. This skill documents the distinction, explains why official docs sometimes conflate the two routes, and provides concrete TypeScript examples for both the 200 (update) and 404 (new suggestion) response paths.

New SKUs must go through the suggestion/approval workflow via PUT https://api.vtex.com/{accountName}/suggestions/{sellerId}/{sellerSkuId} — direct Catalog API writes are forbidden for external sellers and will return 403 Forbidden. The skill enforces a status check before any suggestion update, because suggestions can only be modified while in the Pending state; approved or denied suggestions cannot be changed.

Price and inventory updates are sent via separate POST /notificator/{sellerId}/changenotification/{sellerSkuId}/price and .../inventory endpoints, where the path segment is the seller's SKU ID (not the marketplace VTEX SKU ID). After these notifications, the marketplace calls the seller's Fulfillment Simulation endpoint to retrieve current data.

The marketplace calls the seller's POST /pvt/orderForms/simulation endpoint after every price or inventory notification. VTEX waits a maximum of 2.5 seconds for a response; exceeding this limit marks the product unavailable in the storefront. This skill provides a cache-first implementation pattern (in-memory or Redis) so the endpoint responds in under 50 ms.

Sending bulk Change Notification requests without throttling triggers 429 responses that block the seller's entire API access. This skill provides a batched, concurrency-controlled notification loop with per-batch delays, retry-after header parsing, and exponential backoff on 429 errors.

Catalog System routes (e.g., changenotification) use the store hostname ({account}.vtexcommercestable.com.br), while SKU Suggestion routes use https://api.vtex.com/{accountName}. Both surfaces authenticate with the same X-VTEX-API-AppKey and X-VTEX-API-AppToken headers. The skill provides a typed SellerConnectorConfig and Axios client factory covering both base URLs.

A seller is connecting to a VTEX marketplace for the first time and needs to register its entire SKU catalog. The integration calls changenotification/{sellerId}/{sellerSkuId} for each SKU; every 404 triggers a PUT SKU Suggestion, placing each SKU into the marketplace's pending review queue for operator approval.

A seller's warehouse system emits price or stock change events. The connector sends batched price and inventory notifications via the /notificator/ endpoints, and the seller's Fulfillment Simulation endpoint — backed by a pre-warmed cache — responds to marketplace polling requests within the 2.5-second deadline.

An operator needs to update product data on a suggestion that was sent but not yet reviewed. The integration first calls GET /suggestions/{sellerId}/{sellerSkuId} to confirm the suggestion is still in Pending state, then issues a PUT with the corrected data. Suggestions already approved or denied are skipped with a warning.

After a product data migration, hundreds of SKUs need re-notification. The integration uses the batched notification pattern — processing SKUs in groups of five with 200 ms inter-batch delays and 429-aware retry logic — to re-notify the marketplace without triggering rate-limit blocks.