Skip to main content

App Bridge for Checkout

Checkout extensions render as iframes inside the customer-facing checkout (/checkout). They use the same App Bridge wire format as admin extensions, but the host on /checkout exposes a customer-safe subset of actions — no resource pickers, no admin modals, no title bars. Use this page when building any extension whose target starts with checkout-*, checkout.*, or purchase.checkout.*. Extensions on the order status page (purchase.thank-you.*, purchase.order-status.*) talk to the post-purchase host instead.

What’s different from admin App Bridge

Calls to unsupported actions return no response — the SDK call will reject with a timeout after 10 seconds. Design your extension to gracefully degrade if a non-checkout action fails.

Initializing

The host adds only an extensionId query parameter to your iframe URL — no apiKey, host or shop parameter, and there is no session token at checkout (call SHOP_GET to learn which store you are in). Use the lightweight client below, or the SDK:
The SDK resolves host: 'checkout' to the origin of the page embedding your frame and only accepts replies from that origin. Older SDK builds resolved it to the frame’s own origin, which only works for frames served from the store’s domain; with one of those, pass the checkout’s origin explicitly: host: btoa(location.ancestorOrigins?.[0] || new URL(document.referrer).origin).

Action Reference

BRIDGE_PING

Capability handshake. Resolves with { ok: true, host: 'checkout' } if the checkout host is listening.
Use this to detect whether your extension is running inside the checkout host or some other surface, and feature-flag accordingly.

TOAST_SHOW

Show a toast notification rendered by the checkout’s toast system.
Response: { ok: true }

CART_GET

Read the current cart.
Line ids stay the same while the line stays in the cart, so an id read here can be passed to updateCartLine / removeCartLine later.

CHECKOUT_TOTALS_GET

Read the price breakdown as numbers — the same figures the order summary shows.
Refresh by polling — there is no push notification. A 2–3 second interval is reasonable.

COST_GET

The same totals as { amount, currencyCode } money objects. amount is a string with two decimals.
totalDiscountAmount does not include shipping discounts or gift cards — read those from CHECKOUT_TOTALS_GET. Like CHECKOUT_TOTALS_GET, this is a snapshot; re-poll after any cart / discount / address change.

CUSTOMER_GET

email is what is in the checkout’s email field (an empty string until the buyer types one; pre-filled for a logged-in customer). customer is null for a guest.

CURRENCY_GET

currency is what the checkout charges in and baseCurrency the store’s own currency. rate converts a base-currency amount to the checkout currency, including the store’s conversion fee; it is 1 when nothing is converted. Round the product to the checkout currency’s precision (two decimals; none for JPY-style, three for BHD-style currencies) to match what the checkout charges.

BUYER_IDENTITY_GET

LOCALIZATION_GET

The buyer’s country (the shipping destination the checkout is using, else the store’s country), the checkout language and the currency.
Use this to switch between localised marketing copy or hide an extension entirely in unsupported regions.

SHIPPING_ADDRESS_GET

The address the checkout will ship to — the one it quotes shipping for: the address the buyer is typing, or the saved address a logged-in customer selected.
address is always an object: fields the buyer has not filled are empty strings (the country can be filled before anything else, from the buyer’s location). provinceCode is the province name when the name has no known code.

BILLING_ADDRESS_GET

LaunchMyStore checkout does not split shipping/billing — this returns the same address payload as SHIPPING_ADDRESS_GET.

DISCOUNT_CODES_GET

Discount codes applied to this cart: the code the buyer (or an extension) entered, and the store’s automatic discount when it applies.

APPLIED_GIFT_CARDS_GET

Gift cards applied to this checkout, with what each covers.

DELIVERY_GROUPS_GET

The delivery options the shopper can see for the current cart and address — the merchant’s shipping zones after any delivery customization, the store’s own delivery method, rates from shipping apps and pickup locations — and the one they picked. Costs are in the checkout currency, as the rows show them.
Handles are the same ones delivery customization and order validation functions see, listed in the same order: a shipping-zone id, shipping:<shippingId> for the store’s own delivery method (source: 'shipping_method'), app:<appId>:<code> for an app rate, and pickup:<locationId> for a pickup location. In app:<appId>:<code>, appId is your app’s handle for rates from a shipping-rate function and your app’s id for live (carrier) rates, so to recognise your own rate compare source, which carries your app’s handle. The host has no change events; poll this action (every few seconds) to follow the shopper’s choice. A single delivery group is returned today; future multi-shipment support will expand this into one group per shipment.

SHOP_GET

Identity of the store the checkout is running on.
storefrontUrl is the address the buyer is actually using, including a custom domain; storeDomain is the store’s canonical domain.

INSTRUCTIONS_GET

Capability flags describing what the checkout host lets your extension change.
Every flag is true on the checkout today; check them anyway so your extension keeps working if a store restricts a change later.

ATTRIBUTES_GET

