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>
     );
   }