Create catalog items via POST /api/catalog-items/ with id (your external item ID prefixed with $custom:::), title, description, url, image_url, and custom_metadata fields
Create catalog variants via POST /api/catalog-variants/ linked to the parent catalog item via relationships.item; include price, inventory_quantity, and inventory_policy (continue or stop)
To trigger back-in-stock: when a variant's inventory_quantity returns to a positive value, PATCH /api/catalog-variants/{id} to update inventory_quantity; this fires the Back In Stock trigger for subscribers
Subscribe a profile to back-in-stock alerts via POST /api/back-in-stock-subscriptions/ with the catalog variant id and profile identification; Klaviyo queues the flow trigger for when inventory is updated
Sync catalog item metadata changes (price, title, image) via PATCH requests to keep flow email content current; full re-creation is rarely needed unless the item ID changes
Known gotchas
Catalog item and variant IDs are compound strings with a required prefix (e.g., $custom::: for custom catalogs); omitting the prefix or using a plain numeric ID returns a 400 error
Back-in-stock flow triggers fire asynchronously after inventory updates — there is no guarantee of immediate delivery; test with small inventory changes in a sandbox before relying on timing in production
Klaviyo catalog variants must be linked to a parent catalog item at creation time; there is no endpoint to re-parent a variant to a different item after creation
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp