Customer Account UI Extensions

https://shopify.dev/docs/api/customer-account-ui-extensions/latest
Admin
Customer account UI extensions allow app developers to build custom functionality for merchants to...
Tokens:110,685
Snippets:887
Trust Score:10
Update:15 hours ago
Show doc for...
Tokens:
Raw
### Grid layout example with badge, text, and link

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/grid

Use this snippet to create a grid layout with three columns: auto, 1fr, and auto. The grid contains a badge, text, and link, aligned with a base gap. This example is from the Grid component documentation.

```html
<s-grid gridTemplateColumns="auto 1fr auto" gap="base" alignItems="center">
  <s-badge tone="auto">Delivered</s-badge>
  <s-text>Order #1042 — March 15, 2026</s-text>
  <s-link href="#">View details</s-link>
</s-grid>
```

--------------------------------

### Show a list of actions

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/overlays/popover

Present a set of related actions in a compact overlay. This example shows an action list with options for returns, issue reporting, and support.

```html
<s-button commandFor="action-list">Actions</s-button>
<s-popover id="action-list">
  <s-action-list>
    <s-action-list-item>Start a return</s-action-list-item>
    <s-action-list-item>Report an issue</s-action-list-item>
    <s-action-list-item>Contact support</s-action-list-item>
  </s-action-list>
</s-popover>
```

--------------------------------

### Navigate to another extension

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/navigation-api

Deep-links to a different installed extension using the 'extension://<handle>' protocol. This example navigates to a loyalty rewards extension when the customer clicks a button in a banner.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  function handleNavigate() {
    shopify.navigation.navigate(
      'extension://loyalty-rewards',
    );
  }

  return (
    <s-banner heading="Loyalty program">
      <s-text>
        You have 1,200 points available.
      </s-text>
      <s-button onClick={handleNavigate}>
        View rewards
      </s-button>
    </s-banner>
  );
}
```

--------------------------------

### Display contextual information

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/overlays/popover

Surface supplementary information on demand without cluttering the main view. This example shows shipping details in a popover triggered by a button.

```html
<s-button commandFor="shipping-details">Shipping details</s-button>
<s-popover id="shipping-details">
  <s-stack gap="base" padding="base">
    <s-heading>Standard shipping</s-heading>
    <s-paragraph>Estimated delivery: 5–7 business days</s-paragraph>
    <s-paragraph>Tracking number will be emailed once your order ships.</s-paragraph>
  </s-stack>
</s-popover>
```

--------------------------------

### Promote a members-only offer

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/feedback-and-status-indicators/announcement

Example showing a personalized discount for signed-in customers using subdued text for the discount code.

```APIDOC
## Promote a members-only offer

### Description
Display a personalized discount for signed-in customers. This example uses subdued text for the discount code so the main message stands out.

### Example
(No code example provided in the source.)
```

--------------------------------

### Display a promotional announcement

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/feedback-and-status-indicators/announcement

Example showing an s-announcement with inline text and a link inviting customers to fill out a survey.

```APIDOC
## Display a promotional announcement

### Description
Display a promotional announcement with a survey link. This example shows an `s-announcement` with inline text and a link inviting customers to fill out a survey.

### Example
```html
<s-announcement>
  Enjoy a free plant on us! 🌿 We'd love to hear from you. <s-link href="/survey">Fill out the survey</s-link>
</s-announcement>
```
```

--------------------------------

### Example: Dismiss a selected option

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/clickable-chip

Show a removable chip that users can dismiss with a single tap. This example uses the `removable` attribute for a shipping insurance option.

```APIDOC
## Example: Dismiss a selected option

### Description
Show a removable chip that users can dismiss with a single tap. This example uses the `removable` attribute for a shipping insurance option.

