@shopify/ui-extensions 2026.4.1 → 2026.4.3

package/src/surfaces/checkout/components/Checkbox.d.ts

@@ -11,21 +11,32 @@
 import type {CheckboxProps$1} from './components-shared.d.ts';
 
 /**
- * Used when an element does not have children.
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+    /**
+     * A unique identifier for this element within its parent. This is used by the rendering engine for efficient reconciliation when lists change.
+     */
     key?: preact.Key;
+    /**
+     * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+     */
     ref?: preact.Ref<TClass>;
+    /**
+     * Assigns the element to a named slot in a parent component that uses slot-based composition patterns.
+     */
     slot?: Lowercase<string>;
 }
 /**
  * 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.
+ * @publicDocs
  */
 export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
     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.
+ * @publicDocs
  */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
@@ -33,9 +44,16 @@ export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap,
 
 declare const tagName = "s-checkbox";
 /** @publicDocs */
-export interface CheckboxElementProps extends Pick<CheckboxProps$1, 'accessibilityLabel' | 'checked' | 'command' | 'commandFor' | 'defaultChecked' | 'disabled' | 'error' | 'id' | 'label' | 'name' | 'required' | 'value'> {
+export interface CheckboxElementProps extends Pick<CheckboxProps$1, 'accessibilityLabel' | 'checked' | 'command' | 'commandFor' | 'defaultChecked' | 'disabled' | 'error' | 'id' | 'name' | 'required' | 'value'> {
     command?: Extract<CheckboxProps$1['command'], '--auto' | '--show' | '--hide' | '--toggle'>;
+    /**
+     * The visual content to use as the control label. Use a string to provide a simple text label displayed to the user.
+     *
+     * If a `label` slot is also provided, the slot content takes precedence. [Learn more about slots](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/checkbox#slots-propertydetail-label).
+     */
+    label?: string;
 }
+/** @publicDocs */
 export interface CheckboxEvents extends Pick<CheckboxProps$1, 'onChange'> {
 }
 /** @publicDocs */
@@ -47,9 +65,20 @@ export interface CheckboxElementEvents {
      */
     change?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface CheckboxElement extends CheckboxElementProps, Omit<HTMLElement, 'id' | 'onchange'> {
     onchange: CheckboxEvents['onChange'];
 }
+/** @publicDocs */
+export interface CheckboxElementSlots {
+    /**
+     * The visual content to use as the control label.
+     *
+     * Use an `HTMLElement` as a rich control label composed of elements. Only an `s-text` element is supported with plain text and `s-link` as its only allowed children. Any other elements are stripped while preserving their text content.
+     */
+    label?: HTMLElement;
+}
+/** @publicDocs */
 export interface CheckboxProps extends CheckboxElementProps, CheckboxEvents {
 }
 declare global {
@@ -65,4 +94,4 @@ declare module 'preact' {
     }
 }
 
-export type { CheckboxElement, CheckboxElementEvents, CheckboxElementProps, CheckboxEvents, CheckboxProps };
+export type { CheckboxElement, CheckboxElementEvents, CheckboxElementProps, CheckboxElementSlots, CheckboxEvents, CheckboxProps };

package/src/surfaces/checkout/components/Clickable.d.ts

@@ -65,6 +65,16 @@ export interface ClickableElementProps extends Pick<ClickableProps$1, 'accessibi
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<ClickableProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
     target?: Extract<ClickableProps$1['target'], 'auto' | '_blank'>;
+    /**
+     * The behavioral type of the clickable component, which determines what action it performs when activated.
+     *
+     * - `submit`: Submits the nearest containing form.
+     * - `button`: Performs no default action, relying on the `click` event handler for behavior.
+     *
+     * This property is ignored if `href` or `commandFor`/`command` is set.
+     *
+     * @default 'button'
+     */
     type?: Extract<ClickableProps$1['type'], 'submit' | 'button'>;
 }
 export interface ClickableEvents extends Pick<ClickableProps$1, 'onBlur' | 'onClick' | 'onFocus'> {

package/src/surfaces/checkout/components/Paragraph.d.ts

@@ -11,7 +11,7 @@
 import type {ParagraphProps$1} from './components-shared.d.ts';
 
 /**
- * Used when an element does not have children.
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
@@ -19,7 +19,8 @@ export interface BaseElementProps<TClass = HTMLElement> {
     slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base properties for elements that have children, extending `BaseElementProps` with children support.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
@@ -31,19 +32,17 @@ export interface ParagraphElementProps extends Pick<ParagraphProps$1, 'accessibi
     color?: Extract<ParagraphProps$1['color'], 'subdued' | 'base'>;
     tone?: Extract<ParagraphProps$1['tone'], 'auto' | 'info' | 'success' | 'warning' | 'critical' | 'neutral' | 'custom'>;
     /**
-     * The semantic type and styling treatment for the paragraph content.
+     * Sets the alignment of the text.
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/text-align
      *
-     * Other presentation properties on `s-paragraph` override the default styling.
-     *
-     * - `paragraph`: A semantic type that indicates the text is a structural grouping of related content.
-     * - `small`: A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand.
-     *
-     * @default 'paragraph'
+     * @default 'auto'
      */
-    type?: Extract<ParagraphProps$1['type'], 'paragraph' | 'small'>;
+    textAlign?: 'start' | 'end' | 'center' | 'auto';
 }
+/** @publicDocs */
 export interface ParagraphElement extends ParagraphElementProps, Omit<HTMLElement, 'id' | 'dir' | 'lang'> {
 }
+/** @publicDocs */
 export interface ParagraphProps extends ParagraphElementProps {
 }
 declare global {

package/src/surfaces/checkout/components/components-shared.d.ts

@@ -822,6 +822,8 @@ interface BadgeProps$1 extends GlobalProps {
 	/**
 	 * An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning. Set to an empty string to display no icon.
 	 *
+	 * Always positioned relative to the text content. Independent positioning isn't supported.
+	 *
 	 * @default ''
 	 */
 	icon?: IconType | AnyString;
@@ -1410,10 +1412,12 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 export interface InteractionProps {
 	/**
 	 * 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).
+	 *
+	 * When both `commandFor` and `href` are set, `commandFor` takes precedence. The command runs and the link doesn't navigate.
 	 */
 	commandFor?: string;
 	/**
-	 * Sets the action the [`command`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this component is activated. Available options:
+	 * Sets the action the `commandFor` target should take when this component is activated. Available options:
 	 *
 	 * - `'--auto'`: Performs the default action appropriate for the target component.
 	 * - `'--show'`: Displays the target component if it's currently hidden.
@@ -1421,7 +1425,7 @@ export interface InteractionProps {
 	 * - `'--toggle'`: Alternates the target component between visible and hidden states.
 	 * - `'--copy'`: Copies the target clipboard item.
 	 *
-	 * The supported actions vary by target component type.
+	 * The supported actions vary by target component type. Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
 	 *
 	 * @default '--auto'
 	 */
@@ -1537,6 +1541,8 @@ export interface MultipleInputProps extends BaseInputProps {
 	 * An array of `value` attributes for the currently selected options.
 	 *
 	 * This is a convenience prop for setting the `selected` prop on child options.
+	 *
+	 * Form data captures the selected value strings only. Complex nested content inside choices is for display purposes and isn't included in form submissions.
 	 */
 	values?: string[];
 }
@@ -1805,6 +1811,8 @@ interface CheckboxProps$1 extends GlobalProps, BaseCheckableProps, FieldErrorPro
 	 * If you want to present an error when this field is empty, you can do
 	 * so with the `error` property.
 	 *
+	 * Adds semantic meaning for accessibility. Doesn't trigger automatic validation or display an error. Implement validation logic yourself and use the `error` prop to show results.
+	 *
 	 * @default false
 	 */
 	required?: boolean;
@@ -1906,6 +1914,8 @@ interface ChoiceListProps$1 extends GlobalProps, Pick<BasicFieldProps, "label" |
 	 * - `block`: The choices are displayed on the block axis.
 	 * - `grid`: The choices are displayed in a grid.
 	 *
+	 * The selected content slot is supported only in the default (stacked) variant. `inline` and `grid` ignore it.
+	 *
 	 * @implementation The `block`, `inline` and `grid` variants are more suitable for button looking choices, but it's at the
 	 * discretion of each surface.
 	 *
@@ -1969,6 +1979,8 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps {
 	 *
 	 * If the chip is not `removable`, it can still be hidden by setting this property.
 	 *
+	 * When using the `removable` variant, keep `hidden` synced with your app state. If `hidden` isn't updated after the chip is removed, the chip can become permanently hidden.
+	 *
 	 * @default false
 	 */
 	hidden?: boolean;
@@ -1993,6 +2005,8 @@ interface ClipboardItemProps$1 extends GlobalProps {
 	/**
 	 * Plain text to be written to the clipboard.
 	 *
+	 * Rich text, HTML, and binary content aren't supported.
+	 *
 	 * @default ''
 	 */
 	text?: string;
@@ -2051,6 +2065,8 @@ export type ConsentPolicy = "sms-marketing";
 interface ConsentCheckboxProps$1 extends GlobalProps, CheckboxProps$1 {
 	/**
 	 * The policy for which user consent is being collected.
+	 *
+	 * Only `sms-marketing` is supported. Other consent policy types aren't available through this component.
 	 */
 	policy?: ConsentPolicy;
 }
@@ -2059,6 +2075,8 @@ interface PhoneFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick<FieldD
 	/**
 	 * The type of phone number to collect. Specific styling may be applied to each type to provide extra guidance to users. No additional validation is performed based on the type.
 	 *
+	 * Styling hint for the input keyboard. Doesn't validate the phone number format. Implement validation in your extension and use the `error` prop to show results.
+	 *
 	 * @default ''
 	 */
 	type?: "mobile" | "";
@@ -2066,6 +2084,8 @@ interface PhoneFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick<FieldD
 interface ConsentPhoneFieldProps$1 extends GlobalProps, PhoneFieldProps$1 {
 	/**
 	 * The policy for which user consent is being collected.
+	 *
+	 * Only `sms-marketing` is supported.
 	 */
 	policy?: ConsentPolicy;
 }
@@ -2119,6 +2139,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 *       So `--2024` is equivalent to `--2024-12-31`.
 	 *     - Whitespace is allowed either side of `--`.
 	 *
+	 * Comma-separated list of allowed dates in `YYYY-MM-DD` format.
+	 *
 	 * @default ""
 	 *
 	 * @example
@@ -2146,6 +2168,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 *       So `--2024` is equivalent to `--2024-12-31`.
 	 *     - Whitespace is allowed either side of `--`.
 	 *
+	 * Comma-separated list of disallowed dates in `YYYY-MM-DD` format.
+	 *
 	 * @default ""
 	 *
 	 * @example
@@ -2210,6 +2234,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format.
 	 * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive.
 	 *
+	 * Single dates use ISO 8601 format (`YYYY-MM-DD`); ranges use `YYYY-MM-DD--YYYY-MM-DD`. Locale-specific formats aren't supported.
+	 *
 	 * @default ""
 	 */
 	value?: string;
@@ -2280,7 +2306,7 @@ interface DividerProps$1 extends GlobalProps {
 	 * The orientation of the divider, using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
 	 *
 	 * - `inline`: A horizontal divider that separates content stacked vertically.
-	 * - `block`: A vertical divider that separates content arranged horizontally.
+	 * - `block`: A vertical divider that separates content arranged horizontally. Requires a parent with a defined height to render visibly.
 	 *
 	 * @default 'inline'
 	 */
@@ -2327,6 +2353,9 @@ interface DropZoneProps$1 extends GlobalProps, FileInputProps, BasicFieldProps {
 	 */
 	onDropRejected?: (event: Event) => void;
 }
+/**
+ * Doesn't perform automatic format validation. Implement validation logic yourself and use the `error` prop to display results.
+ */
 interface EmailFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<EmailAutocompleteField> {
 }
 export type EmailAutocompleteField = ExtractStrict<AnyAutocompleteField, "email" | `${AutocompleteAddressGroup} email`>;

package/src/surfaces/checkout/components/components.d.ts

@@ -115,7 +115,7 @@ export interface ToggleEventProps {
 	 * - If the element transitioned from showing to hidden, the `oldState` property will be set to `open` and the
 	 *   `newState` will be `closed`.
 	 *
-	 * Learn more about [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
+	 * Learn more about [`newState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [`oldState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
 	 */
 	onAfterToggle?: (event: ToggleEvent$1) => void;
 	/**
@@ -126,7 +126,7 @@ export interface ToggleEventProps {
 	 * - If the element is transitioning from showing to hidden, then `oldState` property will be set to `open` and the
 	 *   `newState` will be `closed`.
 	 *
-	 * Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
+	 * Learn more about the [`toggle` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [`newState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [`oldState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
 	 */
 	onToggle?: (event: ToggleEvent$1) => void;
 }
@@ -1390,15 +1390,11 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 }
 export interface InteractionProps {
 	/**
-	 * ID of a component that should respond to activations (e.g. clicks) on this component.
-	 *
-	 * Pair with the `command` property to specify what action to perform on the target component.
-	 *
-	 * @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.
 	 *
@@ -1410,11 +1406,11 @@ export interface InteractionProps {
 	 *
 	 * @default '--auto'
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
+	 * Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
 	 */
 	command?: "--auto" | "--show" | "--hide" | "--toggle" | "--copy";
 	/**
-	 * ID of a component that should respond to interest (e.g. hover and focus) on this component.
+	 * The ID of the component to show when users hover over or focus on this component. Use this to connect interactive components to popovers or tooltips that provide additional context or information.
 	 */
 	interestFor?: string;
 }
@@ -1481,7 +1477,7 @@ export interface BaseInputProps {
 }
 export interface InputProps extends BaseInputProps {
 	/**
-	 * Callback when the user has **finished editing** a field, e.g. once they have blurred the field.
+	 * Callback when the user has **finished editing** a field, such as once they have blurred the field.
 	 *
 	 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
 	 */
@@ -2521,8 +2517,8 @@ export interface BaseTypographyProps {
 	/**
 	 * Indicates the directionality of the element’s text.
 	 *
-	 * - `ltr`: languages written from left to right (e.g. English)
-	 * - `rtl`: languages written from right to left (e.g. Arabic)
+	 * - `ltr`: languages written from left to right (such as English)
+	 * - `rtl`: languages written from right to left (such as Arabic)
 	 * - `auto`: the user agent determines the direction based on the content
 	 * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute)
 	 *

package/src/surfaces/checkout/preact/localized-fields.ts

@@ -38,6 +38,8 @@ export function useLocalizedFields<
 /**
  * Returns the current localized field or undefined for the specified
  * localized field key and re-renders your component if the value changes.
+ *
+ * Returns `undefined` when no field is configured for the buyer's country.
  * @publicDocs
  */
 export function useLocalizedField<

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

@@ -6,7 +6,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

@@ -97,9 +97,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.
    *

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

@@ -157,6 +157,8 @@ export interface Market {
 }
 
 /**
+ * Provides raw localization data only. The `i18n` translation and formatting
+ * helpers from the Localization API aren't available on order status targets.
  * @publicDocs
  */
 export interface OrderStatusLocalization {
@@ -245,12 +247,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>;
 
@@ -272,6 +280,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[]>;
 
@@ -286,7 +297,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * @example 'customer-account.order-status.block.render'
    * 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;
 
@@ -329,12 +340,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>;
 
@@ -354,11 +371,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>;
 }
@@ -470,6 +492,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;
 }
@@ -1002,7 +1027,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/{API_VERSION}/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

@@ -154,12 +154,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/{API_VERSION}/configuration#api-access): the extension can access the Storefront API.
-   *
-   * * [`network_access`](/docs/api/customer-account-ui-extensions/{API_VERSION}/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[]>;
 
@@ -246,6 +242,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;
@@ -618,6 +617,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;
@@ -690,7 +692,7 @@ 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;
   /**
@@ -725,7 +727,7 @@ export interface IntentQuery extends IntentQueryOptions {
    */
   action: IntentAction;
   /**
-   * The resource type (e.g. `shopify/SubscriptionContract`).
+   * The resource type (such as `shopify/SubscriptionContract`).
    */
   type: string;
 }

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

@@ -37,7 +37,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    *
    * @example 'customer-account.order-status.block.render'
    *
-   * @deprecated Deprecated as of version `2023-07`, use `extension.target` instead.
+   * @deprecated Use `extension.target` instead.
    */
   extensionPoint: Target;
 
@@ -118,7 +118,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/{API_VERSION}/configuration#collect-buyer-consent) 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;
 }

package/src/surfaces/customer-account/components/Avatar.d.ts

@@ -18,6 +18,8 @@ export type CallbackEventListener<
 export interface AvatarElementProps extends IdProps {
   /**
    * The initials to display in the avatar when no image is provided or fails to load. Typically one or two characters representing a person's first and last name initials, such as "JD" for John Doe.
+   *
+   * Characters beyond the first two might be truncated. Special characters, emojis, and non-Latin scripts might not render as expected.
    */
   initials?: string;
 

package/src/surfaces/point-of-sale/components/components-shared.d.ts

@@ -1380,27 +1380,21 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 /** @publicDocs */
 export interface InteractionProps {
   /**
-   * 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. Available options:
    *
-   * See the documentation of particular components for the actions they support.
+   * - `'--auto'`: Performs the default action appropriate for the target component.
+   * - `'--show'`: Displays the target component if it's currently hidden.
+   * - `'--hide'`: Conceals the target component from view.
+   * - `'--toggle'`: Alternates the target component between visible and hidden states.
+   * - `'--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.
+   * The supported actions vary by target component type. 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';
   /**

package/src/surfaces/point-of-sale/components.d.ts

@@ -5469,7 +5469,7 @@ interface LinkEvents {
 /**
  * The link component makes text interactive, allowing users to trigger actions through tappable text. Use it for lightweight interactions, navigation triggers, or actions embedded within text content.
  *
- * Links support the command system for controlling other components declaratively. Use `command` and `commandFor` to show, hide, or toggle modals and other targetable elements. For primary actions like submitting forms or triggering operations, use [button](/docs/api/pos-ui-extensions/{API_VERSION}/polaris-web-components/actions/button) instead.
+ * Links support the command system for controlling other components declaratively. Use `command` and `commandFor` to show, hide, or toggle modals and other targetable elements. For primary actions like submitting forms or triggering operations, use [button](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/actions/button) instead.
  * @publicDocs
  */
 interface Link {
@@ -6589,7 +6589,7 @@ interface ModalSlots {
  *
  * Modals block interaction with the underlying interface until the merchant resolves the modal content.
  *
- * Modals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through [events](/docs/api/pos-ui-extensions/{API_VERSION}/polaris-web-components/feedback-and-status-indicators/modal#events).
+ * Modals don't automatically handle state management or persistence, so manage visibility and lifecycle programmatically through [events](/docs/api/pos-ui-extensions/{API_VERSION}/web-components/feedback-and-status-indicators/modal#events).
  * @publicDocs
  */
 interface Modal {