@shopify/ui-extensions 2025.10.14 → 2025.10.15

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

@@ -27,6 +27,10 @@ export interface Metafield {
 
   /**
    * The data stored in the metafield. The format depends on the `valueType`: a plain string for `'string'`, a numeric value for `'integer'`, or a serialized JSON object for `'json_string'`.
+   *
+   * Returned as a string regardless of the metafield's content type. Parse
+   * with `JSON.parse()` for metafields containing JSON or other structured
+   * data.
    */
   value: string | number;
 
@@ -171,6 +175,10 @@ export interface Market {
   handle: string;
 }
 
+/**
+ * Provides raw localization data only. The `i18n` translation and formatting
+ * helpers from the Localization API aren't available on order status targets.
+ */
 export interface OrderStatusLocalization {
   /**
    * The currency used to display money amounts on the **Order status** page. Use this value
@@ -233,7 +241,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
 
   /**
    * The [metafields](/docs/apps/build/custom-data/metafields) requested in the
-   * [`shopify.extension.toml`](/docs/api/customer-account-ui-extensions/latest#configuration)
+   * [`shopify.extension.toml`](/docs/apps/build/customer-accounts/metafields#create-the-metafield-definition)
    * file. Metafields are custom data fields that store additional information on Shopify resources
    * such as products, variants, customers, and the shop. These metafields are updated when there's
    * a change in the merchandise items being purchased by the customer.
@@ -251,12 +259,18 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
 
   /**
    * The buyer who placed the order, including their customer account, email, phone number, and B2B purchasing company. Use this to personalize the **Order status** page or identify B2B orders.
+   *
+   * Reflects the customer account at the time the order was placed. Doesn't
+   * update if account details change afterward.
    */
   buyerIdentity?: OrderStatusBuyerIdentity;
 
   /**
    * The checkout settings that were active when the buyer placed the order, such as
    * whether order notes and login are enabled.
+   *
+   * Returns the merchant's checkout configuration at the time of checkout.
+   * Doesn't reflect updates made after the order was placed.
    */
   checkoutSettings: SubscribableSignalLike<CheckoutSettings>;
 
@@ -278,6 +292,9 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * - `CartCodeDiscountAllocation`: A discount the buyer applied by entering a code at checkout.
    * - `CartAutomaticDiscountAllocation`: A discount the merchant configured in Shopify admin to apply automatically.
    * - `CartCustomDiscountAllocation`: A discount created programmatically by a [Shopify Function](/docs/apps/build/functions).
+   *
+   * Returns order-level discounts only. For per-line discount allocations,
+   * read from individual cart lines via the Cart Lines API.
    */
   discountAllocations: SubscribableSignalLike<CartDiscountAllocation[]>;
 
@@ -290,10 +307,9 @@ export interface OrderStatusApi<Target extends 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.
    *
    * @example 'customer-account.order-status.block.render'
-   * @see /docs/api/customer-account-ui-extensions/extension-targets-overview
-   * @see /docs/apps/app-extensions/configuration#targets
+   * Learn more about [targets](/docs/api/customer-account-ui-extensions/{API_VERSION}/targets) and [target configuration](/docs/api/customer-account-ui-extensions/{API_VERSION}#configuration).
    *
-   * @deprecated Deprecated as of version `2023-07`, use `extension.target` instead.
+   * @deprecated Use `extension.target` instead.
    */
   extensionPoint: Target;
 
@@ -306,7 +322,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * The buyer's locale, currency, time zone, country, and market context for the order.
    * Use these values to adapt your extension's content to the buyer's region. For formatted
-   * dates, numbers, and translated strings, use the [Localization API](/docs/api/customer-account-ui-extensions/target-apis/platform-apis/localization-api)
+   * dates, numbers, and translated strings, use the [Localization API](/docs/api/customer-account-ui-extensions/{API_VERSION}/target-apis/platform-apis/localization-api)
    * instead.
    */
   localization: OrderStatusLocalization;
@@ -332,8 +348,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * The token that identifies the checkout session used to create the order. Use this value
    * to correlate the order with analytics events or backend API calls. This matches the
-   * `token` field in the [WebPixel checkout payload](/docs/api/pixels/customer-events#checkout)
-   * and the `checkout_token` field in the [Admin REST API Order resource](/docs/api/admin-rest/unstable/resources/order#resource-object).
+   * `token` field in the [WebPixel checkout payload](/docs/api/pixels/customer-events#checkout).
    * The value is `undefined` if the checkout token is unavailable.
    */
   checkoutToken: SubscribableSignalLike<CheckoutToken | undefined>;
@@ -342,12 +357,18 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * The shipping address that the buyer provided for the order. This is where physical goods
    * are delivered. The value is `undefined` if the order contains only digital products or
    * if a shipping address wasn't required.
+   *
+   * Reflects the state at the time the order was placed. Doesn't update if the
+   * customer changes their account address afterward.
    */
   shippingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 
   /**
    * The billing address associated with the buyer's payment method for the order. The value
    * is `undefined` if the order doesn't have a billing address on file.
+   *
+   * Reflects the state at the time the order was placed. Doesn't update if the
+   * customer changes their account address afterward.
    */
   billingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 
@@ -367,11 +388,16 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * Triggers a login prompt if the customer is viewing a pre-authenticated **Order status** page.
    * Use this to require full authentication before displaying sensitive information in your extension.
+   *
+   * Triggers a login prompt for pre-authenticated buyers. Doesn't guarantee
+   * the buyer completes the login. Handle the dismissal case in your code.
    */
   requireLogin: () => Promise<void>;
 
   /**
    * The buyer's current authentication level on the **Order status** page. Use this to determine whether to display sensitive information or prompt the buyer to log in.
+   *
+   * Read-only. The authentication level can't be changed programmatically.
    */
   authenticationState: SubscribableSignalLike<AuthenticationState>;
 }
@@ -476,6 +502,9 @@ export interface AppliedGiftCard {
 
   /**
    * The remaining balance of the applied gift card after the order was placed.
+   *
+   * Reflects the remaining amount at the time the order was placed. Doesn't
+   * update if the gift card is used for subsequent purchases.
    */
   balance: Money;
 }
@@ -781,7 +810,7 @@ export interface SelectedPaymentOption {
   /**
    * The handle of the payment option the buyer selected, corresponding to a `PaymentOption.handle` value.
    *
-   * See [availablePaymentOptions](/docs/api/checkout-ui-extensions/apis/payments#standardapi-propertydetail-selectedpaymentoptions).
+   * See [availablePaymentOptions](/docs/api/customer-account-ui-extensions/{API_VERSION}/target-apis/order-apis/payments-api).
    */
   handle: string;
 }
@@ -957,7 +986,7 @@ export interface PaymentTermsTemplate {
    */
   id: string;
   /**
-   * The name of the payment terms translated to the buyer's current language, such as "Net 30" or "Due on receipt". See [localization.language](/docs/api/customer-account-ui-extensions/apis/localization#standardapi-propertydetail-localization).
+   * The name of the payment terms translated to the buyer's current language, such as "Net 30" or "Due on receipt". See [localization.language](/docs/api/customer-account-ui-extensions/{API_VERSION}/apis/localization#properties-propertydetail-localization).
    */
   name: string;
   /**

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

@@ -26,14 +26,7 @@ export {
 };
 
 /**
- * A key-value storage object for extension targets.
- *
- * 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.
+ * Key-value storage that persists across customer sessions for this extension target. Stored data is scoped to your app and can be shared across multiple extension targets. Data persistence isn't guaranteed.
  */
 export interface Storage {
   /**
@@ -59,6 +52,9 @@ export interface Storage {
   delete(key: string): Promise<void>;
 }
 
+/**
+ * The buyer's language, represented as a [BCP-47 standard](https://en.wikipedia.org/wiki/IETF_language_tag) 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,11 +65,11 @@ export interface Language {
 }
 
 /**
- * This defines the i18n.translate() signature.
+ * Translates a key from your extension's locale files into a localized string.
  */
 export interface I18nTranslate {
   /**
-   * This returns a translated string matching a key in a locale file.
+   * Translates a key from your extension's locale files into a localized string. Returns a single string when all replacements are primitives, or an array of elements when replacements include UI components.
    *
    * @example translate("banner.title")
    */
@@ -85,6 +81,9 @@ export interface I18nTranslate {
     : (string | ReplacementType)[];
 }
 
+/**
+ * Utilities for translating strings, formatting currencies, numbers, and dates according to the buyer's locale. Use this alongside `localization` to build fully localized extensions.
+ */
 export interface I18n {
   /**
    * Returns a localized number.
@@ -113,14 +112,7 @@ export interface I18n {
   ) => string;
 
   /**
-   * Returns a localized date value.
-   *
-   * 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
+   * Returns a localized date value. This function behaves like the standard [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) and uses the buyer's locale by default.
    *
    * @param options.inExtensionLocale - if true, use the extension's locale
    */
@@ -142,7 +134,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 +146,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,8 +162,7 @@ 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
@@ -190,11 +178,9 @@ 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.
+   * extension’s configuration file. For available targets, see the [extension targets overview](/docs/api/customer-account-ui-extensions/{API_VERSION}/extension-targets-overview). For configuration details, see [targets](/docs/apps/app-extensions/configuration#targets).
    *
    * @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 +194,9 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   version?: string;
 }
 
+/**
+ * Information about the editor where the extension is being rendered.
+ */
 export interface Editor {
   /**
    * Indicates whether the extension is rendering in the checkout editor.
@@ -240,6 +229,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 +373,40 @@ export interface CompanyLocation {
   id: string;
 }
 
+/**
+ * Authenticates requests between your extension and your app backend by providing signed JWTs.
+ */
 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.
+   * time you need to make a request to your backend 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.
    */
   get(): Promise<string>;
 }
 
+/**
+ * Tracks custom events and sends visitor information to [web pixels](/docs/apps/build/marketing-analytics/pixels).
+ */
 export interface Analytics {
   /**
-   * Publish method to emit analytics events to [Web Pixels](/docs/apps/marketing).
+   * Emits analytics events to [web pixels](/docs/apps/build/marketing-analytics/pixels).
    */
   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 for marketing attribution and analytics.
    */
   visitor(data: {email?: string; phone?: string}): Promise<VisitorResult>;
 }
 /**
- * Represents a visitor result.
+ * The result of a `visitor()` call, indicating whether the visitor information was accepted or rejected.
  */
 export type VisitorResult = VisitorSuccess | VisitorError;
 
 /**
- * Represents a successful visitor result.
+ * Returned when visitor information was validated and submitted successfully.
  */
 export interface VisitorSuccess {
   /**
@@ -418,7 +416,7 @@ export interface VisitorSuccess {
 }
 
 /**
- * Represents an unsuccessful visitor result.
+ * Returned when visitor information is invalid and wasn't submitted.
  */
 export interface VisitorError {
   /**
@@ -568,6 +566,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,9 +606,25 @@ export interface TrackingConsentChangeResultError {
   message: string;
 }
 
+/**
+ * The result returned after a toast is displayed, providing a method to dismiss it.
+ *
+ * @hidden
+ */
 export interface ToastApiResult {
+  /**
+   * Dismisses the toast message from the screen.
+   *
+   * @hidden
+   */
   hide: () => void;
 }
+/**
+ * Displays brief, non-blocking messages at the bottom of the page to confirm actions or report errors.
+ */
 export interface ToastApi {
+  /**
+   * Displays a toast message with the specified content. Returns a promise that resolves with a `ToastApiResult` containing a method to dismiss the toast.
+   */
   show: (content: string) => Promise<ToastApiResult>;
 }

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

@@ -30,18 +30,16 @@ 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.
+   * extension’s configuration file. For available targets, see the [extension targets overview](/docs/api/customer-account-ui-extensions/{API_VERSION}/extension-targets-overview). For configuration details, see [targets](/docs/apps/app-extensions/configuration#targets).
    *
    * @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;
 
@@ -51,74 +49,53 @@ 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. See the [Session Token API](/docs/api/customer-account-ui-extensions/{API_VERSION}/target-apis/platform-apis/session-token-api) for more information.
    */
   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;
 
   /**
-   * 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,
@@ -133,7 +110,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;
 }
@@ -160,6 +137,9 @@ export interface OrderApi {
   orderId: string;
 }
 
+/**
+ * The buyer's language, country, and locale context. Use this to adapt your extension to the buyer's region and display localized content.
+ */
 export interface Localization {
   /**
    * The language the buyer sees in the customer account hub.
@@ -167,22 +147,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 by the extension, this is the fallback locale used for translations.
    *
-   * 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 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).
    */
   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 country the buyer sees in the customer account. Updates when the buyer changes their country. The value is `undefined` if the country is unknown.
    */
   country: SubscribableSignalLike<Country | undefined>;
 }
@@ -192,6 +164,9 @@ export interface Localization {
  */
 export type NavigationTypeString = 'push' | 'replace' | 'traverse';
 
+/**
+ * Options for configuring navigation behavior, including history handling and custom state.
+ */
 export interface NavigationNavigateOptions {
   /**
    * Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState().
@@ -219,6 +194,9 @@ export interface NavigationHistoryEntry {
   getState(): unknown;
 }
 
+/**
+ * Options for updating the state of the current navigation history entry without performing a navigation.
+ */
 export interface NavigationUpdateCurrentEntryOptions {
   state: unknown;
 }
@@ -237,29 +215,42 @@ export interface NavigationCurrentEntryChangeEvent {
   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 specific URL, updating any provided state in the history entries list.
    */
   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 location the user is currently navigated to.
    */
   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 entry without performing a navigation or reload.
    */
   updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
+  /**
+   * Registers a listener that fires when the current history entry changes.
+   */
   addEventListener(
     type: 'currententrychange',
     cb: (event: NavigationCurrentEntryChangeEvent) => void,
   ): void;
+  /**
+   * Removes a previously registered `currententrychange` listener.
+   */
   removeEventListener(
     type: 'currententrychange',
     cb: (event: NavigationCurrentEntryChangeEvent) => void,
   ): void;
 }
 
+/**
+ * A function that navigates to a specific URL, optionally configuring history behavior and custom state.
+ */
 export interface NavigateFunction {
   /**
    * Navigates to a specific URL, updating any provided state in the history entries list.
@@ -268,4 +259,7 @@ export interface NavigateFunction {
   (url: string, options?: NavigationNavigateOptions): void;
 }
 
+/**
+ * The API version string that identifies which version of the extension API is in use.
+ */
 export type Version = string;