Add checkout block

Adds a checkout block to one of an experience's variations.

The block starts from its template's defaults. Send only what you want to change, at any depth: every field of variables and styles you leave out keeps the template's value. A list you send, such as a trust badge's items or an FAQ block's questions, replaces the template's list whole.

Required Fields

• blockType (string) — The block type (see the list above)
• variationId (UUID) — The variation to add the block to. It must belong to the experience in the path.

Optional Fields

• name (string) — Display name in the dashboard. Defaults to the template's name and the block's position.
• template (string) — The preset to start from. The values depend on blockType. Not accepted for postPurchaseUpsell.
• variables (object) — Content settings for this block type
• styles (object) — Style settings for this block type
• displayConditions (object) — Cart conditions that decide when the block shows. Omit it to show the block on every cart. Not accepted for postPurchaseUpsell.
• upsellProductRules (array) — Which products the block recommends. upsell and postPurchaseUpsell only. Leave it out to start with Shopify's recommendations on every cart or order, the same as a block added in Intelligems.

Response

{ "block": { ... } }, with the saved block. A postPurchaseUpsell block also returns adjustments, listing anything the API changed on its own to keep the offer valid. An upsell block sent without upsellProductRules returns adjustments too, saying which products it starts with.

Important Notes

• Blocks can only be added to a checkoutBlock, postPurchase or personalization experience, the same as in Intelligems. Adding one to any other experience, such as a price or offer test, returns a 400.
• A postPurchaseUpsell block needs a store that is ready for post-purchase upsells. If it isn't, the request returns a 400 listing what to fix.
• Discounts can't be set with an API key. An upsell's variables.discount, a product rule's discount, and a post-purchase upsell's discountType and discountValue return a 400. Set discounts in Intelligems.
• On a store that uses Agentic Logic, a new upsell or postPurchaseUpsell block shows products from the store's built-in "Shopify recommendations" rule, the same as one added in Intelligems. Its products come from that rule, so upsellProductRules returns a 400 there. To show different products, pick another rule in Intelligems.
• A recurring timer's resetTimezone is set to the store's timezone. If the store has none, send one: it has to be an IANA name such as America/New_York, or the request returns a 400.
• Blocks added to a running experience show to shoppers immediately.

Rate Limit: 50 requests per 30s window, refilling 25 tokens every 30s.