@shopify/ui-extensions 2025.10.0-rc.4 → 2025.10.0-rc.41

package/src/surfaces/customer-account/api/order-status/order-status.ts

@@ -1,5 +1,3 @@
-import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
-
 import type {
   CurrencyCode,
   Country,
@@ -8,6 +6,7 @@ import type {
   Attribute,
   MailingAddress,
   Language,
+  SubscribableSignalLike,
 } from '../shared';
 import type {ExtensionTarget} from '../../extension-targets';
 import {Extension} from '../shared';
@@ -138,17 +137,17 @@ export interface OrderStatusLocalization {
   /**
    * The currency that the buyer sees for money amounts in the checkout.
    */
-  currency: StatefulRemoteSubscribable<Currency>;
+  currency: SubscribableSignalLike<Currency>;
 
   /**
    * The buyer’s time zone.
    */
-  timezone: StatefulRemoteSubscribable<Timezone>;
+  timezone: SubscribableSignalLike<Timezone>;
 
   /**
    * The language the buyer sees in the checkout.
    */
-  language: StatefulRemoteSubscribable<Language>;
+  language: SubscribableSignalLike<Language>;
 
   /**
    * This is the buyer's language, as supported by the extension.
@@ -161,7 +160,7 @@ export interface OrderStatusLocalization {
    * translations at all, this value is the default locale for your
    * extension (that is, the one matching your .default.json file).
    */
-  extensionLanguage: StatefulRemoteSubscribable<Language>;
+  extensionLanguage: SubscribableSignalLike<Language>;
 
   /**
    * The country context of the checkout. This value carries over from the
@@ -169,7 +168,7 @@ export interface OrderStatusLocalization {
    * experience. It will update if the buyer changes the country of their
    * shipping address. The value is undefined if unknown.
    */
-  country: StatefulRemoteSubscribable<Country | undefined>;
+  country: SubscribableSignalLike<Country | undefined>;
 
   /**
    * The [market](https://shopify.dev/docs/apps/markets) context of the
@@ -178,21 +177,16 @@ export interface OrderStatusLocalization {
    * buyer changes the country of their shipping address. The value is undefined
    * if unknown.
    */
-  market: StatefulRemoteSubscribable<Market | undefined>;
+  market: SubscribableSignalLike<Market | undefined>;
 }
 
 export type AuthenticationState = 'fully_authenticated' | 'pre_authenticated';
 
 export interface OrderStatusApi<Target extends ExtensionTarget> {
-  /**
-   * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
-   */
-  analytics: Analytics;
-
   /**
    * Gift Cards that have been applied to the order.
    */
-  appliedGiftCards: StatefulRemoteSubscribable<AppliedGiftCard[]>;
+  appliedGiftCards: SubscribableSignalLike<AppliedGiftCard[]>;
 
   /**
    * The metafields requested in the
@@ -202,12 +196,12 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  appMetafields: StatefulRemoteSubscribable<AppMetafieldEntry[]>;
+  appMetafields: SubscribableSignalLike<AppMetafieldEntry[]>;
 
   /**
    * Custom attributes left by the customer to the merchant, either in their cart or during checkout.
    */
-  attributes: StatefulRemoteSubscribable<Attribute[] | undefined>;
+  attributes: SubscribableSignalLike<Attribute[] | undefined>;
 
   /**
    * Information about the buyer that is interacting with the order.
@@ -219,7 +213,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * Settings applied to the buyer's checkout.
    */
-  checkoutSettings: StatefulRemoteSubscribable<CheckoutSettings>;
+  checkoutSettings: SubscribableSignalLike<CheckoutSettings>;
 
   /**
    * Details on the costs of the purchase for the buyer.
@@ -229,12 +223,12 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * A list of discount codes applied to the purchase.
    */
-  discountCodes: StatefulRemoteSubscribable<CartDiscountCode[]>;
+  discountCodes: SubscribableSignalLike<CartDiscountCode[]>;
 
   /**
    * Discounts that have been applied to the entire cart.
    */
-  discountAllocations: StatefulRemoteSubscribable<CartDiscountAllocation[]>;
+  discountAllocations: SubscribableSignalLike<CartDiscountAllocation[]>;
 
   /**
    * Meta information about the extension.
@@ -257,7 +251,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * A list of lines containing information about the items the customer intends to purchase.
    */
-  lines: StatefulRemoteSubscribable<CartLine[]>;
+  lines: SubscribableSignalLike<CartLine[]>;
 
   /**
    * Details about the location, language, and currency of the buyer. For utilities to easily
@@ -287,17 +281,17 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * Once the order is created, you can query these metafields using the
    * [GraphQL Admin API](https://shopify.dev/docs/admin-api/graphql/reference/orders/order#metafield-2021-01)
    */
-  metafields: StatefulRemoteSubscribable<Metafield[]>;
+  metafields: SubscribableSignalLike<Metafield[]>;
 
   /**
    * A note left by the customer to the merchant, either in their cart or during checkout.
    */
-  note: StatefulRemoteSubscribable<string | undefined>;
+  note: SubscribableSignalLike<string | undefined>;
 
   /**
    * Information about the order that was placed.
    */
-  order: StatefulRemoteSubscribable<Order | undefined>;
+  order: SubscribableSignalLike<Order | undefined>;
 
   /**
    * id that represents the checkout used to create the order.
@@ -305,21 +299,21 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * Matches the `token` field in the [WebPixel checkout payload](https://shopify.dev/docs/api/pixels/customer-events#checkout)
    * and the `checkout_token` field in the [Admin REST API Order resource](https://shopify.dev/docs/api/admin-rest/unstable/resources/order#resource-object).
    */
-  checkoutToken: StatefulRemoteSubscribable<CheckoutToken | undefined>;
+  checkoutToken: SubscribableSignalLike<CheckoutToken | undefined>;
 
   /**
    * The buyer shipping address used for the order.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  shippingAddress?: StatefulRemoteSubscribable<MailingAddress | undefined>;
+  shippingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 
   /**
    * The buyer billing address used for the order.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  billingAddress?: StatefulRemoteSubscribable<MailingAddress | undefined>;
+  billingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 
   /** Shop where the purchase took place. */
   shop: Shop;
@@ -339,7 +333,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * The authentication state of Order status page.
    */
-  authenticationState: StatefulRemoteSubscribable<AuthenticationState>;
+  authenticationState: SubscribableSignalLike<AuthenticationState>;
 }
 
 export interface OrderStatusBuyerIdentity {
@@ -349,7 +343,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  customer: StatefulRemoteSubscribable<OrderStatusCustomer | undefined>;
+  customer: SubscribableSignalLike<OrderStatusCustomer | undefined>;
 
   /**
    * The email address of the buyer that is interacting with the cart.
@@ -357,7 +351,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  email: StatefulRemoteSubscribable<string | undefined>;
+  email: SubscribableSignalLike<string | undefined>;
 
   /**
    * The phone number of the buyer that is interacting with the cart.
@@ -365,7 +359,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  phone: StatefulRemoteSubscribable<string | undefined>;
+  phone: SubscribableSignalLike<string | undefined>;
 
   /**
    * Provides details of the company and the company location that the business customer is purchasing on behalf of.
@@ -374,7 +368,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  purchasingCompany: StatefulRemoteSubscribable<
+  purchasingCompany: SubscribableSignalLike<
     OrderStatusPurchasingCompany | undefined
   >;
 }
@@ -485,28 +479,28 @@ export interface CartCost {
    * A `Money` value representing the subtotal value of the items in the cart at the current
    * step of checkout.
    */
-  subtotalAmount: StatefulRemoteSubscribable<Money>;
+  subtotalAmount: SubscribableSignalLike<Money>;
 
   /**
    * A `Money` value representing the total shipping a buyer can expect to pay at the current
    * step of checkout. This value includes shipping discounts. Returns undefined if shipping
    * has not been negotiated yet, such as on the information step.
    */
-  totalShippingAmount: StatefulRemoteSubscribable<Money | undefined>;
+  totalShippingAmount: SubscribableSignalLike<Money | undefined>;
 
   /**
    * A `Money` value representing the total tax a buyer can expect to pay at the current
    * step of checkout or the total tax included in product and shipping prices. Returns
    * undefined if taxes are unavailable.
    */
-  totalTaxAmount: StatefulRemoteSubscribable<Money | undefined>;
+  totalTaxAmount: SubscribableSignalLike<Money | undefined>;
 
   /**
    * A `Money` value representing the minimum a buyer can expect to pay at the current
    * step of checkout. This value excludes amounts yet to be negotiated. For example,
    * the information step might not have delivery costs calculated.
    */
-  totalAmount: StatefulRemoteSubscribable<Money>;
+  totalAmount: SubscribableSignalLike<Money>;
 }
 
 export interface CartLine {
@@ -952,13 +946,6 @@ export interface StoreCreditAccount {
   balance: Money;
 }
 
-export interface Analytics {
-  /**
-   * Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing).
-   */
-  publish(name: string, data: {[key: string]: unknown}): Promise<boolean>;
-}
-
 /**
  * Represents the delivery information and options available for one or
  * more cart lines.

package/src/surfaces/customer-account/api/shared.ts

@@ -1,5 +1,4 @@
 import type {ExtensionTarget} from '../extension-targets';
-import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
 
 import type {
   ApiVersion,
@@ -12,6 +11,8 @@ import type {
   StorefrontApiVersion,
 } from '../../../shared';
 
+import type {SubscribableSignalLike} from '../../checkout/shared';
+
 export {
   ApiVersion,
   Capability,
@@ -21,6 +22,7 @@ export {
   CountryCode,
   GraphQLError,
   StorefrontApiVersion,
+  SubscribableSignalLike,
 };
 
 /**
@@ -162,7 +164,7 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    *
    * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
    */
-  capabilities: StatefulRemoteSubscribable<Capability[]>;
+  capabilities: SubscribableSignalLike<Capability[]>;
 
   /**
    * Information about the editor where the extension is being rendered.
@@ -182,7 +184,7 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    * from where it was rendered. The extension continues running so that
    * your extension is immediately available to render if the buyer navigates back.
    */
-  rendered: StatefulRemoteSubscribable<boolean>;
+  rendered: SubscribableSignalLike<boolean>;
 
   /**
    * The URL to the script that started the extension target.
@@ -345,11 +347,11 @@ export interface AuthenticatedAccount {
    * Provides the company info of the authenticated business customer.
    * If the customer is not authenticated or is not a business customer, this value is `undefined`.
    */
-  purchasingCompany: StatefulRemoteSubscribable<PurchasingCompany | undefined>;
+  purchasingCompany: SubscribableSignalLike<PurchasingCompany | undefined>;
   /**
    * Provides the customer information of the authenticated customer.
    */
-  customer: StatefulRemoteSubscribable<Customer | undefined>;
+  customer: SubscribableSignalLike<Customer | undefined>;
 }
 
 /**
@@ -392,55 +394,58 @@ export interface CompanyLocation {
   id: string;
 }
 
-export interface Ui {
+export interface SessionToken {
   /**
-   * An overlay is a contextual element on top of the main interface that provides additional information or functionality.
+   * Requests a session token that hasn't expired. You should call this method every
+   * time you need to make a request to your backend in order to get a valid token.
+   * This method will return cached tokens when possible, so you don’t need to worry
+   * about storing these tokens yourself.
    */
-  overlay: {
-    close(overlayId: string): void;
-  };
+  get(): Promise<string>;
+}
+
+export interface Analytics {
   /**
-   * 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/checkout-ui-extensions/unstable/components/feedback/banner) component.
+   * Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing).
    */
-  toast: {
-    show(content: string): void;
-  };
+  publish(name: string, data: Record<string, unknown>): Promise<boolean>;
+
   /**
-   * 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**.
+   * A method for capturing details about a visitor on the online store.
    */
-  forceDataRefresh(content: string): Promise<void>;
+  visitor(data: {email?: string; phone?: string}): Promise<VisitorResult>;
 }
