Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 55 ยท App Extensions

Checkout UI Extensions

Add upsells, gift messages and custom fields to Shopify checkout: targets, Polaris checkout components, cart line data, sandbox limits and applying cart changes.

Checkout is where the money changes hands, and Shopify keeps tight control over it. You cannot edit checkout templates or inject scripts. What you can do is add small, safe pieces of interface in places Shopify chooses: a gift-message box under the contact form, an upsell after the line items, a banner above the payment step. These pieces are checkout UI extensions.

This lesson explains targets, how the interface and cart data reach your code, what the sandbox forbids, and how an extension changes the cart. Real extension code needs the CLI and a development store with checkout extensibility, so it is shown read-only. The runnable TryIts are honest stand-ins: a tiny target renderer and a fake cart-change API. Examples target API version 2026-07; generate a fresh extension with the CLI to see the exact imports of your version, because details of checkout extensibility change between versions.

Where your code runs

A checkout UI extension is a ui_extension (see App Extensions Overview). It does not run on your server and it does not run as ordinary page JavaScript. Shopify loads your bundle into an isolated sandbox (a worker, not the checkout page), and your code describes a tree of approved components. Shopify draws them natively inside checkout, so they are fast, accessible and cannot read card numbers or restyle the page.

flowchart LR
  B["Buyer in checkout"] --> C["Checkout page (Shopify)"]
  C -->|"renders components"| T["Native components"]
  C <-->|"messages"| S["Sandbox: your extension code"]
  S -->|"applyCartLinesChange"| C
  S -.->|"fetch (needs network access)"| API["Your server"]

Your code sends a component tree and cart-change requests to checkout; it never touches the checkout DOM.

Targets: static and block

A target is a named slot in checkout. There are two families.

Static targets sit at fixed spots next to Shopify's own sections, for example:

  • purchase.checkout.cart-line-item.render-after shows content after each line item, so it runs once per line.
  • purchase.checkout.delivery-address.render-before and purchase.checkout.payment-method-list.render-after sit around the address and payment sections.
  • purchase.checkout.reductions.render-after is next to the discount-code field.

Block targets such as purchase.checkout.block.render are not tied to a place. The merchant drops your block anywhere in the checkout editor (in the theme editor family of tools), moves it and edits its settings, much like the app blocks you saw in Theme App Extensions.

There are also targets for the thank-you and order-status pages, such as purchase.thank-you.block.render. Target names, and which ones exist for your store's plan, change between API versions, so confirm names in the current reference rather than trusting a memorized list.

The TOML declares the target and the module that renders it:

TOML
# extensions/gift-message/shopify.extension.toml  (read-only)
api_version = "2026-07"

[[extensions]]
name = "Gift message"
handle = "gift-message"
type = "ui_extension"

  [[extensions.targeting]]
  target = "purchase.checkout.block.render"
  module = "./src/Checkout.jsx"

  [extensions.capabilities]
  network_access = false
  api_access = false

Capabilities are opt-in. network_access lets the extension call external URLs with fetch; api_access lets it query the Storefront API. Merchants can see which extensions request them, and network access may need a separate approval. Request only what you use, as in the App Security Checklist.

The interface: Polaris checkout components

You build the interface from Polaris web components (the s- elements). A checkout-flavored set exists: stacks and grids for layout, s-text, s-heading, s-banner, s-text-field, s-checkbox, s-choice-list, s-button, s-image, s-divider and more. Because Shopify renders them, they pick up the merchant's checkout branding automatically; you cannot set arbitrary colors or CSS.

A read-only gift-message block, in the JSX style CLI templates use:

JSX
// src/Checkout.jsx  (read-only: needs the Shopify CLI and a development store)
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [message, setMessage] = useState('');

  async function save() {
    const result = await shopify.applyAttributeChange({
      type: 'updateAttribute',
      key: 'gift_message',
      value: message,
    });
    if (result.type === 'error') {
      console.error(result.message);
    }
  }

  return (
    <s-stack gap="base">
      <s-text-field
        label="Gift message"
        value={message}
        onInput={(event) => setMessage(event.currentTarget.value)}
      />
      <s-button onClick={save}>Add message</s-button>
    </s-stack>
  );
}

Notice there is no document.querySelector against the checkout page, no window.location navigation, and no CSS. The component names and the way events are wired can differ between versions, so treat the snippet as the shape of the idea.

Reading cart data

The extension receives checkout data through the global shopify object. Many values are signals: objects with a .value that updates when the cart changes (a buyer edits a quantity, or a discount applies). Reading a signal's value inside your component re-renders it when the value changes.

A read-only example:

JSX
// src/LineNote.jsx  (read-only)
export default async () => render(<LineNote />, document.body);

function LineNote() {
  const lines = shopify.lines.value;           // all cart lines
  const total = shopify.cost.totalAmount.value; // { amount, currencyCode }
  const line = shopify.target.value;            // on a per-line target: this line

  return (
    <s-text>
      {line.merchandise.title} x {line.quantity} (order total {total.amount} {total.currencyCode})
    </s-text>
  );
}

