Shopify Checkout Extensions

Shopify Checkout Extensions

Overview

Shopify Checkout Extensions allow apps to render custom UI blocks inside Shopify's checkout without forking the checkout template. Shopify Functions let you replace backend logic — discounts, shipping, payment methods, and order validation — with custom WebAssembly modules that run inside Shopify's infrastructure. Together they replace the deprecated checkout.liquid customization approach and work with both Shopify Plus and non-Plus stores (UI extensions) or Plus-only (some Functions targets).

When to Use This Skill

• When adding custom UI blocks to checkout (upsells, trust badges, gift message fields, warranty options)
• When implementing custom discount logic beyond native Shopify discount rules (e.g., tiered discounts, B2B pricing)
• When creating custom shipping method filtering or renaming based on cart contents
• When building payment customization to hide/rename payment methods for specific customers
• When validating order contents before checkout completes (e.g., quantity limits, region restrictions)
• When replacing deprecated checkout.liquid customizations for Shopify Plus stores

Core Instructions

1. Scaffold an extension with Shopify CLI

   # Inside an existing Shopify app directory
   shopify app generate extension
   # Choose: Checkout UI extension OR Shopify Function
   # Name: my-checkout-extension

This creates an extensions/my-checkout-extension/ directory with src/index.tsx (UI) or src/index.ts (Function).

2. Build a Checkout UI extension

Checkout UI extensions use a React-like component API from @shopify/ui-extensions-react/checkout:

   // extensions/order-upsell/src/index.tsx
   import {
     reactExtension,
     useCartLines,
     useApplyCartLinesChange,
     useSettings,
     BlockStack,
     Button,
     Image,
     Text,
     InlineStack,
     Divider,
   } from "@shopify/ui-extensions-react/checkout";

   const CheckoutBlock = reactExtension(
     "purchase.checkout.block.render",
     () => <OrderUpsell />
   );
   export { CheckoutBlock };

   function OrderUpsell() {
     const cartLines = useCartLines();
     const applyCartLinesChange = useApplyCartLinesChange();
     const { upsell_variant_id: upsellVariantId } = useSettings();

     // Only show upsell if a variant is configured and cart doesn't already contain it
     if (!upsellVariantId) return null;

     const alreadyInCart = cartLines.some(
       (line) => line.merchandise.id === upsellVariantId
     );

     if (alreadyInCart) return null;

     const handleAddUpsell = async () => {
       await applyCartLinesChange({
         type: "addCartLine",
         merchandiseId: upsellVariantId,
         quantity: 1,
       });
     };

     return (
       <BlockStack spacing="base">
         <Divider />
         <InlineStack blockAlignment="center" spacing="base">
           <Image source="https://cdn.shopify.com/s/files/..." aspectRatio={1} />
           <BlockStack>
             <Text emphasis="bold">Add a gift bag for $3.99</Text>
             <Text appearance="subdued">Beautiful packaging for your order</Text>
           </BlockStack>
           <Button onPress={handleAddUpsell}>Add</Button>
         </InlineStack>
       </BlockStack>
     );
   }

3. Configure the extension in `shopify.extension.toml`

   api_version = "2025-01"

   [[extensions]]
   type = "ui_extension"
   name = "Order Upsell"
   handle = "order-upsell"

   [[extensions.targeting]]
   module = "./src/index.tsx"
   target = "purchase.checkout.block.render"

   [extensions.settings]
   [[extensions.settings.fields]]
   key = "upsell_variant_id"
   type = "variant_reference"
   name = "Upsell Product Variant"

4. Build a Shopify Function for custom discounts

Shopify Functions compile to WebAssembly. Use Rust or JavaScript:

   // extensions/volume-discount/src/index.ts
   import type {
     RunInput,
     FunctionRunResult,
     CartLineInput,
   } from "../generated/api";

   const NO_CHANGES: FunctionRunResult = { discounts: [], discountApplicationStrategy: "FIRST" };

   export function run(input: RunInput): FunctionRunResult {
     const { cart } = input;

     // Calculate total quantity across all lines
     const totalQuantity = cart.lines.reduce(
       (sum, line) => sum + line.quantity,
       0
     );

     // Tiered volume discount
     let discountPercent = 0;
     if (totalQuantity >= 20) discountPercent = 20;
     else if (totalQuantity >= 10) discountPercent = 10;
     else if (totalQuantity >= 5) discountPercent = 5;

     if (discountPercent === 0) return NO_CHANGES;

     return {
       discounts: [
         {
           value: {
             percentage: { value: discountPercent.toString() },
           },
           targets: [{ orderSubtotal: { excludedVariantIds: [] } }],
           message: `${discountPercent}% volume discount (${totalQuantity} items)`,
         },
       ],
       discountApplicationStrategy: "FIRST",
     };
   }

Function shopify.extension.toml:

   api_version = "2025-01"

   [[extensions]]
   type = "function"
   name = "Volume Discount"
   handle = "volume-discount"
   runtime = "javascript"

   [[extensions.input.variables]]
   name = "cart"
   type = "Cart"

   [extensions.build]
   command = "npm run build"
   path = "dist/index.wasm"

5. Test and deploy extensions

   # Run local dev preview (UI extension hot-reloads in checkout)
   shopify app dev
   # Open the checkout preview URL shown in terminal

   # Deploy all extensions to Shopify
   shopify app deploy

After deploying, go to Admin → Checkout → Customize to add the UI extension block to a checkout template. Functions are activated by creating a discount with the function from Admin → Discounts.

Examples

Gift message field using useApplyMetafieldsChange

