---
title: UI API
description: >-
  The UI API lets you display brief, non-disruptive notification messages to
  customers using toast notifications. Use this API to confirm successful
  actions, report errors, or surface contextual feedback without interrupting
  the customer workflow.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/ui-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/ui-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# UI API

The UI API lets you display brief, non-disruptive notification messages to customers using toast notifications. Use this API to confirm successful actions, report errors, or surface contextual feedback without interrupting the customer workflow.

**Note:**

In API version 2025-10 and later, this functionality moved to the [Toast API](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-10/target-apis/platform-apis/toast-api).

### Use cases

* **Confirm a completed action**: Show a success toast after the customer saves a preference, submits a form, or completes an operation.
* **Surface an error message**: Display an error toast when a backend request fails or an action can't be completed, so the customer knows something went wrong.
* **Provide status updates**: Notify the customer that a background process like data syncing or a submission has completed.

### Support Targets (25)

### Supported targets

* Customer​Account::Kitchen​Sink
* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

### Properties

The UI API object provides toast notification functionality for customer account extensions. Access the following properties on the API object to show brief, non-blocking notification messages to the customer.

* **ui**

  **Ui**

  **required**

  Triggers platform-level UI interactions, such as displaying toast notifications. Use this to show success or error messages in response to customer actions.

### Ui

Triggers platform-level UI interactions from your extension, such as displaying toast notifications. Use the UI API to show success or error messages in response to customer actions.

* forceDataRefresh

  Refresh data so the surrounding information on the page is updated. The \`content\` string will appear in a toast message after refresh, to confirm the action was successful. To request access to this API: 1. Go to your partner dashboard and click \*\*Apps\*\*. 2. Select the app you need to request access for. 3. Click \*\*API access\*\*. 4. Under \*\*Access force data refresh\*\*, click \*\*Request access\*\*.

  ```ts
  (content: string) => Promise<void>
  ```

* overlay

  An overlay is a contextual element on top of the main interface that provides additional information or functionality.

  ```ts
  { close(overlayId: string): void; }
  ```

* toast

  The Toast API displays a non-disruptive message that displays at the bottom of the interface to provide quick, at-a-glance feedback on the outcome of an action. How to use: - Use toasts to confirm successful actions. - Aim for two words. - Use noun + past tense verb format. For example, \\\`Changes saved\\\`. For errors, or information that needs to persist on the page, use a \[banner]\(/docs/api/customer-account-ui-extensions/2025-07/components/feedback/banner) component.

  ```ts
  { show(content: string): void; }
  ```

Examples

### Examples

* ####

  ##### Description

  Display a toast notification after the customer saves a pickup address selection. This example uses \`ui.toast.show()\` from \`useApi()\` to confirm the action.

  ##### React

  ```tsx
  import React, {useState} from 'react';
  import {
    reactExtension,
    useApi,
    Button,
    Select,
    Modal,
  } from '@shopify/ui-extensions-react/customer-account';

  export default reactExtension('customer-account.page.render', () => (
    <Extension />
  ));
  function Extension() {
    const [selectedAddress, setSelectedAddress] = useState();
    const [pickupAddress, setPickupAddress] = useState();
    const {i18n, ui} = useApi<'customer-account.page.render'>();
    return (
      <Modal>
        <Select
          onChange={(value) => {
            setSelectedAddress(value);
          }}
          label="Pickup Address Options"
          value="1"
          options={[
            {
              value: '1',
              label: 'Address 1',
            },
            {
              value: '2',
              label: 'Address 2',
            },
            {
              value: '3',
              label: 'Address 3',
            },
            {
              value: '4',
              label: 'Address 4',
            },
          ]}
        />
        <Button
          onPress={() => {
            setPickupAddress(selectedAddress);
            ui.toast.show('Selection saved');
          }}
        >
          Save
        </Button>
      </Modal>
    );
  }
  ```

***

## Best practices

* **Keep messages short**: Toast messages should be a few words that confirm what happened, like "Selection saved" or "Submitted successfully". Avoid long sentences.
* **Don't rely on toasts for critical information**: Toasts disappear automatically. If the customer needs to take action, use a banner or inline message instead.

***

## Limitations

* Toast messages dismiss automatically after a short duration. You can't control how long they remain visible.
* Only one toast can be displayed at a time. If you trigger multiple toasts in quick succession, earlier ones may be replaced.
* Toast notifications don't support interactive elements like links or buttons. Use them for passive feedback only.

***