Checkout Extensions

Overview

Checkout extensions let you add custom UI components to the checkout process. Display delivery estimates, upsells, custom fields, payment options, and more.

Extension Points

Checkout extensions can appear in multiple locations:

Delivery

purchase.checkout.delivery-address.render-afterShow shipping estimates, delivery dates, or custom shipping options

Payment

purchase.checkout.payment-method-list.render-afterAdd payment instructions, installment options, or trust badges

Cart Line

purchase.checkout.cart-line-item.render-afterDisplay product details, warranties, or customization options

Block

purchase.checkout.block.renderFull-width custom content anywhere in checkout

Example: Delivery Estimate

Generate a checkout extension that shows delivery estimates:

Describe Your Extension

Create a checkout extension that displays estimated delivery 
dates based on the customer's shipping address. Show a calendar 
icon and format like "Estimated delivery: Nov 5-8, 2025"

Review Generated Code

Synapse generates a complete extension with:

React component with Shopify UI components
GraphQL queries for shipping address
Date calculation logic
Proper styling and icons

Validate & Deploy

MCP validation ensures all APIs are correct
Automatic deployment to your dev store
Available in checkout editor immediately

Configure in Checkout

Go to Settings → Checkout → Customize
Find your extension in the left sidebar
Drag to desired location
Configure settings and save

Generated Extension Structure

extensions/delivery-estimate/
├── src/
│   ├── Checkout.tsx           # Main component
│   ├── Checkout.test.tsx      # Tests
│   └── run.graphql           # GraphQL queries
├── locales/
│   └── en.default.json       # Translations
├── shopify.extension.toml    # Config
└── package.json

Main Component

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

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

function Extension() {
  const address = useShippingAddress();
  
  const deliveryDate = calculateDeliveryDate(address);
  
  return (
    <Banner title="Estimated Delivery">
      <Icon source="delivery" />
      <Text>
        {deliveryDate.start} - {deliveryDate.end}
      </Text>
    </Banner>
  );
}

Common Checkout Patterns

Delivery Estimate
Upsell
Custom Field
Trust Badge

Use Case: Show when items will arriveTarget: purchase.checkout.delivery-address.render-afterFeatures:

Calculate based on address
Show date range
Handle holidays/weekends
Display transit time

Prompt Example:

"Show estimated delivery dates after the shipping address. 
Calculate 3-5 business days from today, display with a 
calendar icon"

Available UI Components

Synapse generates code using Shopify’s UI components:

Layout Components

<BlockStack> - Vertical layout
<InlineLayout> - Horizontal layout
<Grid> - Grid layout
<Divider> - Section dividers
<View> - Generic container

Content Components

<Text> - Styled text
<Heading> - Section headings
<Image> - Product/brand images
<Icon> - Built-in icons
<Banner> - Info/warning messages

Form Components

<TextField> - Text input
<Checkbox> - Checkboxes
<Select> - Dropdowns
<Button> - Action buttons
<Form> - Form container

Data Hooks

useShippingAddress() - Get shipping info
useCartLines() - Access cart items
useApplyMetafieldsChange() - Save data
useApplyCartLinesChange() - Modify cart
useSettings() - Extension settings

Best Practices

Performance

Minimize Re-renders: Use React.memo for expensive components
Lazy Load: Don’t fetch data until needed
Cache Results: Store calculated values
Small Bundle: Keep dependencies minimal

UX Guidelines

Clear Messaging: Be explicit about what you’re showing
Mobile-First: Checkout is 70%+ mobile
Loading States: Show skeleton loaders
Error Handling: Gracefully handle failures

Validation

Synapse ensures your extension:

✅ Uses valid extension targets
✅ Only calls allowed APIs
✅ Follows Shopify’s UI guidelines
✅ Has proper error handling
✅ Includes TypeScript types

Advanced Features

Metafields

Store custom data on orders:

const applyMetafields = useApplyMetafieldsChange();

applyMetafields({
  type: "updateMetafield",
  namespace: "custom",
  key: "gift_message",
  valueType: "string",
  value: message
});

Cart Modifications

Add/remove items programmatically:

const applyCartLines = useApplyCartLinesChange();

