> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsebuilder.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Checkout Extensions
> Build custom checkout UI extensions with Synapse
## 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:
**purchase.checkout.delivery-address.render-after**
Show shipping estimates, delivery dates, or custom shipping options
**purchase.checkout.payment-method-list.render-after**
Add payment instructions, installment options, or trust badges
**purchase.checkout.cart-line-item.render-after**
Display product details, warranties, or customization options
**purchase.checkout.block.render**
Full-width custom content anywhere in checkout
## Example: Delivery Estimate
Generate a checkout extension that shows delivery estimates:
```
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"
```
Synapse generates a complete extension with:
* React component with Shopify UI components
* GraphQL queries for shipping address
* Date calculation logic
* Proper styling and icons
* MCP validation ensures all APIs are correct
* Automatic deployment to your dev store
* Available in checkout editor immediately
1. Go to Settings → Checkout → Customize
2. Find your extension in the left sidebar
3. Drag to desired location
4. 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
```tsx theme={null}
import {
reactExtension,
Banner,
Text,
Icon,
useShippingAddress,
} from '@shopify/ui-extensions-react/checkout';
export default reactExtension(
'purchase.checkout.delivery-address.render-after',
() =>
);
function Extension() {
const address = useShippingAddress();
const deliveryDate = calculateDeliveryDate(address);
return (
{deliveryDate.start} - {deliveryDate.end}
);
}
```
## Common Checkout Patterns
**Use Case:** Show when items will arrive
**Target:** `purchase.checkout.delivery-address.render-after`
**Features:**
* 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"
```
**Use Case:** Recommend additional products
**Target:** `purchase.checkout.cart-line-item.render-after`
**Features:**
* Product recommendations
* "Frequently bought together"
* Add to cart button
* Image and pricing
**Prompt Example:**
```
"After each cart item, suggest related products that pair
well with it. Show product image, title, price, and an
'Add' button"
```
**Use Case:** Collect additional information
**Target:** `purchase.checkout.block.render`
**Features:**
* Text input fields
* Validation
* Save to order metafields
* Optional/required
**Prompt Example:**
```
"Add a gift message field where customers can enter a
personalized message. Save to order metafields. Include
character counter (max 200 chars)"
```
**Use Case:** Build customer confidence
**Target:** `purchase.checkout.payment-method-list.render-after`
**Features:**
* Security badges
* Money-back guarantee
* Free returns info
* Customer reviews
**Prompt Example:**
```
"Show security badges after payment methods including
SSL encryption, money-back guarantee, and trusted by
50,000+ customers"
```
## Available UI Components
Synapse generates code using Shopify's UI components:
* `` - Vertical layout
* `` - Horizontal layout
* `` - Grid layout
* `` - Section dividers
* `` - Generic container
* `` - Styled text
* `` - Section headings
* `` - Product/brand images
* `` - Built-in icons
* `` - Info/warning messages
* `` - Text input
* `` - Checkboxes
* `
* `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
Store custom data on orders:
```tsx theme={null}
const applyMetafields = useApplyMetafieldsChange();
applyMetafields({
type: "updateMetafield",
namespace: "custom",
key: "gift_message",
valueType: "string",
value: message
});
```
Add/remove items programmatically:
```tsx theme={null}
const applyCartLines = useApplyCartLinesChange();
applyCartLines({
type: "addCartLine",
merchandiseId: "gid://...",
quantity: 1
});
```
Show/hide based on conditions:
```tsx theme={null}
const lines = useCartLines();
const total = lines.reduce(
(sum, line) => sum + line.cost.totalAmount,
0
);
if (total < 50) return null;
```
Make extensions configurable:
```tsx theme={null}
const settings = useSettings();
const threshold = settings.threshold || 100;
const message = settings.message;
```
## Example Prompts
Get started with these prompts:
```
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.
```
```
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).
```
```
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.
```
```
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
Extensions deploy automatically, but you can test locally:
```bash theme={null}
cd extensions/your-extension
npm run dev
```
1. Open your dev store
2. Add items to cart
3. Go to checkout
4. See your extension in action
* Empty cart
* Single item vs multiple items
* Different shipping addresses
* Various cart totals
* Mobile vs desktop
* Data saves correctly
* Loading states work
* Errors are handled
* Performance is good
## Troubleshooting
**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
**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
**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
Learn Shopify's quality guidelines
Build admin panel extensions
Add backend logic with Shopify Functions
Debug and troubleshoot extensions