All cart-level attributes apps and other extensions have written.
The same map is persisted onto the order at placement and queryable in Liquid via order.attributes.

ORDER_NOTE_SET

Legacy alias for NOTE_CHANGE / updateNote. Persisted to the cart’s note field and saved on the order when it’s placed.
Pass an empty string to clear the note.

COUPON_APPLY_REQUEST

Legacy form of DISCOUNT_CODE_CHANGE / addDiscountCode: puts the code in the checkout’s code field and applies it, through the merchant’s coupon rules (eligibility, expiry, minimums).
The reply is always ok: true (the request was taken); applied says whether the code took. New extensions should use DISCOUNT_CODE_CHANGE, which rejects with the reason instead.

Cart Mutation Actions

The checkout host exposes a declarative cart-mutation surface: an extension calls one of the actions below, the host applies the change, and the reply carries the outcome plus the updated cart (the CART_GET shape) as cart. The checkout then re-verifies the cart in the background — prices, discounts, shipping and totals refresh a moment later, so read COST_GET again after a change rather than computing totals yourself. Use the Cart class from @launchmystore/app-bridge for type safety; the raw action names are documented below for reference.

CART_LINES_CHANGE

Add, update, or remove cart lines. Accepts a single change, an array of changes, or { changes: [...] }; changes apply in order, so a batch can add a line and then update it.
Response:
A change that fails does not reject the call — check ok / results. Per-change errors: merchandiseId must be a ProductVariant gid (…) or a variant UUID, quantity must be a positive integer, quantity must be a non-negative integer, invalid sellingPlanId, line not found, invalid line id, line id required, unsupported change type. A payload with no change at all rejects with changes required. A line added with only a merchandiseId shows in the order summary with the product’s title, image and price from the catalogue, the same as a line the shopper added from the storefront. This covers upsells, gifts and protection products that are not already in the cart.

DISCOUNT_CODE_CHANGE

Apply or remove a discount code.
Adding a code runs the merchant’s coupon rules — eligibility, expiry and minimums. A code that does not apply rejects with the reason (the raw reply carries it in error and in the payload as { ok: false, type: 'error', message, code }). Adding the code that is already applied answers alreadyApplied: true. Removing works for the code the buyer (or an extension) entered and for the store’s automatic discount; dismissing the automatic discount keeps it off for that buyer for a day. Removing a code that is not applied answers removed: false.

NOTE_CHANGE

Update or remove the cart note.
The reply is { ok: true, type: 'success', note, cart }. The note is stored on the cart and persisted to the order’s note field at placement.

ATTRIBUTE_CHANGE

Set or remove a cart-level attribute (key/value pair stored on the order).
Attributes are stored on the cart and persisted with the order so they’re queryable in Liquid templates and admin order detail pages. Functions see them when the cart is re-verified.

GIFT_CARD_CHANGE

Apply or remove a gift card on the checkout. Both operations are live — they call the same apply/remove path as the checkout’s own code field, so the order summary and totals update accordingly.
The SDK type union is 'addGiftCard' | 'removeGiftCard'; the raw action also accepts 'applyGiftCard' for add. A card that does not apply rejects with the reason — for example Gift card GC-1 not found, … is disabled, … has expired, or … has no balance to apply to this order. Applying a card that is already applied answers alreadyApplied: true; removing one that is not applied answers removed: false. Read applied cards back with APPLIED_GIFT_CARDS_GET.

SHIPPING_ADDRESS_CHANGE

Update the shipping address. Only updateShippingAddress is supported — there is no add/remove distinction because the checkout holds exactly one address at a time.
Without the SDK, dispatch SHIPPING_ADDRESS_CHANGE with the same payload. Only the fields you send change. countryCode is an ISO country code; provinceCode is an ISO 3166-2 code, with or without the country prefix ('NY' or 'US-NY'), or send the name as province. Moving the address to another country clears the province unless you send one. The change applies to the address the checkout is using — the one the buyer is typing, or the saved address a logged-in customer selected — and shipping options and totals are re-quoted for it. Error responses:
  • 'address required' — no address object passed
  • 'address mutation not available' — the host page hasn’t wired the writer (e.g. read-only screens)
  • 'unknown address change type' — type is not updateShippingAddress

METAFIELD_CHANGE

Write or remove a cart-scoped metafield. Updates are stored on the cart, reflected in CART_GET’s metafields, and follow the cart to the order, so an extension can attach data (gift message, engraving text, etc.) that becomes order.metafields.
namespace and key are required; an unknown type returns unsupported METAFIELD_CHANGE type "<x>", and a write the store rejects (for example a value that fails the metafield’s definition) rejects with the reason. For owner-scoped metafields (product / customer / order) use the REST endpoints (/metafields / /api/v1/metafields) instead.

Buyer Journey Intercept

