finsilabs/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

| Problem | Solution | |---------|----------| | Extension not appearing in checkout editor | Ensure the extension is deployed (shopify app deploy) and the correct checkout template is selected in Admin → Checkout | | Function returns FUNCTION_EXECUTION_TIMEOUT | Move configuration out of runtime logic into Function input metafields; avoid complex loops on large catalogs | | useCartLines returns stale data after cart update | Use the returned promise from applyCartLinesChange to wait for checkout to re-evaluate before reading cart lines again | | Extension crashes with "Cannot use browser APIs" | Remove document, window, localStorage references — the extension runs in a Worker sandbox | | Discount Function not applying | Verify the Function-based discount is active in Admin → Discounts and the customer qualifies per any eligibility rules | | Checkout UI extension settings not saving | Settings fields require handle values that match the keys referenced by useSettings() in the extension code |

Related Skills

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