Add a custom UI block to Shopify checkout using a Checkout UI Extension at the purchase.checkout.block.render target
domain: shopify.dev · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Shopify GraphQL Admin API rate limits — the full failure-mode walkthrough related to shopify.dev, checked against official docs, with linked verified routes.
Steps
Scaffold an extension with the Shopify CLI: shopify app generate extension --type checkout_ui_extension; this creates a shopify.extension.toml and src/Checkout.tsx
In shopify.extension.toml, set the target to purchase.checkout.block.render under [[extensions.targeting]]; this is a block target that merchants position in the checkout editor
In the extension code, use useSettings() from @shopify/ui-extensions-react/checkout to expose merchant-configurable settings defined in the toml's [extensions.settings] section
Use reactExtension('purchase.checkout.block.render', () => <App />) as the extension entry point; render components from @shopify/ui-extensions-react/checkout such as BlockStack, Text, and Banner
Deploy the extension with shopify app deploy and activate it in the Shopify checkout editor (Settings > Checkout > Customize) by dragging the block to the desired position
For Shopify Plus stores, extensions can also be placed in the information, shipping, and payment steps using static targets like purchase.checkout.shipping-option-list.render-after
Known gotchas
Checkout UI Extensions for information, shipping, and payment steps are only available to Shopify Plus merchants; standard plan merchants can only use block targets and post-purchase extensions
checkout.liquid was fully sunset — it is no longer available as a customization mechanism for any Shopify plan; all checkout customization now requires Checkout UI Extensions or Shopify Functions
Extension code runs in a sandboxed Web Worker with no DOM access and a restricted JavaScript API surface — direct window, document, or fetch calls are not allowed; use the checkout extension API hooks instead
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?