@shopify/ui-extensions 2026.1.3 → 2026.1.4

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

@@ -26,14 +26,9 @@ export {
 };
 
 /**
- * A key-value storage object for extension targets.
+ * Persists key-value data across customer sessions for a specific extension target. Use storage to save preferences, dismiss states, or cached data that should survive page reloads without requiring a backend call.
  *
- * Stored data is only available to this specific app
- * but can be shared across multiple extension targets.
- *
- * The storage backend is implemented with `localStorage` and
- * should persist for ... days
- * However, data persistence isn't guaranteed.
+ * Stored data is only available to this specific app but can be shared across multiple extension targets. The storage backend is implemented with `localStorage` and data persistence isn't guaranteed.
  */
 export interface Storage {
   /**
@@ -59,6 +54,9 @@ export interface Storage {
   delete(key: string): Promise<void>;
 }
 
+/**
+ * A language identifier following the [BCP-47 standard](https://en.wikipedia.org/wiki/IETF_language_tag).
+ */
 export interface Language {
   /**
    * The [BCP-47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag that identifies the language. This is a standardized code that may include a base language and an optional region subtag separated by a dash. For example, `'en'` represents English and `'en-US'` represents English as used in the United States. The region subtag follows the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard.
@@ -69,7 +67,7 @@ export interface Language {
 }
 
 /**
- * This defines the i18n.translate() signature.
+ * Translates a key from your extension's locale files into a localized string. Supports interpolation with placeholder replacements and pluralization via a `count` option.
  */
 export interface I18nTranslate {
   /**
@@ -85,6 +83,9 @@ export interface I18nTranslate {
     : (string | ReplacementType)[];
 }
 
+/**
+ * Utilities for translating strings, formatting currencies, numbers, and dates according to the buyer's locale. Use the I18n API alongside the Localization API to build fully localized extensions.
+ */
 export interface I18n {
   /**
    * Returns a localized number.
@@ -113,14 +114,9 @@ export interface I18n {
   ) => string;
 
   /**
-   * Returns a localized date value.
+   * Returns a localized date value. Behaves like the standard `Intl.DateTimeFormat()` and uses the buyer's locale by default.
    *
-   * This function behaves like the standard `Intl.DateTimeFormatOptions()` and uses
-   * the buyer's locale by default. Formatting options can be passed in as
-   * options.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat0
-   * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options
+   * Learn more about [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) and its [formatting options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options).
    *
    * @param options.inExtensionLocale - if true, use the extension's locale
    */
@@ -142,7 +138,8 @@ export interface I18n {
 }
 
 /**
- * Meta information about an extension target.
+ * Metadata about the running extension, including its API version, target, capabilities, and editor context. Use this to read configuration details or conditionally render content based on where the extension is running.
+ * @publicDocs
  */
 export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   /**
@@ -153,12 +150,8 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   apiVersion: ApiVersion;
 
   /**
-   * The allowed capabilities of the extension, defined
-   * in your [`shopify.extension.toml`](/docs/api/customer-account-ui-extensions/{API_VERSION}#configuration) file.
-   *
-   * * [`api_access`](/docs/api/customer-account-ui-extensions/configuration#api-access): the extension can access the Storefront API.
-   *
-   * * [`network_access`](/docs/api/customer-account-ui-extensions/configuration#network-access): the extension can make external network calls.
+   * The allowed capabilities of the extension, defined in your
+   * [`shopify.extension.toml`](/docs/api/customer-account-ui-extensions/{API_VERSION}/configuration) file.
    */
   capabilities: SubscribableSignalLike<Capability[]>;
 
@@ -173,12 +166,11 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    * Whether your extension is currently rendered to the screen.
    *
    * Shopify might render your extension before it's visible in the UI,
-   * typically to pre-render extensions that will appear on a later step of the
-   * checkout.
+   * typically to pre-render extensions that will appear on a later page.
    *
    * Your extension might also continue to run after the buyer has navigated away
    * from where it was rendered. The extension continues running so that
-   * your extension is immediately available to render if the buyer navigates back.
+   * it's immediately available if the buyer navigates back.
    */
   rendered: SubscribableSignalLike<boolean>;
 
@@ -189,12 +181,10 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
 
   /**
    * The identifier that specifies where in Shopify’s UI your code is being
-   * injected. This will be one of the targets you have included in your
-   * extension’s configuration file.
+   * injected. This will be one of the [targets](/docs/api/customer-account-ui-extensions/{API_VERSION}/configuration#targets) you have included in your
+   * extension’s configuration file. For more information, refer to the [extension targets overview](/docs/api/customer-account-ui-extensions/{API_VERSION}/extension-targets-overview).
    *
    * @example 'customer-account.order-status.block.render'
-   * @see /docs/api/customer-account-ui-extensions/extension-targets-overview
-   * @see /docs/apps/app-extensions/configuration#targets
    */
   target: Target;
 
@@ -208,6 +198,9 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   version?: string;
 }
 
+/**
+ * Information about the editor environment when an extension is rendered inside the editor. The value is `undefined` when the extension is not rendering in an editor.
+ */
 export interface Editor {
   /**
    * Indicates whether the extension is rendering in the checkout editor.
@@ -240,6 +233,9 @@ export interface Attribute {
   /**
    * The value associated with the attribute key. This contains the buyer-provided or app-set data for the custom attribute.
    *
+   * Attribute values are always strings. If structured data was stored during
+   * checkout, parse it on read with `JSON.parse()`.
+   *
    * @example 'Happy Birthday!'
    */
   value: string;
@@ -381,34 +377,39 @@ export interface CompanyLocation {
   id: string;
 }
 
+/**
+ * Authenticates requests between your extension and your app backend. Use session tokens to verify the identity of the customer and the shop context when making server-side API calls. The token includes claims such as the customer ID, shop domain, and expiration time.
+ */
 export interface SessionToken {
   /**
-   * 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.
+   * 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.
    */
   get(): Promise<string>;
 }
 
+/**
+ * Tracks custom events and sends visitor information to [web pixels](/docs/apps/build/marketing-analytics/pixels). Use the Analytics API to emit analytics events from your extension, such as tracking product views, button clicks, or conversion funnels.
+ */
 export interface Analytics {
   /**
-   * Publish method to emit analytics events to [Web Pixels](/docs/apps/marketing).
+   * Emit an analytics event to web pixels. The event name and data are forwarded to all registered pixels on the page.
    */
   publish(name: string, data: Record<string, unknown>): Promise<boolean>;
 
   /**
-   * A method for capturing details about a visitor on the online store.
+   * Submits visitor contact information (email or phone) to the shop backend. This data is sent to Shopify and is not propagated to web pixels on the page.
    */
   visitor(data: {email?: string; phone?: string}): Promise<VisitorResult>;
 }
 /**
- * Represents a visitor result.
+ * The result returned by `Analytics.visitor()`. Check the `type` property to determine whether the submission succeeded or failed.
  */
 export type VisitorResult = VisitorSuccess | VisitorError;
 
 /**
- * Represents a successful visitor result.
+ * Returned when visitor information was validated and submitted successfully.
  */
 export interface VisitorSuccess {
   /**
@@ -418,7 +419,7 @@ export interface VisitorSuccess {
 }
 
 /**
- * Represents an unsuccessful visitor result.
+ * Returned when visitor information is invalid and wasn't submitted. Contains a `message` with details about what went wrong.
  */
 export interface VisitorError {
   /**
@@ -568,6 +569,9 @@ export interface CustomerPrivacy {
    *
    * @example `{countryCode: 'CA', provinceCode: 'ON'}` for a visitor in Ontario, Canada; `{countryCode: 'US', provinceCode: undefined}` for a visitor in the United States if geolocation fails to detect the state; or `undefined` if neither country nor province is detected or geolocation fails.
    *
+   * Requires level 1 access to protected customer data. `undefined` without
+   * that access. Regional compliance logic can't run without it.
+   *
    * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
   region?: CustomerPrivacyRegion;
@@ -605,10 +609,23 @@ export interface TrackingConsentChangeResultError {
   message: string;
 }
 
+/**
+ * A handle returned by `ToastApi.show()`. Call `hide()` to dismiss the toast notification programmatically.
+ */
 export interface ToastApiResult {
+  /**
+   * Dismisses the toast notification.
+   */
   hide: () => void;
 }
+
+/**
+ * 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.
+ */
 export interface ToastApi {
+  /**
+   * Show a toast notification with the given message. Returns a handle with a `hide()` method to dismiss the toast programmatically.
+   */
   show: (content: string) => Promise<ToastApiResult>;
 }
 
@@ -621,16 +638,11 @@ export interface ToastApi {
  */
 export interface IntentQueryOptions {
   /**
-   * The resource identifier for edit actions (e.g. `gid://shopify/SubscriptionContract/123`).
+   * The resource identifier for edit actions (such as `gid://shopify/SubscriptionContract/123`).
    */
   value?: string;
   /**
-   * Optional input payload passed to the intent.
-   *
-   * Used to seed forms or supply parameters. The accepted shape is
-   * intent-specific. For example:
-   * - Replacing a payment method on a subscription contract requires
-   *   { field: 'paymentMethod' }
+   * Optional input payload passed to the intent. Used to seed forms or supply parameters. The accepted shape is intent-specific. For example, replacing a payment method on a subscription contract requires `{ field: 'paymentMethod' }`.
    */
   data?: Record<string, unknown>;
 }
@@ -659,7 +671,7 @@ export interface IntentQuery extends IntentQueryOptions {
    */
   action: IntentAction;
   /**
-   * The resource type (e.g. `shopify/SubscriptionContract`).
+   * The resource type (such as `shopify/SubscriptionContract`).
    */
   type: string;
 }
@@ -671,6 +683,9 @@ export interface IntentQuery extends IntentQueryOptions {
  * - `data` contains the output payload
  */
 export interface SuccessIntentResponse {
+  /**
+   * Always `'ok'` for a successful response.
+   */
   code: 'ok';
   /**
    * Validated output payload produced by the workflow.
@@ -690,8 +705,17 @@ export interface SuccessIntentResponse {
  *
  */
 export interface ErrorIntentResponse {
+  /**
+   * Set to `'error'` when present. This property is optional.
+   */
   code?: 'error';
+  /**
+   * A human-readable summary of the failure.
+   */
   message?: string;
+  /**
+   * Structured details for validation or field-specific problems, following the Standard Schema convention.
+   */
   issues?: {
     /**
      * The path to the field with the issue.
@@ -711,6 +735,9 @@ export interface ErrorIntentResponse {
  * abandoned by the user.
  */
 export interface ClosedIntentResponse {
+  /**
+   * Always `'closed'` when the user dismissed the workflow without completing it.
+   */
   code: 'closed';
 }
 
@@ -736,16 +763,14 @@ export interface IntentActivity {
 }
 
 /**
- * Entry point for Shopify intents.
+ * Invokes built-in Shopify workflows for managing customer account resources. Use the Intents API to trigger native Shopify modals and flows, such as replacing a payment method on a subscription contract, without building the UI yourself.
  *
  * Intents pair an `action` (verb) with a resource `type` and optional `value`
  * and `data` to request a workflow.
  */
 export interface Intents {
   /**
-   * Invoke an intent using the object or URL syntax.
-   *
-   * Object format: `{action, type, value?, data?}`
+   * Triggers a built-in Shopify workflow by passing a structured intent object. Specify an `action` (such as `'open'`), a resource `type`, and an optional `value` identifying the resource. Returns a promise that resolves to an `IntentActivity` you can use to track completion.
    *
    * @param query - Structured intent description, including `action` and `type`.
    * @returns A promise for an {@link IntentActivity} that completes with an
@@ -765,9 +790,9 @@ export interface Intents {
    */
   invoke(query: IntentQuery): Promise<IntentActivity>;
   /**
-   * URL format: `action:type[,value][?params]`
+   * Triggers a built-in Shopify workflow using a URL string in the format `action:type[,value][?params]`. Use this overload when composing intents from dynamic strings rather than structured objects.
    *
-   * @param intentURL - Intent in URL form
+   * @param intentURL - Intent in URL form, such as `'open:shopify/SubscriptionContract,gid://shopify/SubscriptionContract/123'`.
    * @param options - Optional supplemental inputs such as `value` or `data`.
    * @returns A promise for an {@link IntentActivity} that completes with an
    *          {@link IntentResponse}.

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

@@ -30,19 +30,17 @@ export interface ExtensionSettings {
 export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * The identifier that specifies where in Shopify’s UI your code is being
-   * injected. This will be one of the targets you have included in your
-   * extension’s configuration file.
+   * injected. This will be one of the [targets](/docs/api/customer-account-ui-extensions/{API_VERSION}/configuration#targets) you have included in your
+   * extension’s configuration file. For more information, refer to the [extension targets overview](/docs/api/customer-account-ui-extensions/{API_VERSION}/extension-targets-overview).
    *
    * @example 'customer-account.order-status.block.render'
-   * @see https://shopify.dev/docs/api/customer-account-ui-extensions/extension-targets-overview
-   * @see https://shopify.dev/docs/apps/app-extensions/configuration#targets
    *
-   * @deprecated Deprecated as of version `2023-07`, use `extension.target` instead.
+   * @deprecated Use `extension.target` instead.
    */
   extensionPoint: Target;
 
   /**
-   * Meta information about the extension.
+   * Metadata about the extension, including its target, version, and editor context. Use this to conditionally render content based on where the extension is running.
    */
   extension: Extension;
 
@@ -52,82 +50,58 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   authenticatedAccount: AuthenticatedAccount;
 
   /**
-   * The renderer version being used for the extension.
+   * The API version your extension is running against. Use this to conditionally enable features or handle breaking changes when your extension supports multiple API versions.
    *
    * @example 'unstable'
    */
   version: Version;
 
   /**
-   * Details about the language of the buyer.
+   * The buyer's language, country, and locale context. Use this to adapt your extension to the buyer's region and display localized content.
    */
   localization: Localization;
 
   /**
-   * Utilities for translating content and formatting values according to the current `localization`
-   * of the user.
+   * Utilities for translating strings, formatting currencies, numbers, and dates according to the buyer's locale. Use this alongside `localization` to build fully localized extensions.
    */
   i18n: I18n;
 
   /**
-   * Key-value storage for the extension target.
+   * Key-value storage that persists across customer sessions for this extension target. Use this to store preferences, dismiss states, or cached data without requiring a backend call.
    */
   storage: Storage;
 
   /**
-   * Provides access to session tokens, which can be used to verify token claims on your app's server.
-   *
-   * See [session token examples](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/session-token#examples) for more information.
+   * Authenticates requests between your extension and your app backend. Call `get()` to retrieve a signed JWT containing the customer ID, shop domain, and expiration time, then verify it server-side. For more information, refer to the [Session Token API](/docs/api/customer-account-ui-extensions/{API_VERSION}/target-apis/platform-apis/session-token-api).
    */
   sessionToken: SessionToken;
 
   /**
-   * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
+   * Tracks custom events and sends visitor information to [web pixels](/docs/apps/build/marketing-analytics/pixels). Use `publish()` to emit events and `visitor()` to submit visitor data.
    *
-   * > 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.
+   * > Note: Requires [connecting 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;
 
   /**
-   * Entry point for Shopify intents.
-   *
-   * Intents pair an `action` (verb) with a resource `type` and optional `value`
-   * and `data` to request a workflow.
+   * Invokes built-in Shopify workflows for managing customer account resources. Use intents to trigger native modals and flows, such as replacing a payment method on a subscription contract, without building the UI yourself.
    */
   intents: Intents;
 
   /**
-   * The settings matching the settings definition written in the
-   * [`shopify.extension.toml`](/docs/api/customer-account-ui-extensions/{API_VERSION}#configuration) file.
-   *
-   *  See [settings examples](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/order-status-api/settings#examples) for more information.
-   *
-   * > 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.
+   * Merchant-defined configuration values for your extension, as specified in the [settings definition](/docs/api/customer-account-ui-extensions/{API_VERSION}/configuration#settings-definition) of your `shopify.extension.toml` file. Settings update in real time as merchants edit them in the extension editor. The value is empty until a merchant sets it.
    */
   settings: SubscribableSignalLike<ExtensionSettings>;
 
   /**
-   * 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/web-components/feedback/banner) component.
+   * 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](/docs/api/customer-account-ui-extensions/{API_VERSION}/ui-components/feedback-and-status-indicators/banner) component instead.
    */
   toast: ToastApi;
 
   /**
-   * Used to query the Storefront GraphQL API with a prefetched token.
+   * Queries the [Storefront GraphQL API](/docs/api/storefront) directly from your extension using a prefetched token. Use this to fetch product data, collection details, or other storefront information without routing requests through your app backend.
    *
-   * See [storefront api access examples](https://shopify.dev/docs/api/customer-account-ui-extensions/apis/storefront-api#examples) for more information.
+   * Requires the [`api_access` capability](/docs/api/customer-account-ui-extensions/{API_VERSION}/configuration#api-access).
    */
   query: <Data = unknown, Variables = {[key: string]: unknown}>(
     query: string,
@@ -142,7 +116,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Applies updated tracking consent preferences for the buyer, including their decisions for analytics, marketing, and data sale, along with any custom tracking consent [metafields](/docs/apps/build/custom-data/metafields). Returns a promise that resolves with the result of the consent update.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires the [`customer_privacy` capability](/docs/api/customer-account-ui-extensions/latest#configuration) and access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires the [`collect_buyer_consent` capability](/docs/apps/build/customer-accounts/capabilities#collect-buyer-consent) and access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
   applyTrackingConsentChange: ApplyTrackingConsentChangeType;
 }
@@ -169,6 +143,9 @@ export interface OrderApi {
   orderId: string;
 }
 
+/**
+ * The buyer's language, country, and locale context in customer accounts. Properties on this interface are subscribable and update automatically when the buyer changes their country.
+ */
 export interface Localization {
   /**
    * The language the buyer sees in the customer account hub.
@@ -176,22 +153,14 @@ export interface Localization {
   language: SubscribableSignalLike<Language>;
 
   /**
-   * This is the buyer's language, as supported by the extension.
-   * If the buyer's actual language isn't supported by the extension,
-   * this is the fallback locale used for translations.
+   * The buyer's language, as supported by the extension. If the buyer's actual language isn't supported, this falls back to the closest match or the extension's default locale (the one matching your `.default.json` file).
    *
-   * For example, if the buyer's language is 'fr-CA' but your extension
-   * only supports translations for 'fr', then the `isoCode` for this
-   * language is 'fr'. If your extension doesn't provide french
-   * translations at all, this value is the default locale for your
-   * extension (that is, the one matching your .default.json file).
+   * For example, if the buyer's language is `'fr-CA'` but your extension only supports `'fr'`, then `isoCode` is `'fr'`. If your extension doesn't provide French translations at all, this returns the default locale.
    */
   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.
+   * The buyer's country in customer accounts. Updates automatically if the buyer changes their country. The value is `undefined` if the country is unknown.
    */
   country: SubscribableSignalLike<Country | undefined>;
 }
@@ -201,6 +170,9 @@ export interface Localization {
  */
 export type NavigationTypeString = 'push' | 'replace' | 'traverse';
 
+/**
+ * Options passed to `Navigation.navigate()` to control history behavior and attach state to the navigation entry.
+ */
 export interface NavigationNavigateOptions {
   /**
    * Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState().
@@ -213,62 +185,83 @@ export interface NavigationNavigateOptions {
 }
 
 /**
- * The NavigationHistoryEntry interface of the Navigation API represents a single navigation history entry.
+ * A single entry in the navigation history stack. Each entry has a unique key, a URL, and optional developer-defined state.
  */
 export interface NavigationHistoryEntry {
-  /** Returns the key of the history entry. This is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. */
+  /**
+   * A unique, platform-generated identifier for this entry's position in the history stack. This value identifies the slot, not the content.
+   */
   key: string;
   /**
-   * Returns the URL of this history entry.
+   * The URL associated with this history entry, or `null` if unavailable.
    */
   url: string | null;
   /**
-   * Returns a clone of the available state associated with this history entry.
+   * Returns a clone of the developer-defined state associated with this history entry.
    */
   getState(): unknown;
 }
 
+/**
+ * Options for `Navigation.updateCurrentEntry()`. Use this to update the state of the current history entry without triggering a navigation.
+ */
 export interface NavigationUpdateCurrentEntryOptions {
+  /**
+   * Developer-defined state to associate with the current navigation history entry.
+   */
   state: unknown;
 }
 
 /**
- * The NavigationCurrentEntryChangeEvent interface of the Navigation API is the event object for the currententrychange event, which fires when the Navigation.currentEntry has changed.
+ * The event object passed to `currententrychange` listeners when the current navigation entry changes.
  */
 export interface NavigationCurrentEntryChangeEvent {
   /**
-   * Returns the type of the navigation that resulted in the change.
+   * The type of navigation that caused the change: `'push'`, `'replace'`, or `'traverse'`.
    */
   navigationType?: NavigationTypeString;
   /**
-   * Returns the NavigationHistoryEntry that was navigated from.
+   * The history entry the buyer navigated away from.
    */
   from: NavigationHistoryEntry;
 }
 
+/**
+ * Navigates between pages in customer accounts, including other extensions and host pages. Full-page extensions also get access to the current navigation entry and history state.
+ * @publicDocs
+ */
 export interface Navigation {
   /**
-   * The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
+   * Navigates to a URL, updating any provided state in the history entries list. Supports [custom protocols](/docs/api/customer-account-ui-extensions/{API_VERSION}#custom-protocols) for navigating within customer accounts.
    */
   navigate: NavigateFunction;
   /**
-   * The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
+   * The current navigation history entry, representing the page the buyer is viewing. Only available in full-page extensions.
    */
   currentEntry: NavigationHistoryEntry;
   /**
-   * 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.
+   * Updates the state of the current history entry without triggering a navigation. Use this when the state change is independent of a page transition, such as saving form progress.
    */
   updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
+  /**
+   * Registers a listener that fires whenever the current navigation entry changes, such as when the buyer navigates to a different page.
+   */
   addEventListener(
     type: 'currententrychange',
     cb: (event: NavigationCurrentEntryChangeEvent) => void,
   ): void;
+  /**
+   * Removes a previously registered `currententrychange` listener.
+   */
   removeEventListener(
     type: 'currententrychange',
     cb: (event: NavigationCurrentEntryChangeEvent) => void,
   ): void;
 }
 
+/**
+ * A callable function that navigates to a URL within customer accounts. Accepts a destination URL and optional navigation options.
+ */
 export interface NavigateFunction {
   /**
    * Navigates to a specific URL, updating any provided state in the history entries list.
@@ -277,4 +270,7 @@ export interface NavigateFunction {
   (url: string, options?: NavigationNavigateOptions): void;
 }
 
+/**
+ * The API version string your extension is running against, such as `'2026-04-rc'` or `'unstable'`.
+ */
 export type Version = string;