--- title: Toast API description: >- The Toast API lets you show brief, non-disruptive notification messages to customers. Use this API to confirm successful actions, surface errors, or provide lightweight feedback that appears temporarily and dismisses automatically. api_version: 2026-04 source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/toast-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/toast-api.md --- # Toast API The Toast API lets you show brief, non-disruptive notification messages to customers. Use this API to confirm successful actions, surface errors, or provide lightweight feedback that appears temporarily and dismisses automatically. ### 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 (24) ### Supported targets * [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/footer#footer-render-after-) * [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-announcement-) * [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-block-) * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-menu-item-) * [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-) * [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#customer-account-full-page-) * [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-page-default-targets-) * [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-announcement-) * [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-block-) * [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/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/2026-04/targets/profile-page-b2b#company-location-staff-render-after-) * customer-account.​profile.​payment.​render-after ### Properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#target-apis-define-what-your-extension-does) provides toast notification functionality for customer account extensions. Access the following properties on `shopify` to show brief, non-blocking notification messages to the customer. * **toast** **ToastApi** **required** Displays brief, non-blocking messages at the bottom of the page to confirm actions or report errors. Use noun + past tense verb format (for example, `Changes saved`). For persistent messages, use a [Banner](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/ui-components/feedback-and-status-indicators/banner) component instead. ### ToastApi Displays brief, non-blocking notification messages to the customer. Use the Toast API to confirm successful actions, report errors, or surface contextual feedback without interrupting the customer workflow. * show Show a toast notification with the given message. Returns a handle with a \`hide()\` method to dismiss the toast programmatically. ```ts (content: string) => Promise ``` ### ToastApiResult A handle returned by \`ToastApi.show()\`. Call \`hide()\` to dismiss the toast notification programmatically. * hide Dismisses the toast notification. ```ts () => void ``` Examples ### Examples * #### ##### Description Display a toast notification after completing an action like saving preferences. This example calls \`shopify.toast.show()\` with a message string after a successful write to storage. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { async function handleSave() { await shopify.storage.write( 'preferences_saved', 'true', ); shopify.toast.show('Preferences saved'); } return ( Save preferences ); } ``` * #### ##### Description Display an error toast when an operation fails so the customer knows to try again. This example wraps a fetch call in a try-catch block and passes \`{isError: true}\` to \`shopify.toast.show()\` on failure. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { async function handleSubmit() { try { const token = await shopify.sessionToken.get(); const response = await fetch( 'https://myapp.com/api/submit', { method: 'POST', headers: { Authorization: `Bearer ${token}`, }, }, ); if (!response.ok) { throw new Error('Request failed'); } shopify.toast.show( 'Submitted successfully', ); } catch (error) { shopify.toast.show( 'Something went wrong. Please try again.', {isError: true}, ); } } return ( Submit ); } ``` *** ## Best practices * **Keep messages short**: Toast messages should be a few words that confirm what happened, like "Preferences 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. ***