@shopify/ui-extensions 2026.4.2 → 2026.4.4

package/src/surfaces/checkout/api/address-autocomplete/standard.ts

@@ -88,7 +88,7 @@ export interface AddressAutocompleteStandardApi<
   /**
    * The details about the location, language, and currency of the customer. For utilities to easily
    * format and translate content based on these details, you can use the
-   * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#standardapi-propertydetail-i18n)
+   * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#properties-propertydetail-i18n)
    * object instead.
    */
   localization: Localization;

package/src/surfaces/checkout/api/address-autocomplete/suggest.ts

@@ -56,8 +56,8 @@ interface Target {
 export interface AddressAutocompleteSuggestOutput {
   /**
    * An array of address autocomplete suggestions to show to the buyer.
-   *
-   * > Note: Only the first five suggestions will be displayed to the buyer.
+   * Checkout displays up to five address suggestions. Return no more
+   * than five. Additional suggestions are ignored.
    */
   suggestions: AddressAutocompleteSuggestion[];
 }

package/src/surfaces/checkout/api/cart-line/cart-line-item.ts

@@ -7,6 +7,10 @@ export interface CartLineItemApi {
    * The cart line that this extension is attached to. Use this to read the
    * line item's merchandise, quantity, cost, and attributes.
    *
+   * Available only on the corresponding item target. Shipping option item
+   * targets expose shipping option properties; pickup location item targets
+   * expose pickup location properties.
+   *
    * > Note: Until version `2023-04`, this property was a `ReadonlySignalLike<PresentmentCartLine>`.
    */
   target: SubscribableSignalLike<CartLine>;

package/src/surfaces/checkout/api/checkout/checkout.ts

@@ -61,6 +61,9 @@ export interface NoteChangeResultError {
   /**
    * A message that explains the error. This message is useful for debugging.
    * It isn't localized and shouldn't be displayed to the buyer.
+   *
+   * Render your own localized error text rather than displaying this message
+   * to the buyer.
    */
   message: string;
 }
@@ -176,6 +179,9 @@ export interface CartLineChangeResultError {
   /**
    * A message that explains the error. This message is useful for debugging.
    * It isn't localized and shouldn't be displayed to the buyer.
+   *
+   * Render your own localized error text rather than displaying this message
+   * to the buyer.
    */
   message: string;
 }
@@ -450,6 +456,9 @@ export interface GiftCardChangeResultError {
   /**
    * A message that explains the error. This message is useful for debugging.
    * It isn't localized and shouldn't be displayed to the buyer.
+   *
+   * Render your own localized error text rather than displaying this message
+   * to the buyer.
    */
   message: string;
 }
@@ -541,6 +550,9 @@ export interface MetafieldChangeResultError {
   /**
    * A message that explains the error. This message is useful for debugging.
    * It isn't localized and shouldn't be displayed to the buyer.
+   *
+   * Render your own localized error text rather than displaying this message
+   * to the buyer.
    */
   message: string;
 }
@@ -642,35 +654,41 @@ export type ShippingAddressChangeResult =
 export interface CheckoutApi {
   /**
    * Updates or removes an attribute on the cart and checkout. On success, the
-   * [`attributes`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/attributes#standardapi-propertydetail-attributes) property updates to reflect the change.
+   * [`attributes`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/attributes#properties-propertydetail-attributes) property updates to reflect the change.
    *
-   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#standardapi-propertydetail-instructions) `attributes.canUpdateAttributes` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `attributes.canUpdateAttributes` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    *
    * @deprecated Use cart metafields instead.
    */
   applyAttributeChange(change: AttributeChange): Promise<AttributeChangeResult>;
 
   /**
-   * Adds, removes, or updates line items in the cart. The returned promise resolves when the change has been applied by the server, and the [`lines`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-lines#standardapi-propertydetail-lines) property updates with the new state.
+   * Adds, removes, or updates line items in the cart. The returned promise resolves when the change has been applied by the server, and the [`lines`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-lines#properties-propertydetail-lines) property updates with the new state.
+   *
+   * Accepts a single change per call. To make multiple changes, call this
+   * method separately for each one.
    *
-   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#standardapi-propertydetail-instructions) `lines.canAddCartLine` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `lines.canAddCartLine` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    */
   applyCartLinesChange(change: CartLineChange): Promise<CartLineChangeResult>;
 
   /**
-   * Adds or removes a discount code on the checkout. The returned promise resolves when the change has been applied by the server, and the [`discountCodes`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/discounts#standardapi-propertydetail-discountcodes) property updates with the new state.
+   * Adds or removes a discount code on the checkout. The returned promise resolves when the change has been applied by the server, and the [`discountCodes`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/discounts#properties-propertydetail-discountcodes) property updates with the new state.
    *
    * > Caution:
    * > See [security considerations](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#network-access) if your extension retrieves discount codes through a network call.
    *
-   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#standardapi-propertydetail-instructions) `discounts.canUpdateDiscountCodes` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `discounts.canUpdateDiscountCodes` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    */
   applyDiscountCodeChange(
     change: DiscountCodeChange,
   ): Promise<DiscountCodeChangeResult>;
 
   /**
-   * Adds or removes a gift card from the checkout. The returned promise resolves when the change has been applied by the server, and the [`appliedGiftCards`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/gift-cards#standardapi-propertydetail-appliedgiftcards) property updates with the new state.
+   * Adds or removes a gift card from the checkout. The returned promise resolves when the change has been applied by the server, and the [`appliedGiftCards`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/gift-cards#properties-propertydetail-appliedgiftcards) property updates with the new state.
+   *
+   * Unlike other write operations, gift card changes aren't gated by a cart
+   * instruction flag.
    *
    * > Caution:
    * > See [security considerations](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#network-access) if your extension retrieves gift card codes through a network call.
@@ -681,20 +699,20 @@ export interface CheckoutApi {
 
   /**
    * Creates, updates, or removes a cart metafield on the checkout. On success, the
-   * [`metafields`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/metafields#standardapi-propertydetail-metafields) property updates to reflect the change.
+   * [`metafields`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/metafields#properties-propertydetail-metafields) property updates to reflect the change.
    *
    * Cart metafields are copied to order metafields at order creation time if there's a matching order metafield definition with the [`cart to order copyable`](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#cart-to-order-copyable) capability enabled.
    *
-   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#standardapi-propertydetail-instructions) `metafields.canSetCartMetafields` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `metafields.canSetCartMetafields` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    */
   applyMetafieldChange(change: MetafieldChange): Promise<MetafieldChangeResult>;
 
   /**
    * Sets or removes the buyer's note on the checkout. On success, the
-   * [`note`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/note#standardapi-propertydetail-note)
+   * [`note`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/note#properties-propertydetail-note)
    * property updates to reflect the change.
    *
-   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#standardapi-propertydetail-instructions) `notes.canUpdateNote` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `notes.canUpdateNote` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    */
   applyNoteChange(change: NoteChange): Promise<NoteChangeResult>;
 
@@ -708,7 +726,7 @@ export interface CheckoutApi {
    * are merged into the existing address without prompting the buyer. On success,
    * the `shippingAddress` property updates to reflect the change.
    *
-   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#standardapi-propertydetail-instructions) `delivery.canSelectCustomAddress` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
+   * > Note: This method returns an error if the [cart instruction](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#properties-propertydetail-instructions) `delivery.canSelectCustomAddress` is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    */

package/src/surfaces/checkout/api/order-confirmation/order-confirmation.ts

@@ -16,6 +16,8 @@ export interface OrderConfirmation {
    * A randomly generated alpha-numeric identifier for the order, distinct
    * from `order.id`. The value is `undefined` for orders that were created
    * before this field was introduced. All recent orders have a number.
+   *
+   * Optional. Might not be present for orders created before 2024.
    */
   number?: string;
 

package/src/surfaces/checkout/api/pickup/pickup-location-item.ts

@@ -5,11 +5,19 @@ import type {PickupLocationOption} from '../standard/standard';
 export interface PickupLocationItemApi {
   /**
    * The pickup location that this extension is attached to. Use this to read the location's name, address, and other details.
+   *
+   * Available only on the corresponding item target. Shipping option item
+   * targets expose shipping option properties; pickup location item targets
+   * expose pickup location properties.
    */
   target: SubscribableSignalLike<PickupLocationOption>;
 
   /**
    * Whether the buyer has selected the target pickup location. When `true`, the target location is the buyer's active choice. When `false`, the buyer has chosen a different pickup location.
+   *
+   * Available only on the corresponding item target. Shipping option item
+   * targets expose shipping option properties; pickup location item targets
+   * expose pickup location properties.
    */
   isTargetSelected: SubscribableSignalLike<boolean>;
 }

package/src/surfaces/checkout/api/pickup/pickup-point-list.ts

@@ -3,9 +3,9 @@ import type {SubscribableSignalLike} from '../../shared';
 /** @publicDocs */
 export interface PickupPointListApi {
   /**
-   * Whether the location search form is currently visible to the buyer.
-   * Use this to conditionally render UI that depends on the buyer actively
-   * searching for pickup points.
+   * Reflects which view was active when the extension loaded. When the
+   * buyer moves to the next view, the extension restarts with the
+   * current value rather than updating in place.
    */
   isLocationFormVisible: SubscribableSignalLike<boolean>;
 }

package/src/surfaces/checkout/api/shared.ts

@@ -59,6 +59,9 @@ export interface Attribute {
    * The value associated with the attribute key. This is a freeform string
    * that can store any information the buyer or app provides.
    *
+   * Attribute values are always strings. To store structured data, serialize
+   * it to JSON and parse it when reading.
+   *
    * @example 'Please use red wrapping paper'
    */
   value: string;

package/src/surfaces/checkout/api/shipping/shipping-option-item.ts

@@ -5,11 +5,19 @@ import type {ShippingOption} from '../standard/standard';
 export interface ShippingOptionItemApi {
   /**
    * The shipping option that this extension is attached to. Use this to read the option's cost, carrier, delivery estimate, and other details.
+   *
+   * Available only on the corresponding item target. Shipping option item
+   * targets expose shipping option properties; pickup location item targets
+   * expose pickup location properties.
    */
   target: SubscribableSignalLike<ShippingOption>;
 
   /**
    * Whether the buyer has selected the target shipping option. When `true`, the target option is the buyer's active choice. When `false`, the buyer has chosen a different shipping option.
+   *
+   * Available only on the corresponding item target. Shipping option item
+   * targets expose shipping option properties; pickup location item targets
+   * expose pickup location properties.
    */
   isTargetSelected: SubscribableSignalLike<boolean>;
 

package/src/surfaces/checkout/api/standard/standard.ts

@@ -35,7 +35,8 @@ export interface Storage {
    * The stored data is deserialized from JSON and returned as
    * its original type.
    *
-   * Returns `null` if no stored data exists.
+   * Returns the stored value for the given key, or `null` when no value
+   * exists. Doesn't throw on a missing key.
    */
   read<T = unknown>(key: string): Promise<T | null>;
 
@@ -66,20 +67,8 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   apiVersion: ApiVersion;
 
   /**
-   * The allowed capabilities of the extension, defined
-   * in your [shopify.extension.toml](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration) file.
-   *
-   * * [`api_access`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#api-access): the extension can access the Storefront API.
-   *
-   * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#network-access): the extension can make external network calls.
-   *
-   * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#block-progress): the extension can block a customer's progress and the merchant has allowed this blocking behavior.
-   *
-   * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#collect-buyer-consent): the extension can collect customer consent for SMS marketing.
-   *
-   * * [`collect_buyer_consent.customer_privacy`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#collect-buyer-consent): the extension can register customer consent decisions that are honored on Shopify-managed services.
-   *
-   * * [`iframe.sources`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#iframe): the extension can embed an external URL in an iframe.
+   * The allowed capabilities of the extension, defined in your
+   * [`shopify.extension.toml`](/docs/api/checkout-ui-extensions/{API_VERSION}/configuration) file.
    */
   capabilities: SubscribableSignalLike<Capability[]>;
 
@@ -124,6 +113,9 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    *
    * For unpublished extensions, the value is `undefined`.
    *
+   * Don't use this property as a stable identifier in development environments.
+   * It becomes available only after the extension is published.
+   *
    * @example 3.0.10
    */
   version?: string;
@@ -435,15 +427,21 @@ export interface Localization {
 
   /**
    * The country context of the checkout, carried over from the cart. It updates when the buyer changes their shipping address country. Use this value to display region-specific content such as local support information or regional policies. The value is `undefined` if the buyer's country is unknown.
+   *
+   * Derived from the buyer's shipping address. Returns `undefined` until the
+   * buyer enters a shipping address.
    */
   country: SubscribableSignalLike<Country | undefined>;
 
   /**
-   * The [market](https://shopify.dev/docs/apps/build/markets) context of the checkout, carried over from the cart context. Markets group countries and regions with shared pricing, languages, and domains. It updates when the buyer changes the country of their shipping address. The value is `undefined` if the market is unknown.
-   *
-   * > Caution: Deprecated as of version `2025-04`. Merchants now manage which extensions load for each market, so extensions no longer need to check this value.
+   * The [market](/docs/apps/build/markets) context of the checkout,
+   * carried over from the cart context. Markets group countries and
+   * regions with shared pricing, languages, and domains. The market
+   * context updates when the buyer changes the country of their
+   * shipping address. The value is `undefined` if the market is unknown.
    *
-   * @deprecated Deprecated as of version `2025-04`
+   * @deprecated Merchants now manage which extensions load for each
+   * market, so extensions no longer need to check this value.
    */
   market: SubscribableSignalLike<Market | undefined>;
 }
@@ -587,8 +585,10 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    * For example, if you intend to add a discount code via the `applyDiscountCodeChange` method,
    * check `discounts.canUpdateDiscountCodes` to ensure it's supported in this checkout.
    *
-   * > Caution: As of version `2024-07`, UI extension code must check for instructions before calling select APIs in case those APIs aren't available.
-   *  See the [update guide](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#examples) for more information.
+   * > Caution: Check cart instructions before calling select APIs, as
+   * > some may not be available. See the
+   * > [Cart Instructions API](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/cart-instructions#examples)
+   * > for more information.
    *
    */
   instructions: SubscribableSignalLike<CartInstructions>;
@@ -611,7 +611,14 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   attributes: SubscribableSignalLike<Attribute[]>;
 
   /**
-   * All payment options available to the buyer for this checkout, such as credit cards, wallets, and local payment methods. The list depends on the shop's payment configuration and the buyer's region.
+   * All payment options available to the buyer for this checkout, such as
+   * credit cards, wallets, and local payment methods. The list depends on
+   * the shop's payment configuration and the buyer's region.
+   *
+   * The set of payment options can change when the buyer updates their
+   * address or cart, so subscribe to changes rather than reading once
+   * during initialization. Each option exposes `handle` and `type` only.
+   * Provider names, logos, fees, and installment terms aren't available.
    */
   availablePaymentOptions: SubscribableSignalLike<PaymentOption[]>;
 
@@ -624,9 +631,6 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
 
   /**
    * Provides details on the buyer's progression through the checkout and lets you intercept navigation to validate data before the buyer continues.
-   *
-   * Refer to [buyer journey](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/buyer-journey#examples)
-   * examples for more information.
    */
   buyerJourney: BuyerJourney;
 
@@ -644,6 +648,8 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    *
    * This matches the `data.checkout.token` field in a [checkout-related WebPixel event](https://shopify.dev/docs/api/web-pixels-api/standard-events/checkout_started#properties-propertydetail-data)
    * and the `checkout_token` field in the [REST Admin API `Order` resource](https://shopify.dev/docs/api/admin-rest/unstable/resources/order#resource-object).
+   *
+   * Can be `undefined`. Handle the `undefined` state before using the value.
    */
   checkoutToken: SubscribableSignalLike<CheckoutToken | undefined>;
 
@@ -654,6 +660,9 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
 
   /**
    * The delivery groups for this checkout. Each group contains one or more cart lines and the available delivery options (shipping, pickup point, or pickup location) for those items.
+   *
+   * Empty until the buyer enters enough address information for Shopify to
+   * calculate shipping rates.
    */
   deliveryGroups: SubscribableSignalLike<DeliveryGroup[]>;
 
@@ -683,7 +692,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    * @see https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/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;
 
@@ -703,7 +712,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * The buyer's language, country, currency, and timezone context. For
    * formatting and translation helpers, use the
-   * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/localization#standardapi-propertydetail-i18n)
+   * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/localization#properties-propertydetail-i18n)
    * object instead.
    */
   localization: Localization;
@@ -718,7 +727,6 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * The method used to query the Storefront GraphQL API with a prefetched token.
    *
-   * Refer to [Storefront API access examples](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/storefront-api) for more information.
    */
   query: <Data = unknown, Variables = Record<string, unknown>>(
     query: string,
@@ -726,7 +734,13 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   ) => Promise<{data?: Data; errors?: GraphQLError[]}>;
 
   /**
-   * The payment options the buyer has currently selected. This updates as the buyer changes their payment method. The array can contain multiple entries when the buyer splits payment across methods (for example, a gift card and a credit card).
+   * The payment options the buyer has currently selected. This updates as
+   * the buyer changes their payment method. The array can contain multiple
+   * entries when the buyer splits payment across methods (for example, a
+   * gift card and a credit card).
+   *
+   * Each option exposes `handle` and `type` only. Provider names, logos,
+   * fees, and installment terms aren't available.
    */
   selectedPaymentOptions: SubscribableSignalLike<SelectedPaymentOption[]>;
 
@@ -780,8 +794,8 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
 
   /**
    * Key-value storage that persists across page loads within the current checkout
-   * session. Data is shared across all activated extension targets of this
-   * extension.
+   * session. Data is shared across all activated targets associated with
+   * this extension.
    *
    * > Caution: Data persistence isn't guaranteed and storage is cleared when the
    * buyer starts a new checkout.
@@ -803,7 +817,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Enables setting and updating customer privacy consent settings and tracking consent metafields.
    *
-   * > Note: Requires the [`customer_privacy` capability](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/configuration#collect-buyer-consent) to be set to `true`.
+   * > Note: Requires the [`collect_buyer_consent` capability](/docs/apps/build/customer-accounts/capabilities#collect-buyer-consent) to be set to `true`.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    */
@@ -820,6 +834,10 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
  * Use session tokens to verify the identity of the buyer and the shop
  * context when making server-side API calls. The token is a signed JWT
  * that contains claims such as the customer ID, shop domain, and expiration.
+ *
+ * The `sub` claim in the decoded token is present only when the buyer is
+ * logged in and the app has permission to read customer accounts. Absent for
+ * anonymous buyers.
  */
 export interface SessionToken {
   /**
@@ -987,11 +1005,17 @@ export interface CartCost {
 
   /**
    * The total shipping cost after shipping discounts have been applied. The value is `undefined` if shipping hasn't been calculated yet, such as when the buyer is still on the information step.
+   *
+   * `undefined` until the buyer selects a shipping method (typically after the
+   * information step).
    */
   totalShippingAmount: SubscribableSignalLike<Money | undefined>;
 
   /**
    * The total tax the buyer can expect to pay, or the total tax already included in product and shipping prices (for tax-inclusive regions). The value is `undefined` if taxes haven't been calculated yet.
+   *
+   * `undefined` when taxes haven't been calculated or aren't available for the
+   * buyer's region.
    */
   totalTaxAmount: SubscribableSignalLike<Money | undefined>;
 
@@ -1396,6 +1420,11 @@ interface InterceptorRequestAllow {
    * This callback is called when all interceptors finish. We recommend
    * setting errors or reasons for blocking at this stage, so that all the errors in
    * the UI show up at once.
+   *
+   * Runs after all intercept results are collected. Use it for local state
+   * updates such as setting an error flag. By the time it runs, the navigation
+   * decision is final, so blocking logic belongs in the intercept handler
+   * itself, not here.
    * @param result InterceptorResult with behavior as either 'allow' or 'block'
    */
   perform?(result: InterceptorResult): void | Promise<void>;
@@ -1423,6 +1452,11 @@ interface InterceptorRequestBlock {
    * This callback is called when all interceptors finish. We recommend
    * setting errors or reasons for blocking at this stage, so that all the errors in
    * the UI show up at once.
+   *
+   * Runs after all intercept results are collected. Use it for local state
+   * updates such as setting an error flag. By the time it runs, the navigation
+   * decision is final, so blocking logic belongs in the intercept handler
+   * itself, not here.
    * @param result InterceptorResult with behavior as either 'allow' or 'block'
    */
   perform?(result: InterceptorResult): void | Promise<void>;
@@ -1630,6 +1664,10 @@ export interface Analytics {
   /**
    * Publishes a custom event to [Web Pixels](https://shopify.dev/docs/apps/marketing).
    * Returns `true` when the event is successfully dispatched.
+   *
+   * The Promise resolves to `true` when the event was dispatched. The boolean
+   * indicates dispatch confirmation only. It doesn't indicate whether any
+   * specific web pixel processed the event.
    */
   publish(name: string, data: Record<string, unknown>): Promise<boolean>;
 
@@ -1959,24 +1997,45 @@ export interface AllowedProcessing {
    * Whether analytics data can be collected based on the visitor's consent,
    * the merchant's privacy configuration, and the visitor's region. Analytics
    * data includes how the shop was used and what interactions occurred.
+   *
+   * Whether analytics data can be collected right now. Combines the buyer's
+   * consent, the merchant's privacy configuration, and the buyer's region into
+   * a single boolean. Check this flag, not `visitorConsent.analytics`, before
+   * calling `shopify.analytics.publish()`.
    */
   analytics: boolean;
   /**
    * Whether marketing data can be collected based on the visitor's consent,
    * the merchant's privacy configuration, and the visitor's region. Marketing
    * data includes attribution and targeted advertising preferences.
+   *
+   * Whether marketing data can be collected right now. Combines the buyer's
+   * consent, the merchant's privacy configuration, and the buyer's region into
+   * a single boolean. Check this flag, not `visitorConsent.marketing`, before
+   * performing marketing-related data collection.
    */
   marketing: boolean;
   /**
    * Whether preference data can be collected based on the visitor's consent,
    * the merchant's privacy configuration, and the visitor's region. Preference
    * data includes language, currency, and sizing choices.
+   *
+   * Whether preference data can be collected right now. Combines the buyer's
+   * consent, the merchant's privacy configuration, and the buyer's region into
+   * a single boolean. Check this flag, not `visitorConsent.preferences`,
+   * before storing or reading buyer preference data.
    */
   preferences: boolean;
   /**
    * Whether data can be shared with third parties based on the visitor's
    * consent, the merchant's privacy configuration, and the visitor's region.
    * This typically applies to behavioral advertising data.
+   *
+   * Whether buyer data can be shared with or sold to third parties right now.
+   * Combines the buyer's consent, the merchant's privacy configuration, and
+   * the buyer's region into a single boolean. Check this flag, not
+   * `visitorConsent.saleOfData`, before sharing or selling buyer data with
+   * third parties.
    */
   saleOfData: boolean;
 }
@@ -2029,6 +2088,9 @@ export interface TrackingConsentMetafieldChange {
   key: string;
   /**
    * The new value to store in the metafield. Set to `null` to delete the metafield.
+   *
+   * Consent metafield values are strings, not booleans. Pass `null` to delete
+   * a tracking consent metafield.
    */
   value: string | null;
 }

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

@@ -70,7 +70,7 @@ export interface AnnouncementElementEvents {
      * - 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).
      */
     aftertoggle?: CallbackEventListener<typeof tagName, ToggleArgumentsEvent>;
     /**
@@ -82,10 +82,10 @@ export interface AnnouncementElementEvents {
      *
      * - If the element is transitioning from hidden to showing, the `oldState` property will be set to `closed` and the
      *   `newState` property will be set to `open`.
-     * - If the element is transitioning from showing to hidden, then `oldState` property will be set to `open` and the
+     * - If the element is transitioning from showing to hidden, then the `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).
      */
     toggle?: CallbackEventListener<typeof tagName, ToggleArgumentsEvent>;
 }