import {
  reactExtension,
  TextField,
  useApplyMetafieldsChange,
  useMetafield,
  BlockStack,
  Text,
} from "@shopify/ui-extensions-react/checkout";

export default reactExtension(
  "purchase.checkout.shipping-option-list.render-after",
  () => <GiftMessage />
);

function GiftMessage() {
  const giftMessage = useMetafield({ namespace: "custom", key: "gift_message" });
  const applyMetafieldsChange = useApplyMetafieldsChange();

  return (
    <BlockStack spacing="tight">
      <Text emphasis="bold">Gift message (optional)</Text>
      <TextField
        label="Message"
        value={giftMessage?.value ?? ""}
        multiline={3}
        onChange={(value) =>
          applyMetafieldsChange({
            type: "updateMetafield",
            namespace: "custom",
            key: "gift_message",
            valueType: "string",
            value,
          })
        }
      />
    </BlockStack>
  );
}

Payment customization Function (hide cash on delivery for international orders)

// extensions/payment-customization/src/index.ts
import type { RunInput, FunctionRunResult } from "../generated/api";

export function run(input: RunInput): FunctionRunResult {
  const country = input.cart.buyerIdentity?.countryCode;

  // Hide "Cash on Delivery" for non-domestic orders
  const hideOperations = input.paymentMethods
    .filter((pm) => pm.name.toLowerCase().includes("cash on delivery") && country !== "US")
    .map((pm) => ({
      hide: { paymentMethodId: pm.id },
    }));

  return { operations: hideOperations };
}

Best Practices

• Use the `purchase.checkout.block.render` target for maximum placement flexibility — merchants can drag the block anywhere in the checkout editor
• Keep Function execution under 5ms — Shopify enforces a strict execution time limit; avoid network calls inside Functions (use metafields or Function input variables for configuration)
• Use `useSettings()` hook to read merchant-configured values from the extension settings schema — avoids hardcoded IDs in extension code
• Never read DOM or use browser APIs in UI extensions — they run in a sandboxed Worker environment without DOM access
• Use `@shopify/ui-extensions-react/checkout` components only — native HTML and other UI libraries are not available in the extension sandbox
• Test payment and shipping Functions with real checkout sessions — the local dev preview only works for UI extensions; Functions need to be deployed to test
• Version-pin your extension API version — increment the api_version in shopify.extension.toml to access new APIs while keeping backward compatibility
• Handle async operations with loading states — useApplyCartLinesChange is async; show a spinner while the mutation is in flight

Common Pitfalls

Related Skills

• @shopify-app-development
• @shopify-storefront-api
• @shopify-metafields
• @checkout-flow-optimization
• @shopify-admin-api

Order Notes Checkout Extension

Problem/Feature Description

A gifting marketplace wants to let customers add a personal message to their order during checkout. The message should be saved alongside the order so that the fulfillment team can print it on the packing slip. Customers who return to the checkout after navigating away should see their previously entered message still populated in the field.

The marketplace uses Shopify and needs a Checkout UI extension that renders a text input in the checkout flow, after the shipping options section. Whatever the customer types must be persisted to the order using Shopify's standard persistence mechanism for extensions, and it must be pre-populated on re-render if data was already entered.

The team wants this built as a standalone extension with its configuration file, ready to be added to an existing Shopify app.

Output Specification

Produce the following files:

• extensions/order-notes/src/index.tsx — the extension source code
• extensions/order-notes/shopify.extension.toml — the extension configuration

Do not create a full Shopify app scaffold — just these two files as if they were part of an existing app.

Warranty Upsell Block for Checkout

Problem/Feature Description

A Shopify app agency is building a warranty upsell app for e-commerce merchants. The app needs to display a warranty add-on offer inside the Shopify checkout — merchants want to offer customers an optional warranty product alongside their main purchase. Critically, different merchants sell different warranty products, so the specific warranty product variant must be configurable per merchant through the Shopify Admin rather than being baked into the app's code.

The team needs a Checkout UI extension that renders the warranty upsell offer. When the customer clicks to add the warranty, the extension should add it to the cart. The UI must not flicker or allow double-clicks during the add operation. The extension should only display the offer when the warranty item is not already in the cart.

Output Specification

Produce the following files representing the extension source code and configuration:

• extensions/warranty-upsell/src/index.tsx — the React extension source code
• extensions/warranty-upsell/shopify.extension.toml — the extension configuration file

Do not create a full Shopify app scaffold — just write these two files as if they were part of an existing app.

Tiered B2B Discount Function

Problem/Feature Description

A B2B wholesale supplier has been using Shopify Plus and wants to implement automatic tiered pricing for bulk orders. Their requirement is simple: buyers who add 5 or more units to their cart get a 5% discount, 10+ units get 10%, and 20+ units get 15%. Native Shopify discount rules can't handle quantity-based tiers automatically — each order needs to be evaluated at checkout.

The engineering team has decided to implement this as a Shopify Function so discounts apply instantly during checkout without any manual coupon codes. The Function must be production-ready: it needs to perform well within Shopify's runtime constraints and be configured correctly so it can be deployed and activated. The team is unfamiliar with the Shopify Functions runtime and wants clear documentation of the deployment and activation steps alongside the code.

Output Specification

Produce the following files:

• extensions/b2b-tiered-discount/src/index.ts — the Function source code in TypeScript/JavaScript
• extensions/b2b-tiered-discount/shopify.extension.toml — the Function configuration
• DEPLOYMENT.md — a brief document describing the steps required to deploy this Function and make it active on a store, including what admin section to use and what action to take after deployment

Do not create a full Shopify app scaffold — just these three files as if they were part of an existing app.