Block the buyer from placing the order until your condition is met. The host asks every extension on the checkout when the buyer clicks the pay button — after the checkout’s own field validation passes and before the order is created, whatever the payment method (a retry of a failed payment is not intercepted).
The host sends BUYER_JOURNEY_INTERCEPT_REQUEST (as a host push, with a requestId, step: 'checkout.payment', the order total and currency); the SDK runs your callback and answers with BUYER_JOURNEY_INTERCEPT_RESPONSE carrying the same requestId. The callback can be async. The host waits 4 seconds in total for the extensions to answer. A frame that does not answer in time, a callback that throws, and a callback that returns nothing all count as allow. When any extension blocks, the order is not placed and the reasons are shown to the buyer in a toast. Result shape: Without the SDK, listen for an APP_BRIDGE_RESPONSE message whose action is BUYER_JOURNEY_INTERCEPT_REQUEST and post an APP_BRIDGE_ACTION with action BUYER_JOURNEY_INTERCEPT_RESPONSE and payload { requestId, behavior, reason }.

Page lifecycle

When the checkout page gains or loses focus, or is hidden or shown (the buyer switches tabs), the host sends APP_FOCUS, APP_BLUR, APP_VISIBLE or APP_HIDDEN to every extension frame. The SDK’s Lifecycle reports them together with your frame’s own focus changes:

APP_BRIDGE_RESIZE

Tell the host to resize your iframe to fit content. Use a ResizeObserver to call this automatically.
The host clamps the height to [60, 2000] pixels and matches the message to your frame by the window that sent it (an extensionId field is optional). This is a fire-and-forget message — no response.

Available Targets

Where each checkout target renders — including the phone layout, the Shopify target names that are accepted, and the order status page targets — is listed in Checkout UI Extensions → Target Slots.

Worked Example: Delivery Instructions Card

A complete iframe that asks the customer for delivery instructions and saves them via NOTE_CHANGE.
Register the manifest in your app.json:

Persistence Guarantees

What survives into the placed order:
  • Notes, attributes, cart lines and cart metafields survive. They are sent with the order at placement (note, attributes, line properties, order.metafields).
  • Discount codes and gift cards apply through the merchant’s rules. An extension cannot apply a code the checkout would reject; the call rejects with the reason instead.
  • Shipping address changes survive — the order ships to the address the checkout holds when the buyer pays.
  • TOAST_SHOW is ephemeral. Toasts vanish on page reload.
Function-based price changes (cart_transform, discount, shipping_rate, payment_customization, delivery_customization, order_validation) are separate from App Bridge — they’re declarative functions that run at cart verification and order placement. Use those for guaranteed cart mutations; use App Bridge actions for opt-in customer interaction.

Security Notes

  • The checkout host answers only iframes it rendered into a checkout extension slot — the message’s source window is matched against the slot iframes by identity. Messages from any other frame on the page (an app-embed script’s iframe, a chat widget, the top window itself) are silently ignored. This also means you can’t exercise the bridge from the browser devtools console at the top window — post from inside an extension iframe.
  • Buyer data an extension can read. There is no per-app permission for checkout data — every extension frame on the checkout can read:
    • CUSTOMER_GET, BUYER_IDENTITY_GET — the buyer’s email and phone, and the logged-in customer’s id;
    • SHIPPING_ADDRESS_GET, BILLING_ADDRESS_GET — the full shipping address: name, street lines, city, province, postal code, country, phone and company;
    • CART_GET — lines, note, attributes, cart metafields and the cart token;
    • DISCOUNT_CODES_GET, APPLIED_GIFT_CARDS_GET — applied discount codes, and applied gift card codes with their amounts and remaining balances;
    • totals, currency, country, language and delivery options.
    Card and other payment details never reach the checkout page (payment happens with the payment provider), and passwords and session tokens are never exposed. Read only what your extension needs and cover it in your privacy policy.
  • Iframes use sandbox="allow-scripts allow-forms allow-popups allow-same-origin". A frame served from your own domain is isolated from the checkout by the browser’s same-origin policy; a frame served from the store’s domain (a relative iframeUrl) is same-origin with the checkout and is not isolated from it. Top-level navigation is blocked; popups open in a new tab.

Troubleshooting

My dispatchAndWait always times out. Confirm your code runs inside a checkout extension slot iframe — the host ignores messages from any other frame (see Security Notes). With the SDK, check app.hostOrigin is the checkout page’s origin (see Initializing); the SDK drops replies from any other origin. The host is listening once the checkout page has rendered, so a BRIDGE_PING sent at script start may need one retry. A discount code or gift card call rejects. The rejection message is the reason the checkout refused it (invalid code, not applicable to the cart, expired, no balance left). Show it to the buyer. CART_LINES_CHANGE resolves but nothing changed. Check ok and results[] — a change that fails (an unknown variant id, a line id that is no longer in the cart) does not reject the call. Iframe height won’t change past 2000px. The host clamps APP_BRIDGE_RESIZE to [60, 2000]. Split content across multiple slots or use internal scrolling if you need more vertical space.