Typical data available to checkout extensions includes the cart lines, cost, shipping address and selected delivery options, discount allocations, buyer identity and settings you define in the TOML for the merchant. What exactly you see also depends on the protected customer data access your app was granted; see Orders, Customers and Protected Data.

A runnable target-render stand-in

The real renderer lives in Shopify. This stand-in shows the idea of targets: a "checkout" with named slots, a registry of extensions per target, and a per-line target that runs once for every line. The names mimic the real ones; the mechanics are simplified.

Node.js Render extensions into checkout targets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The per-line target ran twice, once for each line, and only the mug line produced output. Real per-line targets work the same way: write the extension as "what do I show for this line?"

Changing the cart

Extensions can change the cart, but only through checked APIs, never by writing to a global. The main ones:

  • shopify.applyCartLinesChange(change) adds a line, removes a line or updates a quantity. Change types are addCartLine, removeCartLine and updateCartLine.
  • shopify.applyAttributeChange(change) sets or removes a cart attribute (the gift message above); attributes appear on the order.
  • shopify.applyNoteChange(change) updates the order note.
  • shopify.applyDiscountCodeChange(change) adds or removes a discount code.
  • shopify.applyShippingAddressChange(change) updates the address when the extension is allowed to.

Each returns a promise that resolves to a result: {type: 'success'} or {type: 'error', message}. Never assume success. Checkout also exposes instructions (shopify.instructions.value), which describe what the current checkout allows. A checkout where the merchant disallowed cart updates tells you so, and you should hide the upsell button instead of letting it fail.

A read-only upsell button:

JSX
// src/Upsell.jsx  (read-only)
function Upsell({variantId}) {
  const canAdd = shopify.instructions.value.lines.canAddCartLine;

  async function add() {
    const result = await shopify.applyCartLinesChange({
      type: 'addCartLine',
      merchandiseId: variantId,          // a gid://shopify/ProductVariant/... id
      quantity: 1,
    });
    if (result.type === 'error') {
      // show result.message in an s-banner, keep the buyer in control
    }
  }

  return canAdd ? <s-button onClick={add}>Add gift wrap</s-button> : null;
}

Where the upsell recommendations come from is your problem: a settings value, a hard-coded variant, or a call to your own backend with network access enabled. The full build is in Project: Checkout Upsell Extension.

A fake cart-change API

This stand-in mimics the result contract: a cart, an instructions object, and applyCartLinesChange that either succeeds or returns an error result. The inventory limit is invented for the demo.

Node.js Apply cart changes and handle errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Sandbox limits and design rules

  • No DOM and no global styles. You describe components; Shopify renders them. There is no access to cookies, localStorage of the checkout page, or the payment fields.
  • Network is a capability. Without network_access, fetch to external hosts fails. With it, your server must allow cross-origin requests and verify the session token the extension sends, as in Session Tokens for Embedded Apps.
  • Be fast and small. Your bundle loads during checkout; a slow extension slows every buyer. Keep dependencies minimal and avoid blocking on network calls before rendering.
  • Fail soft. If your server is down, render nothing rather than a broken box. Checkout must always be completable.
  • Validation is separate. An extension can suggest, but rules that must hold (for example "no shipping to this region") belong to a function; see Cart Validation, Delivery and Payment Customization. Extensions run in the buyer's session and can be unavailable.
  • Respect the buyer. Do not add lines silently. Make upsells optional, and do not steer buyers with misleading wording, which also risks App Store review.

Shared ideas about checkout, carts and order totals are covered in the E-commerce Fundamentals track.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a checkout UI extension's code run?

    Extensions run in a sandbox; they describe components and Shopify renders them, so extensions cannot read the page or the payment fields.
  2. 2. What is the difference between a static target and a block target?

    Static targets such as cart-line-item.render-after are tied to a position. Block targets, such as purchase.checkout.block.render, can be positioned by the merchant.
  3. 3. applyCartLinesChange resolves with { type: 'error', message }. What should your extension do?

    Changes can fail (stock, permissions, merchant settings). Handle the error result, keep the buyer informed and never block checkout.
  4. 4. Why does an extension that calls your own backend need the network_access capability?

    Network access is opt-in so that merchants and Shopify can see which extensions talk to external servers.

Summary

  • Checkout UI extensions add small pieces of interface to checkout through targets; they run in a Shopify-managed sandbox and never touch the page DOM.
  • Static targets sit at fixed positions (some run once per cart line); block targets such as purchase.checkout.block.render are placed by the merchant in the checkout editor.
  • The interface is Polaris web components; cart data arrives as signals on the shopify global.
  • Change the cart only through applyCartLinesChange, applyAttributeChange and similar calls, check instructions first, and always handle error results.
  • Capabilities such as network_access are opt-in. Keep extensions small, fail softly, and leave hard rules to Functions.

Next: Polaris and App Home Design