Shopify CLI: How to Create a Customer Account UI Extension

Customer Account UI Extensions let you add custom React components directly into Shopify’s native customer account interface — the order history page, order detail page, profile page, and more. No Liquid hacks, no iframes, just first-class extensions that feel native to the Shopify experience.

This guide walks through the full workflow: CLI setup, creating the extension scaffold, writing components with the customer-account-ui-extensions library, local dev preview, and deployment.

• Node.js 18+ and npm/pnpm
• Shopify CLI 3.x: npm install -g @shopify/cli
• A Shopify Partner account and a development store
• A Shopify app (existing or new) — extensions live inside apps

Create a new app (if needed)

shopify app init my-customer-app
cd my-customer-app

Select your preferred language (JavaScript/TypeScript) and template (Remix is recommended for new apps).

Generate the Customer Account UI Extension

shopify app generate extension

Select Customer account UI from the extension type list. Give it a name like loyalty-dashboard. Select JavaScript or TypeScript.

After generation, your extension lives at extensions/loyalty-dashboard/ with this structure:

extensions/loyalty-dashboard/
├── shopify.extension.toml    # Extension configuration
├── src/
│   └── CustomerAccountBlock.tsx  # Main extension component
├── package.json
└── tsconfig.json

name = "Loyalty Dashboard"
handle = "loyalty-dashboard"
type = "ui_extension"

[[extensions.targeting]]
module = "./src/CustomerAccountBlock.tsx"
target = "customer-account.order-index.block.render"

[settings]
  [[settings.fields]]
  key = "loyalty_api_url"
  type = "single_line_text_field"
  name = "Loyalty API URL"

Extensions use the @shopify/ui-extensions-react/customer-account package for components. These are Shopify’s own UI primitives — not HTML elements:

// src/CustomerAccountBlock.tsx
import {
  reactExtension,
  useApi,
  BlockStack,
  InlineStack,
  Text,
  Button,
  Divider,
  SkeletonText,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.order-index.block.render',
  () => <LoyaltyDashboard />
);

function LoyaltyDashboard() {
  const { customer } = useApi();
  const [points, setPoints] = React.useState<number | null>(null);
  const [loading, setLoading] = React.useState(true);

  React.useEffect(() => {
    // Fetch loyalty points from your backend
    customer.id.then(async (customerId) => {
      const response = await fetch(
        `https://your-app.myshopify.com/loyalty/${customerId}`
      );
      const data = await response.json();
      setPoints(data.points);
      setLoading(false);
    });
  }, []);

  if (loading) {
    return (
      <BlockStack spacing="base">
        <SkeletonText />
        <SkeletonText />
      </BlockStack>
    );
  }

  return (
    <BlockStack spacing="base" border="base" cornerRadius="base" padding="base">
      <Text size="large" emphasis="bold">Your Loyalty Points</Text>
      <Divider />
      <InlineStack spacing="base" blockAlignment="center">
        <Text size="extraLarge" emphasis="bold">{points}</Text>
        <Text tone="subdued">points available</Text>
      </InlineStack>
      <Button to="/loyalty">View Rewards</Button>
    </BlockStack>
  );
}

Choose where your extension renders by setting the target in your TOML:

• customer-account.order-index.block.render — on the order list page
• customer-account.order-status.block.render — on the order detail/status page
• customer-account.profile.block.render — on the customer profile page
• customer-account.page.render — render a full custom page (accessed via navigation link)

You can target multiple locations by adding multiple [[extensions.targeting]] blocks in your TOML.

The useApi() hook exposes customer context and app utilities:

const {
  customer,           // Customer ID, email, tags
  orders,             // Order list data
  navigation,         // Navigate between pages
  storage,            // Local storage for the extension
  settings,           // Settings fields from shopify.extension.toml
  i18n,               // Internationalization utilities
  authenticatedFetch, // Authenticated fetch to your app backend
} = useApi();

Use authenticatedFetch instead of plain fetch when calling your app’s backend API — it automatically includes a session token that your backend can verify:

const { authenticatedFetch } = useApi();

const response = await authenticatedFetch('/api/loyalty-points');
const data = await response.json();

shopify app dev

This starts the local dev server and provides a URL to preview the extension on your development store. You’ll see live reload as you edit component code. Open your dev store’s customer account, log in, and navigate to the target page — you’ll see your extension rendered inline.

# Build and upload the extension
shopify app deploy

# This will:
# 1. Build all extensions
# 2. Upload to Shopify's CDN
# 3. Create a new app version in your Partner Dashboard

After deploying, go to your Shopify Partner Dashboard → Apps → your app → Extensions, and verify the extension version is published. Merchants then activate it from their Shopify admin under Customer Accounts settings.

• Loyalty points dashboard — show points balance and redemption options on the orders page
• Return portal — embed a self-service returns flow on the order status page
• Subscription management — show active subscriptions with pause/cancel actions on the profile page
• Custom profile fields — collect additional customer data (birthday, preferences) stored as metafields
• Wishlist display — show saved items with quick-add-to-cart on a custom account page