--- title: Block description: >- Use block targets to build general-purpose extensions which merchants can reposition using the checkout and accounts editor. Unlike static extension targets that render at fixed locations, block targets can be displayed across different areas of the Thank you page according to merchants' needs. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/checkout/block md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/checkout/block.md --- # Block Use block targets to build general-purpose extensions that merchants can reposition using the [checkout and accounts editor](https://help.shopify.com/en/manual/checkout-settings/customize-checkout-configurations/checkout-editor). ### Use cases * **Product upsell**: Read cart contents and display recommendations for complementary products that buyers can add at checkout. * **Trust badges**: Show security seals, money-back guarantees, or satisfaction badges to build buyer confidence. * **Loyalty program**: Display the buyer's loyalty points balance, and encourage checkout completion by showing how many points the current order would earn. * **Brand messaging**: Add custom banners that the merchant controls through the checkout and accounts editor to reflect their store's look and feel. * **Custom fields**: Collect additional information from buyers, such as gift-wrap preferences or delivery instructions, and store the data as [cart metafields](https://shopify.dev/docs/api/storefront/latest/mutations/cartmetafieldsset). ![Checkout page showing payment options (PayPal, Cash on Delivery) with two purchase.checkout.block.render target slots, one between the payment methods and the Remember me section and one near the discount code field.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-07/purchase.checkout.block.render-1ASRzz4U.png) *** ## Block target [Block targets](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets#block-extension-targets) can be displayed across different areas of checkout, unlike [static extension targets](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets#static-extension-targets), which render at fixed locations. ### Render block target `purchase.checkout.block.render` A block extension target that isn't tied to a specific checkout section or feature. Merchants control the placement using the [checkout and accounts editor](https://shopify.dev/docs/apps/checkout/test-ui-extensions#test-the-extension-in-the-checkout-editor). **Note:** During development, you can preview the target at different locations by [using a URL parameter](https://shopify.dev/docs/apps/checkout/best-practices/testing-ui-extensions#block-extension-targets). API properties provide read access to cart contents, buyer identity, and delivery details. To store custom data, use the [Metafields API](https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/metafields) to write cart [metafields](https://shopify.dev/docs/apps/build/checkout/metafields). Use [cart instructions](https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/cart-instructions) to check which mutations are available before making API calls. ### Support Components (55) APIs (24) ### Supported components * [Abbreviation](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/abbreviation) * [Badge](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/feedback-and-status-indicators/badge) * [Banner](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/feedback-and-status-indicators/banner) * [Box](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/box) * [Button](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/button) * [Checkbox](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/checkbox) * [Chip](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/chip) * [Choice list](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/choice-list) * [Clickable](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/clickable) * [Clickable chip](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/clickable-chip) * [Clipboard item](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/clipboard-item) * [Consent checkbox](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/consent-checkbox) * [Consent phone field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/consent-phone-field) * [Date field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/date-field) * [Date picker](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/date-picker) * [Details](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/details) * [Divider](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/divider) * [Drop zone](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/drop-zone) * [Email field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/email-field) * [Form](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/form) * [Grid](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/grid) * [Heading](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/heading) * [Icon](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/icon) * [Image](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/image) * [Link](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/link) * [Map](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/map) * [Modal](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/overlays/modal) * [Money field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/money-field) * [Number field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/number-field) * [Ordered list](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/ordered-list) * [Paragraph](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/paragraph) * [Password field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/password-field) * [Payment icon](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/payment-icon) * [Phone field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/phone-field) * [Popover](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/overlays/popover) * [Press button](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/actions/press-button) * [Product thumbnail](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/product-thumbnail) * [Progress](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/feedback-and-status-indicators/progress) * [Qr code](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/media-and-visuals/qr-code) * [Query container](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/query-container) * [Scroll box](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/scroll-box) * [Section](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/section) * [Select](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/select) * [Sheet](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/overlays/sheet) * [Skeleton paragraph](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/skeleton-paragraph) * [Spinner](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/feedback-and-status-indicators/spinner) * [Stack](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/layout-and-structure/stack) * [Switch](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/switch) * [Text](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/text) * [Text area](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/text-area) * [Text field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/text-field) * [Time](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/time) * [Tooltip](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/overlays/tooltip) * [Unordered list](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/typography-and-content/unordered-list) * [Url field](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/web-components/forms/url-field) ### Available APIs * [Addresses API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/addresses-api) * [Analytics API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/analytics-api) * [Attributes API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/attributes-api) * [Buyer Identity API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/buyer-identity-api) * [Buyer Journey API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/buyer-journey-api) * [Cart Instructions API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/cart-instructions-api) * [Cart Lines API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/cart-lines-api) * [Checkout Token API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/checkout-token-api) * [Cost API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/cost-api) * [Customer Privacy API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/customer-privacy-api) * [Delivery API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/delivery-api) * [Discounts API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/discounts-api) * [Extension API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/extension-api) * [Gift Cards API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/gift-cards-api) * [Localization API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/localization-api) * [Localized Fields API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/localized-fields-api) * [Metafields API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/metafields-api) * [Note API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/note-api) * [Payments API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/checkout-apis/payments-api) * [Session Token API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/session-token-api) * [Settings API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/settings-api) * [Shop API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/shop-api) * [Storage API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/storage-api) * [Storefront API](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/target-apis/platform-apis/storefront-api) Examples ### Examples * #### Add a gift wrap option ##### Description Let buyers request gift wrapping by toggling a checkbox that saves an order note. This example checks cart instructions to verify the note can be updated before rendering. ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const canUpdateNote = shopify.instructions.value.notes .canUpdateNote; if (!canUpdateNote) return null; return ( shopify.applyNoteChange({ type: 'updateNote', note: e.target.checked ? 'Gift wrap requested' : '', }) } > Add gift wrapping to this order ); } ``` * #### Add a free sample for large orders ##### Description Offer a free product sample when the cart exceeds a spending threshold. This example checks \`shopify.instructions\` for cart line permissions and uses \`shopify.applyCartLinesChange\` to add a variant. ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useState} from 'preact/hooks'; export default function extension() { render(, document.body); } const SAMPLE_VARIANT_ID = 'gid://shopify/ProductVariant/1234567890'; const MINIMUM_AMOUNT = 50; function Extension() { const [added, setAdded] = useState(false); const canAdd = shopify.instructions.value.lines .canAddCartLine; const subtotal = shopify.cost.subtotalAmount.value; if ( !canAdd || subtotal.amount < MINIMUM_AMOUNT || added ) { return null; } async function handleAdd() { const result = await shopify.applyCartLinesChange({ type: 'addCartLine', merchandiseId: SAMPLE_VARIANT_ID, quantity: 1, }); if (result.type === 'success') { setAdded(true); } } return ( Orders over {subtotal.currencyCode}{' '} {MINIMUM_AMOUNT} qualify for a free product sample. Add free sample ); } ``` *** ## Best practices * **Design for flexible placement**: The merchant controls where block extensions appear, so avoid assumptions about surrounding content. Test the extension in multiple [supported locations](https://shopify.dev/docs/apps/build/checkout/test-checkout-ui-extensions#block-extension-targets) to confirm it renders well in each. *** ## Placement references During development, preview each supported placement by appending `?placement-reference={name}` to the checkout URL printed by [Shopify CLI](https://shopify.dev/docs/api/shopify-cli). For example, `?placement-reference=INFORMATION1` previews the extension above the contact information section. You can also set `default_placement` in your extension's [TOML configuration file](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions#checkout-ui-extensions) to recommend an initial placement to merchants in the [checkout and accounts editor](https://shopify.dev/docs/apps/build/checkout/test-checkout-ui-extensions#test-the-extension-in-the-checkout-editor). ### Multi-page checkout | Reference | Location | | - | - | | `WALLETS1` | Above the express checkout buttons (Shop Pay, Apple Pay, and Google Pay). Disabled when express checkout isn't shown. | | `INFORMATION1` | Above the contact information section, as the first element on the **Information** step. | | `INFORMATION2` | Below the contact information section and its `purchase.checkout.contact.render-after` static extensions, above the shipping or delivery address. | | `INFORMATION3` | Below the delivery method selector. Renders in place of the delivery method selector when shipping isn't required (for example, for digital goods). | | `DELIVERY1` | Above the shipping methods section, as the first element on the **Shipping** step. | | `DELIVERY2` | Below the shipping methods section. | | `PAYMENT1` | Above the payment section, as the first element on the **Payment** step (before error banners, tips, and payment methods). | | `ORDER_SUMMARY1` | Above the line items in the order summary sidebar. | | `ORDER_SUMMARY2` | Below the line items in the order summary sidebar, after the `purchase.checkout.cart-line-list.render-after` static target. | | `ORDER_SUMMARY3` | Above the money lines (subtotal, shipping, taxes, and total) in the order summary sidebar. | | `ORDER_SUMMARY4` | Below the money lines in the order summary sidebar. | `PAYMENT2`, `PAYMENT3`, and `PAYMENT4` shift depending on whether tips are enabled: | Reference | With tips enabled | Without tips | | - | - | - | | `PAYMENT2` | After the tips section. | After payment methods and gift card redemption. | | `PAYMENT3` | After payment methods and gift card redemption. | After the billing address selector. | | `PAYMENT4` | After the billing address selector. | After the Remember me section. | ### One-page checkout Placement behavior changes in one-page checkout: * `INFORMATION3` is disabled. * `DELIVERY2` is disabled and swaps to the nearest valid placement. * `DELIVERY1` renders after the delivery methods section instead of before it. * `PAYMENT3` and `PAYMENT4` might be disabled depending on tip payments and shipping requirements. * `ORDER_SUMMARY4` renders below the **Pay** button on mobile only. ***