@shopify/ui-extensions 2026.1.3 → 2026.1.4

package/src/surfaces/checkout/preact/shop.ts

@@ -5,6 +5,7 @@ import {useApi} from './api';
 
 /**
  * Returns the `Shop` where the checkout is taking place.
+ * @publicDocs
  */
 export function useShop<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

package/src/surfaces/checkout/preact/storage.ts

@@ -10,6 +10,7 @@ import {useApi} from './api';
  *
  * Data is shared across all activated extension targets of this extension. In versions `<=2023-07`,
  * each activated extension target had its own storage.
+ * @publicDocs
  */
 export function useStorage<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

package/src/surfaces/checkout/preact/subscription.ts

@@ -13,6 +13,7 @@ type Subscriber<T> = Parameters<SubscribableSignalLike<T>['subscribe']>[0];
  * > As of version 2025-10, you no longer need this hook. When you access `.value`
  * > (instead of `.current`) on subscribable properties, Preact will automatically
  * > re-render as `.value` changes.
+ * @publicDocs
  */
 export function useSubscription<Value>(
   subscription: SubscribableSignalLike<Value>,

package/src/surfaces/checkout/preact/target.ts

@@ -23,6 +23,7 @@ class ExtensionHasNoTargetError extends Error {
  * > Caution: Deprecated as of version `2023-10`, use `useCartLineTarget()` instead.
  *
  * @deprecated Deprecated as of version `2023-10`, use `useCartLineTarget()` instead.
+ * @publicDocs
  */
 export function useTarget(): CartLine {
   const api = useApi<

package/src/surfaces/checkout/preact/timezone.ts

@@ -7,6 +7,7 @@ import {useSubscription} from './subscription';
 /**
  * Returns the time zone of the checkout, and automatically re-renders
  * your component if the time zone changes.
+ * @publicDocs
  */
 export function useTimezone<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

package/src/surfaces/checkout/preact/translate.ts

@@ -5,6 +5,7 @@ import {useApi} from './api';
 
 /**
  * Returns the `I18nTranslate` interface used to translate strings.
+ * @publicDocs
  */
 export function useTranslate<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

package/src/surfaces/checkout/shared.ts

@@ -78,6 +78,7 @@ export type PrivateComponent = 'Chat';
 
 export type ThankYouComponent = 'Announcement';
 
+/** @publicDocs */
 export type AnyComponent =
   | (typeof SUPPORTED_COMPONENTS)[number]
   | PrivateComponent;
@@ -99,8 +100,8 @@ export type AnyCheckoutComponentExcept<Except extends AnyCheckoutComponent> =
  */
 export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> {
   /**
-   * The current value of the signal. This property provides synchronous access to the
-   * latest value without subscribing to changes.
+   * The current value of the signal. Equivalent to `.value`, accessing this property
+   * subscribes to changes when used in a reactive context.
    *
    * @deprecated Use `.value` instead.
    */

package/src/surfaces/checkout/style/style.ts

@@ -88,6 +88,7 @@ const when: WhenFunction = function when<
 
 // This interface is only used to provide documentation for the Style helper.
 // It is not used in the implementation.
+/** @publicDocs */
 export interface DocsStyle {
   /**
    * Sets an optional default value to use when no other condition is met.

package/src/surfaces/checkout/style/types.ts

@@ -110,8 +110,6 @@ export interface ConditionalStyle<
 /**
  * A type that represents a value that can be a conditional style.
  * We highly recommend using the `Style` helper which simplifies the creation of conditional styles.
- *
- * To learn more check out the [conditional styles](/api/checkout-ui-extensions/components/utilities/stylehelper) documentation.
  */
 export type MaybeConditionalStyle<
   T,
@@ -121,8 +119,6 @@ export type MaybeConditionalStyle<
 /**
  * A type that represents a value that can be a conditional style. The conditions are based on the viewport size.
  * We highly recommend using the `Style` helper which simplifies the creation of conditional styles.
- *
- * To learn more check out the [conditional styles](/api/checkout-ui-extensions/components/utilities/stylehelper) documentation.
  */
 export type MaybeResponsiveConditionalStyle<T> =
   | T

package/src/surfaces/customer-account/api/cart-line/cart-line-item.ts

@@ -3,7 +3,7 @@ import {SubscribableSignalLike} from '../shared';
 
 export interface CartLineItemApi {
   /**
-   * The cart line the extension is attached to.
+   * The cart line that this extension is attached to. Use this to read the line item's merchandise, quantity, cost, and attributes.
    */
   target: SubscribableSignalLike<CartLine>;
 }

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

@@ -2,6 +2,9 @@ import {OrderStatusApi} from './order-status/order-status';
 import {StandardApi} from './standard-api/standard-api';
 import {CartLineItemApi} from './cart-line/cart-line-item';
 
+/**
+ * An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.
+ */
 export type CallbackEvent<
   TTagName extends keyof HTMLElementTagNameMap,
   TEvent extends Event = Event,
@@ -9,6 +12,9 @@ export type CallbackEvent<
   currentTarget: HTMLElementTagNameMap[TTagName];
 };
 
+/**
+ * A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.
+ */
 export type CallbackEventListener<
   TTagName extends keyof HTMLElementTagNameMap,
   TEvent extends Event = Event,
@@ -29,27 +35,21 @@ interface ButtonProps {
    */
   accessibilityLabel?: string;
   /**
-   * ID of a component that should respond to activations (e.g. clicks) on this component.
-   *
-   * See `command` for how to control the behavior of the target.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor
+   * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
    */
   commandFor?: string;
   /**
-   * Sets the action the `commandFor` should take when this clickable is activated.
+   * Sets the action the `commandFor` target should take when this component is activated.
    *
-   * See the documentation of particular components for the actions they support.
+   * - `--auto`: A default action for the target component.
+   * - `--show`: Shows the target component.
+   * - `--hide`: Hides the target component.
+   * - `--toggle`: Toggles the target component.
+   * - `--copy`: Copies the target clipboard item.
    *
-   * - `--auto`: a default action for the target component.
-   * - `--show`: shows the target component.
-   * - `--hide`: hides the target component.
-   * - `--toggle`: toggles the target component.
-   * - `--copy`: copies the target ClipboardItem.
+   * Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
    *
    * @default '--auto'
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
    */
   command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy';
   /**
@@ -76,7 +76,7 @@ interface ButtonProps {
    */
   loading?: boolean;
   /**
-   * Specifies where to display the linked URL
+   * Specifies where to display the linked URL.
    * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target
    *
    * 'auto' - The target is automatically determined based on the origin of the URL. Surfaces can set specific rules on how they handle each URL.
@@ -95,9 +95,8 @@ interface ButtonProps {
   /**
    * The behavior of the button.
    *
-   * - `'submit'` - Used to indicate the component acts as a submit button, meaning it submits the closest form.
-   * - `'button'` - Used to indicate the component acts as a button, meaning it has no default action.
-   * - `'reset'` - Used to indicate the component acts as a reset button, meaning it resets the closest form (returning fields to their default values).
+   * - `'submit'`: Submits the nearest containing form.
+   * - `'button'`: Performs no default action, relying on the `click` event handler for behavior.
    *
    * This property is ignored if the component supports `href` or `commandFor`/`command` and one of them is set.
    *
@@ -120,92 +119,189 @@ interface ButtonProps {
   click?: ((event: CallbackEventListener<typeof buttonTagName>) => void) | null;
 }
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_MetafieldsApi
   extends Pick<OrderStatusApi<any>, 'appMetafields' | 'metafields'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_AttributesApi
   extends Pick<OrderStatusApi<any>, 'attributes'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_BuyerIdentityApi
   extends Pick<OrderStatusApi<any>, 'buyerIdentity'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_CheckoutSettingsApi
   extends Pick<OrderStatusApi<any>, 'checkoutSettings'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_CostApi
   extends Pick<OrderStatusApi<any>, 'cost'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_LocalizationApi
   extends Pick<OrderStatusApi<any>, 'localization'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_DiscountsApi
   extends Pick<OrderStatusApi<any>, 'discountAllocations' | 'discountCodes'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_GiftCardsApi
   extends Pick<OrderStatusApi<any>, 'appliedGiftCards'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_NoteApi
   extends Pick<OrderStatusApi<any>, 'note'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_AddressApi
   extends Pick<OrderStatusApi<any>, 'shippingAddress' | 'billingAddress'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_ShopApi
   extends Pick<OrderStatusApi<any>, 'shop'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_RequireLoginApi
   extends Pick<OrderStatusApi<any>, 'requireLogin'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_AuthenticationStateApi
   extends Pick<OrderStatusApi<any>, 'authenticationState'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_CartLinesApi
   extends Pick<OrderStatusApi<any>, 'lines'> {}
 
+/**
+ * The API object provided to `customer-account.order-status.cart-line-item.render-after` extension targets for interacting with individual cart line items.
+ * @publicDocs
+ */
 export interface Docs_CartLineItem_CartLinesApi
   extends Pick<CartLineItemApi, 'target'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderStatus_OrderApi
   extends Pick<OrderStatusApi<any>, 'order'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_Standard_ExtensionApi
   extends Pick<StandardApi<any>, 'extension'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_Standard_AuthenticatedAccountApi
   extends Pick<StandardApi<any>, 'authenticatedAccount'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_Standard_VersionApi
   extends Pick<StandardApi<any>, 'version'> {}
 
+/**
+ * The base API object provided to this and other `customer-account` extension targets.
+ * @publicDocs
+ */
 export interface Docs_Standard_LocalizationApi
   extends Pick<StandardApi<any>, 'localization' | 'i18n'> {}
 
+/**
+ * The base API object provided to this and other `customer-account` extension targets.
+ * @publicDocs
+ */
 export interface Docs_Standard_SessionTokenApi
   extends Pick<StandardApi<any>, 'sessionToken'> {}
 
+/**
+ * The base API object provided to this and other `customer-account` extension targets.
+ * @publicDocs
+ */
 export interface Docs_Standard_AnalyticsApi
   extends Pick<StandardApi<any>, 'analytics'> {}
 
+/**
+ * The base API object provided to this and other `customer-account` extension targets.
+ * @publicDocs
+ */
 export interface Docs_Standard_SettingsApi
   extends Pick<StandardApi, 'settings'> {}
 
+/**
+ * The base API object provided to this and other `customer-account` extension targets.
+ * @publicDocs
+ */
 export interface Docs_Standard_StorageApi
   extends Pick<StandardApi<any>, 'storage'> {}
 
+/**
+ * The base API object provided to this and other `customer-account` extension targets.
+ * @publicDocs
+ */
 export interface Docs_Standard_CustomerPrivacyApi
   extends Pick<
     StandardApi<any>,
     'customerPrivacy' | 'applyTrackingConsentChange'
   > {}
 
+/**
+ * The base API object provided to this and other `customer-account` extension targets.
+ * @publicDocs
+ */
 export interface Docs_Standard_ToastApi
   extends Pick<StandardApi<any>, 'toast'> {}
 
+/**
+ * The base API object provided to this and other `customer-account` extension targets.
+ * @publicDocs
+ */
 export interface Docs_Standard_QueryApi
   extends Pick<StandardApi<any>, 'query'> {}
 
+/**
+ * The base API object provided to this and other `customer-account` extension targets.
+ * @publicDocs
+ */
 export interface Docs_StandardApi extends Omit<StandardApi<any>, 'router'> {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_Page_Button_PrimaryAction
   extends Pick<
     ButtonProps,
@@ -216,7 +312,52 @@ export interface Docs_Page_Button_PrimaryAction
     | 'href'
     | 'command'
     | 'commandFor'
-  > {}
+  > {
+  /**
+   * A label that describes the button's purpose to assistive technologies. Use this when the button text alone doesn't provide enough context.
+   */
+  accessibilityLabel?: ButtonProps['accessibilityLabel'];
+  /**
+   * A callback that fires when the button is activated, before the action indicated by `type`.
+   */
+  click?: ButtonProps['click'];
+  /**
+   * The action the `commandFor` target should take when this button is activated.
+   *
+   * - `--auto`: A default action for the target component.
+   * - `--show`: Shows the target component.
+   * - `--hide`: Hides the target component.
+   * - `--toggle`: Toggles the target component.
+   * - `--copy`: Copies the target ClipboardItem.
+   *
+   * @default '--auto'
+   */
+  command?: ButtonProps['command'];
+  /**
+   * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
+   */
+  commandFor?: ButtonProps['commandFor'];
+  /**
+   * Whether the button is disabled and non-interactive.
+   *
+   * @default false
+   */
+  disabled?: ButtonProps['disabled'];
+  /**
+   * The URL to navigate to when the button is activated. If a `commandFor` is set, the `command` is executed instead of the navigation.
+   */
+  href?: ButtonProps['href'];
+  /**
+   * Whether to replace the button content with a loading indicator.
+   *
+   * @default false
+   */
+  loading?: ButtonProps['loading'];
+}
+
+/**
+ * @publicDocs
+ */
 export interface Docs_Page_Button_SecondaryAction
   extends Pick<
     ButtonProps,
@@ -227,22 +368,81 @@ export interface Docs_Page_Button_SecondaryAction
     | 'href'
     | 'command'
     | 'commandFor'
-  > {}
+  > {
+  /**
+   * A label that describes the button's purpose to assistive technologies. Use this when the button text alone doesn't provide enough context.
+   */
+  accessibilityLabel?: ButtonProps['accessibilityLabel'];
+  /**
+   * A callback that fires when the button is activated, before the action indicated by `type`.
+   */
+  click?: ButtonProps['click'];
+  /**
+   * The action the `commandFor` target should take when this button is activated.
+   *
+   * - `--auto`: A default action for the target component.
+   * - `--show`: Shows the target component.
+   * - `--hide`: Hides the target component.
+   * - `--toggle`: Toggles the target component.
+   * - `--copy`: Copies the target ClipboardItem.
+   *
+   * @default '--auto'
+   */
+  command?: ButtonProps['command'];
+  /**
+   * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
+   */
+  commandFor?: ButtonProps['commandFor'];
+  /**
+   * Whether the button is disabled and non-interactive.
+   *
+   * @default false
+   */
+  disabled?: ButtonProps['disabled'];
+  /**
+   * The URL to navigate to when the button is activated. If a `commandFor` is set, the `command` is executed instead of the navigation.
+   */
+  href?: ButtonProps['href'];
+  /**
+   * Whether to replace the button content with a loading indicator.
+   *
+   * @default false
+   */
+  loading?: ButtonProps['loading'];
+}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_Page_Button_BreadcrumbAction
   extends Pick<ButtonProps, 'click' | 'href'> {
   /**
-   * A label used for buyers using assistive technologies. Needed because `children` passed to this component will be discarded.
+   * A label that describes the breadcrumb's destination to assistive technologies. Required because `children` passed to this button are discarded.
    */
   accessibilityLabel: ButtonProps['accessibilityLabel'];
+  /**
+   * A callback that fires when the breadcrumb is activated.
+   */
+  click?: ButtonProps['click'];
+  /**
+   * The URL to navigate to when the breadcrumb is activated.
+   */
+  href?: ButtonProps['href'];
 }
 
+/**
+ * The menu component exclusively accepts button elements with restricted props as its children. The `tone` prop will always be set to monochrome by default.
+ * @publicDocs
+ */
 export interface Docs_Menu_Button_Action
   extends Omit<
     ButtonProps,
     'variant' | 'textDecoration' | 'inlineAlignment' | 'inlineSize' | 'size'
   > {}
 
+/**
+ * @publicDocs
+ */
 export interface Docs_OrderActionMenu_Button
   extends Pick<
     ButtonProps,
@@ -256,6 +456,10 @@ export interface Docs_OrderActionMenu_Button
   href: ButtonProps['href'];
 }
 
+/**
+ * Supported props for Buttons used inside CustomerAccountAction slots.<br><br>`children` only support text.
+ * @publicDocs
+ */
 export interface Docs_CustomerAccountAction_SlotButton
   extends Pick<
     ButtonProps,

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

@@ -29,6 +29,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;
 
@@ -173,6 +177,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
@@ -235,7 +243,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.
@@ -253,12 +261,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>;
 
@@ -280,6 +294,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[]>;
 
@@ -292,10 +309,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;
 
@@ -308,7 +324,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;
@@ -336,8 +352,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>;
@@ -346,12 +361,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>;
 
@@ -371,11 +392,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>;
 }
@@ -480,6 +506,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;
 }
@@ -785,7 +814,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;
 }
@@ -961,7 +990,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;
   /**