```

--------------------------------

### Start development server with shopify app dev

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest

Run the Shopify CLI development server for customer account UI extensions. Requires a dev store with customer accounts enabled and test customer accounts created.

```bash
shopify app dev
```

--------------------------------

### Translate a static string with shopify.i18n.translate

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/localization-api

JSX example showing how to translate a static string using shopify.i18n.translate. It imports from '@shopify/ui-extensions/preact' and 'preact', renders an Extension component, and uses the translation key 'welcomeMessage'. The translation keys and values are provided in the locales/en.default.json tab.

```JSX
/* See the locales/en.default.json tab for the translation keys and values for this example */
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  return (
    <s-text>
      {shopify.i18n.translate('welcomeMessage')}
    </s-text>
  );
}
```

--------------------------------

### Translate a static string with shopify.i18n.translate()

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/localization-api

Renders a translated string from a locale file using shopify.i18n.translate(). The example displays a welcome message that adapts to the customer's language. The locale file defines the 'welcomeMessage' key.

```tsx
/* See the locales/en.default.json tab for the translation keys and values for this example */
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  return (
    <s-text>
      {shopify.i18n.translate('welcomeMessage')}
    </s-text>
  );
}
```

```json
{
  "welcomeMessage": "Welcome to our store!"
}
```

--------------------------------

### Format currency values using shopify.localization.currency

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/order-status-localization-api

Reads shopify.localization.currency.isoCode and uses Intl.NumberFormat to display formatted currency values. The example shows a sample amount of 49.99 formatted as currency.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const currency =
    shopify.localization.currency.value;
  const formatter = new Intl.NumberFormat(
    undefined,
    {
      style: 'currency',
      currency: currency.isoCode,
    },
  );

  const sampleAmount = 49.99;

  return (
    <s-box padding="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">Order Summary</s-text>
        <s-divider />
        <s-stack
          direction="inline"
          gap="base"
          justifyContent="space-between"
        >
          <s-text>Subtotal</s-text>
          <s-text>
            {formatter.format(sampleAmount)}
          </s-text>
        </s-stack>
        <s-text color="subdued">
          Prices shown in {currency.isoCode}
        </s-text>
      </s-stack>
    </s-box>
  );
}
```

--------------------------------

### Fetch loyalty points with session token

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest

Use this snippet to call your own backend from a Customer Account UI Extension. It requires network_access = true in capabilities and a server with Access-Control-Allow-Origin: * header. The example fetches loyalty points using a session token obtained from shopify.sessionToken.get().

```javascript
import {render} from 'preact';

import {useState, useEffect} from 'preact/hooks';

export default () => {

  render(<Extension />, document.body);

};

async function getLoyaltyPoints(sessionToken) {

  const res = await fetch('https://your-app.com/api/loyalty', {

    headers: {

      Authorization: `Bearer ${sessionToken}`,

    },

  });

  return res.json();

}

function Extension() {

  const [points, setPoints] = useState(null);

  useEffect(() => {

    async function fetchPoints() {

      const token = await shopify.sessionToken.get();

      const data = await getLoyaltyPoints(token);

      setPoints(data.points);

    }

    fetchPoints();

  }, []);

  return (

    <s-section>

      <s-text>Loyalty points: {points ?? 'Loading...'}</s-text>

    </s-section>

  );

}
```

--------------------------------

### Scaffold a customer account UI extension with Shopify CLI

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest

Use Shopify CLI to generate a new customer account UI extension. Run these commands from your app directory. The first command changes to the app directory, and the second starts the interactive extension generator.

```bash
cd my-app
shopify app generate extension
```

--------------------------------

### Display order items (JSX)

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/cart-lines-api

