Adding a custom delivery message with a checkout UI extension

Checkout UI extensions let you inject your own UI into Shopify's checkout page without touching the checkout template itself. Rather than forking checkout.liquid — a path that disqualifies you from future Shopify checkout improvements — you write a typed, sandboxed extension that Shopify renders inside the checkout. In this tutorial you'll build an extension that reads the delivery groups from the checkout and displays a custom message when an order contains perishable items that need expedited shipping.

What you'll build

A checkout UI extension that mounts in the purchase.checkout.delivery-address.render-before extension point, inspects the cart line items for products tagged 'perishable', and if found, renders a Banner component with a message telling the customer that their order will be shipped refrigerated and must be received within 24 hours of delivery.

Before you start

• Shopify CLI 3.x installed globally (npm install -g @shopify/cli)
• A Shopify development store with checkout extensibility enabled (Checkout.liquid-free, or a store on the Shopify Plus plan)
• Node.js 18+ and a Shopify Partner account with a connected app
• At least one product tagged 'perishable' in your development store

# Inside your existing Shopify app directory
shopify app generate extension

# When prompted:
# Extension type: Checkout UI
# Name: perishable-delivery-message
# Language: TypeScript React

# extensions/perishable-delivery-message/shopify.extension.toml

api_version = "2024-04"

[[extensions]]
type = "ui_extension"
name = "Perishable Delivery Message"
handle = "perishable-delivery-message"

[[extensions.targeting]]
module = "./src/Checkout.tsx"
target = "purchase.checkout.delivery-address.render-before"

import {
  useCartLines,
  Banner,
  Text,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.delivery-address.render-before',
  () => <PerishableMessage />
);

function PerishableMessage() {
  const lines = useCartLines();

  // Check each line for a metafield indicating it's perishable
  const hasPerishable = lines.some((line) => {
    const meta = line.merchandise.metafield({
      namespace: 'custom',
      key: 'perishable',
    });
    return meta?.value === 'true';
  });

  if (!hasPerishable) return null;

  return (
    <Banner status="warning">
      <Text>
        Your order contains perishable items and will be shipped refrigerated.
        Please ensure someone is available to receive the package within 24 hours
        of the estimated delivery date.
      </Text>
    </Banner>
  );
}

import {
  Banner,
  BlockStack,
  Heading,
  Text,
  Icon,
  InlineStack,
} from '@shopify/ui-extensions-react/checkout';

function PerishableBanner() {
  return (
    <Banner status="warning">
      <BlockStack spacing="tight">
        <InlineStack spacing="tight">
          <Icon source="truck" />
          <Heading level={3}>Refrigerated shipping required</Heading>
        </InlineStack>
        <Text>
          This order contains perishable goods. Our cold-chain courier will
          deliver between 8 am – 6 pm. Ensure someone is home to receive the
          package.
        </Text>
      </BlockStack>
    </Banner>
  );
}

cd your-app-directory
shopify app dev

# The CLI will output a preview URL like:
# Preview URL: https://your-store.myshopify.com/cart/add?id=...&return_to=...

shopify app deploy

# Confirm the prompts. You'll see:
# ✓ perishable-delivery-message deployed to partner dashboard
# Version created: 1.0.0

What's next

Checkout UI extensions are capable of much more than banners. You can use useApplyCartLinesChange to add upsell products, useApplyAttributeChange to tag the order with custom attributes, and useShippingAddress to read or pre-fill address fields. The full extension API reference is at shopify.dev/docs/api/checkout-ui-extensions.

For more complex conditional logic — like showing different messages based on the selected shipping rate — look into the useDeliveryGroups hook. It exposes the selected delivery option, delivery strategy (ship, pickup, local delivery), and estimated delivery range, giving you everything you need to tailor the checkout experience to the actual fulfillment path.

Performance considerations for checkout extensions

Shopify measures and enforces performance budgets for checkout UI extensions. Your extension's JavaScript bundle must be under 10KB gzipped, and it must render within 50ms of being called. These constraints exist because checkout performance directly impacts conversion rates — Shopify's data shows that each additional 100ms of checkout load time reduces conversion by approximately 0.3%.

Keep your extension bundle small by avoiding large third-party libraries. All the UI primitives you need (Banner, Text, BlockStack, InlineStack, Icon, Button) are imported from @shopify/ui-extensions-react/checkout, which is provided by the Shopify host and doesn't count against your bundle size. Only code you write yourself or third-party packages you import count against the 10KB limit. The Shopify CLI will warn you if your extension bundle exceeds the limit when you run shopify app build.

Testing across checkout themes

Checkout UI components inherit the merchant's checkout branding — fonts, colors, button styles, and corner radius settings defined in the checkout editor. This means your extension will look different on a store with a dark theme versus one with a light theme. Test your extension against multiple theme configurations before submitting. In the Shopify CLI preview mode, you can switch between stored checkout profiles in the checkout editor to verify your extension renders correctly in each configuration.

One common rendering gotcha: if a merchant has set their checkout's accent color to a dark hue and your Banner uses status='warning' (which is typically yellow), the contrast between yellow text and a dark background may be insufficient for WCAG compliance. The Polaris checkout components handle this automatically by adjusting their contrast ratios based on the host's color scheme — another reason to use the provided components rather than custom divs with hardcoded color values.