+/**
+ * Represents a visitor result.
+ */
+export type VisitorResult = VisitorSuccess | VisitorError;
 
-export interface SessionToken {
+/**
+ * Represents a successful visitor result.
+ */
+export interface VisitorSuccess {
   /**
-   * Requests a session token that hasn't expired. You should call this method every
-   * time you need to make a request to your backend in order to get a valid token.
-   * This method will return cached tokens when possible, so you don’t need to worry
-   * about storing these tokens yourself.
+   * Indicates that the visitor information was validated and submitted.
    */
-  get(): Promise<string>;
+  type: 'success';
+}
+
+/**
+ * Represents an unsuccessful visitor result.
+ */
+export interface VisitorError {
+  /**
+   * Indicates that the visitor information is invalid and wasn't submitted.
+   * Examples are using the wrong data type or missing a required property.
+   */
+  type: 'error';
+
+  /**
+   * A message that explains the error. This message is useful for debugging.
+   * It's **not** localized, and therefore should not be presented directly
+   * to the buyer.
+   */
+  message: string;
 }
 
 export interface AllowedProcessing {
@@ -614,3 +619,10 @@ export interface TrackingConsentChangeResultError {
    */
   message: string;
 }
+
+export interface ToastApiResult {
+  hide: () => void;
+}
+export interface ToastApi {
+  show: (content: string) => Promise<ToastApiResult>;
+}

package/src/surfaces/customer-account/api/standard-api/standard-api.ts

@@ -7,14 +7,15 @@ import {
   AuthenticatedAccount,
   GraphQLError,
   StorefrontApiVersion,
-  Ui,
   SessionToken,
+  Analytics,
   CustomerPrivacy,
   ApplyTrackingConsentChangeType,
+  ToastApi,
+  SubscribableSignalLike,
 } from '../shared';
 
 import type {ExtensionTarget} from '../../extension-targets';
-import {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
 
 /**
  * The merchant-defined setting values for the extension.
@@ -79,6 +80,13 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   sessionToken: SessionToken;
 
+  /**
+   * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
+   *
+   * > Note: Requires to [connect a third-party domain](https://help.shopify.com/en/manual/domains/add-a-domain/connecting-domains/connect-domain-customer-account) to Shopify for your customer account pages.
+   */
+  analytics: Analytics;
+
   /**
    * The settings matching the settings definition written in the
    * [`shopify.ui.extension.toml`](https://shopify.dev/docs/api/customer-account-ui-extensions/configuration) file.
@@ -88,14 +96,24 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    * > Note: When an extension is being installed in the editor, the settings will be empty until
    * a merchant sets a value. In that case, this object will be updated in real time as a merchant fills in the settings.
    */
-  settings: StatefulRemoteSubscribable<ExtensionSettings>;
+  settings: SubscribableSignalLike<ExtensionSettings>;
 
   /**
-   * Methods to interact with the extension's UI.
+   * 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/checkout-ui-extensions/unstable/components/feedback/banner) component.
    */
-  ui: Ui;
-
-  navigation: StandardExtensionNavigation;
+  toast: ToastApi;
 
   /**
    * Used to query the Storefront GraphQL API with a prefetched token.
@@ -110,7 +128,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Customer privacy consent settings and a flag denoting if consent has previously been collected.
    */
-  customerPrivacy: StatefulRemoteSubscribable<CustomerPrivacy>;
+  customerPrivacy: SubscribableSignalLike<CustomerPrivacy>;
 
   /**
    * Allows setting and updating customer privacy consent settings and tracking consent metafields.
@@ -148,7 +166,7 @@ export interface Localization {
   /**
    * The language the buyer sees in the customer account hub.
    */
-  language: StatefulRemoteSubscribable<Language>;
+  language: SubscribableSignalLike<Language>;
 
   /**
    * This is the buyer's language, as supported by the extension.
@@ -161,26 +179,26 @@ export interface Localization {
    * translations at all, this value is the default locale for your
    * extension (that is, the one matching your .default.json file).
    */
-  extensionLanguage: StatefulRemoteSubscribable<Language>;
+  extensionLanguage: SubscribableSignalLike<Language>;
 
   /**
    * The country context of the buyer sees in the customer account.
    * It will update if the buyer changes the country in the customer account
    * If the country is unknown, then the value is undefined.
    */
-  country: StatefulRemoteSubscribable<Country | undefined>;
+  country: SubscribableSignalLike<Country | undefined>;
 }
 
 /**
  * An enumerated value representing the type of navigation.
  */
-export type NavigationType = 'push' | 'replace' | 'traverse';
+export type NavigationTypeString = 'push' | 'replace' | 'traverse';
 
-export interface NavigationOptions {
+export interface NavigationNavigateOptions {
   /**
    * Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState().
    */
-  state?: Record<string, any>;
+  state?: unknown;
   /**
    * An enumerated value that sets the history behavior of this navigation.
    */
@@ -196,11 +214,15 @@ export interface NavigationHistoryEntry {
   /**
    * Returns the URL of this history entry.
    */
-  url: string;
+  url: string | null;
   /**
    * Returns a clone of the available state associated with this history entry.
    */
-  getState(): Record<string, any>;
+  getState(): unknown;
+}
+
+export interface NavigationUpdateCurrentEntryOptions {
+  state: unknown;
 }
 
 /**
@@ -210,21 +232,18 @@ export interface NavigationCurrentEntryChangeEvent {
   /**
    * Returns the type of the navigation that resulted in the change.
    */
-  navigationType: NavigationType;
+  navigationType?: NavigationTypeString;
   /**
    * Returns the NavigationHistoryEntry that was navigated from.
    */
   from: NavigationHistoryEntry;
 }
 
-export interface StandardExtensionNavigation {
+export interface Navigation {
   /**
    * The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
    */
   navigate: NavigateFunction;
-}
-
-export interface FullExtensionNavigation extends StandardExtensionNavigation {
   /**
    * The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
    */
@@ -232,7 +251,7 @@ export interface FullExtensionNavigation extends StandardExtensionNavigation {
   /**
    * The updateCurrentEntry() method of the Navigation interface updates the state of the currentEntry; used in cases where the state change will be independent of a navigation or reload.
    */
-  updateCurrentEntry(options: {state: Record<string, any>}): void;
+  updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
   addEventListener(
     type: 'currententrychange',
     cb: (event: NavigationCurrentEntryChangeEvent) => void,
@@ -248,7 +267,7 @@ export interface NavigateFunction {
    * Navigates to a specific URL, updating any provided state in the history entries list.
    * @param url The destination URL to navigate to.
    */
-  (url: string, options?: NavigationOptions): void;
+  (url: string, options?: NavigationNavigateOptions): void;
 }
 
 export type Version = string;

package/src/surfaces/customer-account/api.ts

@@ -66,6 +66,7 @@ export type {
   Company,
   Customer,
   SessionToken,
+  Analytics,
   ApplyTrackingConsentChangeType,
   CustomerPrivacy,
   TrackingConsentChangeResult,
@@ -74,6 +75,10 @@ export type {
   TrackingConsentMetafieldChange,
   VisitorConsent,
   VisitorConsentChange,
+  VisitorResult,
+  VisitorSuccess,
+  VisitorError,
+  SubscribableSignalLike,
 } from './api/shared';
 
 export type {CartLineItemApi} from './api/cart-line/cart-line-item';
@@ -81,12 +86,11 @@ export type {CartLineItemApi} from './api/cart-line/cart-line-item';
 export type {
   Version,
   StandardApi,
-  FullExtensionNavigation,
-  StandardExtensionNavigation,
+  Navigation,
   NavigationCurrentEntryChangeEvent,
   NavigationHistoryEntry,
-  NavigationOptions,
-  NavigationType,
+  NavigationNavigateOptions,
+  NavigationTypeString,
   NavigateFunction,
   Localization,
   CompanyLocationApi,

package/src/surfaces/customer-account/components/Avatar/examples/basic-Avatar-preact.example.tsx

@@ -0,0 +1,10 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  return <s-avatar initials="EW" alt="Evan White" size="base" />;
+}