Example of a Preact extension that reads the cart lines from `shopify.lines.value` and renders a list of items with image, title, quantity, and total cost. It shows a fallback message when there are no items.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const lines = shopify.lines.value;

  if (!lines || lines.length === 0) {
    return <s-text>No items in this order.</s-text>;
  }

  return (
    <s-stack>
      {lines.map((line) => (
        <s-box key={line.id}>
          <s-stack direction="inline">
            {line.merchandise.image?.url && (
              <s-image
                src={line.merchandise.image.url}
                alt={line.merchandise.title}
              />
            )}
            <s-stack>
              <s-text type="strong">
                {line.merchandise.title}
              </s-text>
              <s-text>Qty: {line.quantity}</s-text>
              <s-text>
                {line.cost.totalAmount.amount}{' '}
                {line.cost.totalAmount.currencyCode}
              </s-text>
            </s-stack>
          </s-stack>
        </s-box>
      ))}
    </s-stack>
  );
}
```

--------------------------------

### Create a two-column summary with s-grid

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/grid

Uses gridTemplateColumns="1fr auto" and gap="small-200" to create a flexible two-column layout. Pairs a product name with its price, giving the name column more space.

```html
<s-grid gridTemplateColumns="1fr auto" gap="small-200">
  <s-text>Plants for sale</s-text>
  <s-text></s-text>
  <s-text>Pothos</s-text>
  <s-text>$25.00</s-text>
</s-grid>
```

--------------------------------

### Show return details with shipping instructions

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/payments-and-returns

Displays return shipping instructions specific to a return. Uses shopify.returnId to reference the current return and provides contextual return information.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const order = shopify.order.value;
  const returnId = shopify.returnId;

  if (!order) {
    return null;
  }

  return (
    <s-stack direction="block" gap="base">
      <s-heading>Return shipping instructions</s-heading>
      <s-text>
        Please ship your items back within 14 days. Include return reference{' '}
        {returnId} on the shipping label.
      </s-text>
      <s-text color="subdued">
        Order {order.name}
      </s-text>
    </s-stack>
  );
}
```

--------------------------------

### Suggest related products after the line item list (JSX)

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status

Fetches product recommendations from your app's backend using the session token and renders them as a list with links below the order's line items. Returns null if there are no recommendations.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const [recommendations, setRecommendations] = useState(null);

  useEffect(() => {
    async function fetchRecommendations() {
      const token = await shopify.sessionToken.get();
      const res = await fetch('https://your-app.com/api/recommendations', {
        headers: {Authorization: `Bearer ${token}`},
      });
      const data = await res.json();
      setRecommendations(data.products);
    }
    fetchRecommendations();
  }, []);

  if (!recommendations || recommendations.length === 0) return null;

  return (
    <s-section heading="You might also like">
      <s-stack direction="block" gap="base">
        {recommendations.map((product) => (
          <s-stack key={product.id} direction="inline" gap="base">
            <s-text type="strong">{product.title}</s-text>
            <s-link href={product.url}>View product</s-link>
          </s-stack>
        ))}
      </s-stack>
    </s-section>
  );
}
```

--------------------------------

### Slots

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/clickable-chip

The clickable chip component supports slots for additional content placement within the component. The graphic slot is an optional graphic displayed at the start of the chip.

```APIDOC
## Slots

