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 anextensionId 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:
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.
TOAST_SHOW
Show a toast notification rendered by the checkout’s toast system.
Response:
{ ok: true }
CART_GET
Read the current cart.updateCartLine / removeCartLine later.
CHECKOUT_TOTALS_GET
Read the price breakdown as numbers — the same figures the order summary shows.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.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 sameaddress 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.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.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.order.attributes.
ORDER_NOTE_SET
Legacy alias forNOTE_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 ofDISCOUNT_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 (theCART_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:
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.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. OnlyupdateShippingAddress is supported — there
is no add/remove distinction because the checkout holds exactly one address
at a time.
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'— noaddressobject passed'address mutation not available'— the host page hasn’t wired the writer (e.g. read-only screens)'unknown address change type'—typeis notupdateShippingAddress
METAFIELD_CHANGE
Write or remove a cart-scoped metafield. Updates are stored on the cart, reflected inCART_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).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 sendsAPP_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 aResizeObserver to call this automatically.
[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 viaNOTE_CHANGE.
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_SHOWis ephemeral. Toasts vanish on page reload.
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.
-
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 relativeiframeUrl) is same-origin with the checkout and is not isolated from it. Top-level navigation is blocked; popups open in a new tab.
Troubleshooting
MydispatchAndWait 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.