applyCartLines({
  type: "addCartLine",
  merchandiseId: "gid://...",
  quantity: 1
});

Conditional Display

Show/hide based on conditions:

const lines = useCartLines();
const total = lines.reduce(
  (sum, line) => sum + line.cost.totalAmount,
  0
);

if (total < 50) return null;

Settings

Make extensions configurable:

const settings = useSettings();
const threshold = settings.threshold || 100;
const message = settings.message;

Example Prompts

Get started with these prompts:

Free Shipping Progress Bar

Create a checkout extension that shows a progress bar 
indicating how much more the customer needs to spend 
to get free shipping. The threshold is $50. Display 
like "Add $15 more for free shipping!" with a visual 
progress bar.

Product Protection Offer

Add a checkbox after cart items that lets customers 
add product protection for $9.99. When checked, add 
the protection as a cart line item. Show a shield icon 
and list of benefits (accidental damage, 2-year warranty).

Personalization Field

Create a text input field where customers can enter 
a name or message to be engraved on their product. 
Validate that it's under 30 characters. Save to order 
metafields. Show character counter and preview.

Sustainable Shipping Option

After the shipping address, show an option to add 
carbon-neutral shipping for $2. Explain it offsets 
the carbon footprint of delivery. Use a leaf icon. 
Add as cart line item when selected.

Testing Your Extension

Local Testing

Extensions deploy automatically, but you can test locally:

cd extensions/your-extension
npm run dev

Preview in Checkout

Open your dev store
Add items to cart
Go to checkout
See your extension in action

Test Different Scenarios

Empty cart
Single item vs multiple items
Different shipping addresses
Various cart totals
Mobile vs desktop

Validate Behavior

Data saves correctly
Loading states work
Errors are handled
Performance is good

Troubleshooting

Extension Not Showing

Causes:

Not added to checkout editor
Extension target doesn’t match checkout flow
Conditional logic hiding it

Solutions:

Check Settings → Checkout → Customize
Verify extension target in shopify.extension.toml
Review conditional rendering logic
Check browser console for errors

Data Not Saving

Causes:

Metafield namespace/key conflicts
Missing permissions
Validation errors

Solutions:

Use unique namespace (e.g., “custom”)
Check metafield definitions
Review error messages in console
Verify applyMetafieldsChange syntax

Styling Issues

Causes:

Custom CSS not supported
Component props incorrect
Theme conflicts

Solutions:

Use Shopify UI component props only
Check component documentation
Test in different themes
Avoid custom CSS

Next Steps

Extension Standards

Learn Shopify’s quality guidelines

Admin Extensions

Build admin panel extensions

Functions

Add backend logic with Shopify Functions

Debugging

Debug and troubleshoot extensions

Get Started

Core Concepts

Building Extensions

Building Functions

Development

Deployment

Advanced

Checkout Extensions

Overview

Extension Points

Delivery

Payment

Cart Line

Block

Example: Delivery Estimate

Generated Extension Structure

Main Component

Common Checkout Patterns

Available UI Components

Best Practices

Performance

UX Guidelines

Validation

Advanced Features

Metafields

Cart Modifications

Conditional Display

Settings

Example Prompts

Testing Your Extension

Troubleshooting

Next Steps

Extension Standards

Admin Extensions

Functions

Debugging

Get Started

Core Concepts

Building Extensions

Building Functions

Development

Deployment

Advanced

​Overview

​Extension Points

Delivery

Payment

Cart Line

Block

​Example: Delivery Estimate

​Generated Extension Structure

​Main Component

​Common Checkout Patterns

​Available UI Components

​Best Practices

​Performance

​UX Guidelines

​Validation

​Advanced Features

Metafields

Cart Modifications

Conditional Display

Settings

​Example Prompts

​Testing Your Extension

​Troubleshooting

​Next Steps

Extension Standards

Admin Extensions

Functions

Debugging

Overview

Extension Points

Example: Delivery Estimate

Generated Extension Structure

Main Component

Common Checkout Patterns

Available UI Components

Best Practices

Performance

UX Guidelines

Validation

Advanced Features

Example Prompts

Testing Your Extension

Troubleshooting

Next Steps