### Description
The clickable chip component supports slots for additional content placement within the component. Learn more about [using slots](https://shopify.dev/docs/api/polaris/using-polaris-web-components#slots).

### Slot: graphic
- **Type**: HTMLElement
- **Description**: An optional graphic displayed at the start of the chip, such as an icon to visually reinforce the chip's label. Only the `s-icon` element and its `type` attribute are supported.

```

--------------------------------

### Show a form in a popover

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/overlays/popover

Collect input inline without navigating away from the page. This example presents a text field and submit button inside a popover for verifying a veteran ID.

```html
<s-button commandFor="popover-veteran-id">Verify veteran status</s-button>
<s-popover id="popover-veteran-id">
  <s-stack gap="base" padding="base" direction="inline">
    <s-text-field label="Veteran ID"></s-text-field>
    <s-button variant="primary">Validate</s-button>
  </s-stack>
</s-popover>
```

--------------------------------

### Collapse multiple secondary actions

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/button-group

Automatically collapses extra secondary actions into an overflow menu on smaller screens. The example shows an s-button-group with one primary and three secondary buttons.

```html
<s-button-group>
  <s-button slot="primary-action" variant="primary">
    Primary action
  </s-button>
  <s-button slot="secondary-actions" variant="secondary">
    Secondary action 1
  </s-button>
  <s-button slot="secondary-actions" variant="secondary">
    Secondary action 2
  </s-button>
  <s-button slot="secondary-actions" variant="secondary">
    Secondary action 3
  </s-button>
</s-button-group>
```

--------------------------------

### Warning paragraph with tone and color

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/typography-and-content/paragraph

Use tone="warning" and color="subdued" to display a warning message that is de-emphasized. This example shows a shipping address warning.

```html
<s-paragraph tone="warning" color="subdued">

We can't ship to this address. Update your details to continue.

</s-paragraph>
```

--------------------------------

### Add an icon to a chip using graphic slot

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/actions/clickable-chip

Add an icon next to the chip label using the 'graphic' slot with an s-icon. This example shows a chip for a sale collection with a discount icon.

```html
<s-clickable-chip>
  <s-icon type="discount" slot="graphic"></s-icon>
  On sale
</s-clickable-chip>
```

--------------------------------

### Highlight a critical status with s-badge

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/feedback-and-status-indicators/badge

Uses the critical and warning tones to draw attention to statuses that require customer action. This example pairs a critical badge with an icon and a warning badge side by side.

```html
<s-badge tone="critical">Expired</s-badge>
<s-badge tone="warning">Warning</s-badge>
```

--------------------------------

### Show a preparation notice (JSX)

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/fulfillment-status

Displays a banner informing customers that their items are being prepared for shipment. Reads order data from shopify.order to include the order name for context.

```jsx
import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const order = shopify.order.value;

  if (!order) {
    return null;
  }

  return (
    <s-banner tone="info">
      Items from order {order.name} are being prepared. You'll receive tracking
      details once they ship.
    </s-banner>
  );
}
```

--------------------------------

### SessionToken.get

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/session-token-api

Requests a session token that hasn't expired. Call this method every time you make a request to your backend to get a valid token. Cached tokens are returned when possible, so you don't need to store them yourself.

```APIDOC
## SessionToken.get

### Description
Requests a session token that hasn't expired. Call this method every time you make a request to your backend to get a valid token. Cached tokens are returned when possible, so you don't need to store them yourself.

### Method
- get

### Return Type
`() => Promise<string>`

### Returns
A Promise that resolves to a signed JWT string containing the customer ID, shop domain, and expiration time.

### Example
Fetch data with a session token
```

--------------------------------

### Render Order Summary with Currency Formatting

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/order-status-localization-api

Use this snippet to create a customer account UI extension that displays an order summary with a subtotal formatted in the shop's currency. It imports from '@shopify/ui-extensions/preact' and uses the 'shopify.localization.currency' value to format the amount. The extension renders a box with a stack containing the summary text and a subdued currency note.

```jsx
import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const currency =
    shopify.localization.currency.value;
  const formatter = new Intl.NumberFormat(
    undefined,
    {
      style: 'currency',
      currency: currency.isoCode,
    },
  );
  const sampleAmount = 49.99;

  return (
    <s-box padding="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">Order Summary</s-text>
        <s-divider />
        <s-stack
          direction="inline"
          gap="base"
          justifyContent="space-between"
        >
          <s-text>Subtotal</s-text>
          <s-text>
            {formatter.format(sampleAmount)}
          </s-text>
        </s-stack>
        <s-text color="subdued">
          Prices shown in {currency.isoCode}
        </s-text>
      </s-stack>
    </s-box>
  );
}
```

--------------------------------

### Subdued paragraph for legal or tax copy

Source: https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/typography-and-content/paragraph

Use color="subdued" on s-paragraph to de-emphasize legal or tax copy that must appear but shouldn't dominate the layout. This example shows text below the order total.

```html
<s-paragraph color="subdued">

Prices are in USD and include applicable taxes. Shipping costs are calculated

at checkout based on your delivery address.

</s-paragraph>
```
Tokens:
Raw