@shopify/ui-extensions 2025.10.14 → 2025.10.16

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

@@ -9,94 +9,127 @@ import type {CartLineItemApi} from './cart-line/cart-line-item';
  * Note: These are not exported as part of the package, they are only used for documentation purposes.
  */
 
+/** @publicDocs */
 export interface Docs_Standard_AddressApi
   extends Pick<StandardApi, 'shippingAddress' | 'billingAddress'> {}
+/** @publicDocs */
 export interface Docs_Checkout_AddressApi
   extends Pick<CheckoutApi, 'applyShippingAddressChange'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_AttributesApi
   extends Pick<StandardApi, 'attributes'> {}
+/** @publicDocs */
 export interface Docs_Checkout_AttributesApi
   extends Pick<CheckoutApi, 'applyAttributeChange'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_BuyerIdentityApi
   extends Pick<StandardApi, 'buyerIdentity'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_BuyerJourneyApi
   extends Pick<StandardApi, 'buyerJourney'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_CartInstructionsApi
   extends Pick<StandardApi, 'instructions'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_CartLinesApi
   extends Pick<StandardApi, 'lines'> {}
+/** @publicDocs */
 export interface Docs_Checkout_CartLinesApi
   extends Pick<CheckoutApi, 'applyCartLinesChange'> {}
+/** @publicDocs */
 export interface Docs_CartLineItem_CartLinesApi
   extends Pick<CartLineItemApi, 'target'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_CostApi extends Pick<StandardApi, 'cost'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_LocalizationApi
   extends Pick<StandardApi, 'i18n' | 'localization'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_LocalizedFieldsApi
   extends Pick<StandardApi, 'localizedFields'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_MetafieldsApi
   extends Pick<StandardApi, 'appMetafields' | 'metafields'> {}
+/** @publicDocs */
 export interface Docs_Checkout_MetafieldsApi
   extends Pick<CheckoutApi, 'applyMetafieldChange'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_DeliveryApi
   extends Pick<StandardApi, 'deliveryGroups'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_CheckoutTokenApi
   extends Pick<StandardApi, 'checkoutToken'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_ExtensionMetaApi
   extends Pick<StandardApi, 'extension'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_CheckoutSettingsApi
   extends Pick<StandardApi, 'checkoutSettings'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_ShopApi extends Pick<StandardApi, 'shop'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_NoteApi extends Pick<StandardApi, 'note'> {}
+/** @publicDocs */
 export interface Docs_Checkout_NoteApi
   extends Pick<CheckoutApi, 'applyNoteChange'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_PaymentOptionsApi
   extends Pick<
     StandardApi,
     'availablePaymentOptions' | 'selectedPaymentOptions'
   > {}
 
+/** @publicDocs */
 export interface Docs_Standard_GiftCardsApi
   extends Pick<StandardApi, 'appliedGiftCards'> {}
 
+/** @publicDocs */
 export interface Docs_Checkout_GiftCardsApi
   extends Pick<CheckoutApi, 'applyGiftCardChange'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_DiscountsApi
   extends Pick<StandardApi, 'discountAllocations' | 'discountCodes'> {}
 
+/** @publicDocs */
 export interface Docs_Checkout_DiscountsApi
   extends Pick<CheckoutApi, 'applyDiscountCodeChange'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_SessionTokenApi
   extends Pick<StandardApi, 'sessionToken'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_SettingsApi
   extends Pick<StandardApi, 'settings'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_StorageApi
   extends Pick<StandardApi, 'storage'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_QueryApi extends Pick<StandardApi, 'query'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_AnalyticsApi
   extends Pick<StandardApi, 'analytics'> {}
 
+/** @publicDocs */
 export interface Docs_Standard_CustomerPrivacyApi
   extends Pick<StandardApi, 'customerPrivacy' | 'applyTrackingConsentChange'> {}

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

@@ -3,25 +3,33 @@ import type {SubscribableSignalLike} from '../../shared';
 export interface OrderConfirmation {
   order: {
     /**
-     * The globally-uniqueID of the OrderConfirmation. This will be the ID of the Order once successfully created.
+     * A globally unique identifier for the order. This becomes the
+     * [`Order`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) object ID in the
+     * GraphQL Admin API after the order is created.
+     *
+     * @example 'gid://shopify/Order/123'
      */
     id: string;
   };
   /**
-   * A randomly generated alpha-numeric identifier for the order.
-   * For orders created in 2024 and onwards, the number will always be present. For orders created before that date, the number might not be present.
+   * 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;
 
   /**
-   * Whether this is the customer's first order.
+   * Whether this is the customer's first completed order with this shop. `true` means the buyer hasn't placed an order here before. Use this to show first-purchase messaging or trigger welcome offers.
    */
   isFirstOrder: boolean;
 }
 
+/** @publicDocs */
 export interface OrderConfirmationApi {
   /**
-   * Order information that's available post-checkout.
+   * The order details available after the buyer completes checkout, including the order ID, order number, and whether it's the buyer's first purchase.
    */
   orderConfirmation: SubscribableSignalLike<OrderConfirmation>;
 }

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

@@ -1,14 +1,23 @@
 import type {SubscribableSignalLike} from '../../shared';
 import type {PickupLocationOption} from '../standard/standard';
 
+/** @publicDocs */
 export interface PickupLocationItemApi {
   /**
-   * The pickup location the extension is attached to.
+   * 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 pickup location is currently selected.
+   * 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-location-list.ts

@@ -1,8 +1,11 @@
 import type {SubscribableSignalLike} from '../../shared';
 
+/** @publicDocs */
 export interface PickupLocationListApi {
   /**
-   * Whether the customer location input form is shown to the buyer.
+   * 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 locations.
    */
   isLocationFormVisible: SubscribableSignalLike<boolean>;
 }

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

@@ -1,8 +1,11 @@
 import type {SubscribableSignalLike} from '../../shared';
 
+/** @publicDocs */
 export interface PickupPointListApi {
   /**
-   * Whether the customer location input form is shown to the buyer.
+   * 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

@@ -2,13 +2,17 @@ import type {CountryCode} from '../../../shared';
 
 export interface ValidationError {
   /**
-   * Error message to be displayed to the buyer.
+   * The error message to display to the buyer. Use this to explain what
+   * went wrong and how to fix it.
    */
   message: string;
   /**
-   * The checkout UI field that the error is associated with.
+   * The checkout UI field that the error is associated with. When provided,
+   * checkout highlights the matching field so the buyer knows where to fix
+   * the issue. The value is `undefined` if the error isn't tied to a
+   * specific field.
    *
-   * Example: `$.cart.deliveryGroups[0].deliveryAddress.countryCode`
+   * @example '$.cart.deliveryGroups[0].deliveryAddress.countryCode'
    *
    * See the [supported targets](https://shopify.dev/docs/api/functions/reference/cart-checkout-validation/graphql#supported-targets)
    * for more information.
@@ -16,135 +20,177 @@ export interface ValidationError {
   target?: string;
 }
 
+/**
+ * A [selling plan](https://shopify.dev/docs/apps/build/purchase-options/subscriptions) represents a recurring or deferred purchasing option for a product, such as a subscription, pre-order, or try-before-you-buy plan. The merchant configures selling plans to define how and when the buyer is charged.
+ */
 export interface SellingPlan {
   /**
-   * A globally-unique identifier.
+   * A globally-unique identifier for the selling plan in the format
+   * `gid://shopify/SellingPlan/<id>`. Use this to reference the specific
+   * selling plan associated with a line item.
+   *
    * @example 'gid://shopify/SellingPlan/1'
    */
   id: string;
 
   /**
-   * Whether purchasing the selling plan will result in multiple deliveries.
+   * Whether purchasing through this selling plan results in multiple
+   * deliveries. `true` for subscription plans with recurring fulfillment,
+   * `false` for one-time pre-orders or try-before-you-buy plans.
    */
   recurringDeliveries: boolean;
 }
 
 export interface Attribute {
   /**
-   * The key for the attribute.
+   * The identifier for the attribute. Each key must be unique within the
+   * set of attributes on the cart or checkout. If you call
+   * `applyAttributeChange()` with a key that already exists, then the
+   * existing value is replaced.
+   *
+   * @example 'gift_wrapping'
    */
   key: string;
 
   /**
-   * The value for the 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;
 }
 
 export interface MailingAddress {
   /**
-   * The buyer's full name.
+   * The buyer's full name, typically a combination of first and last name.
+   * The value is `undefined` if the buyer didn't provide a name.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example 'John Doe'
    */
   name?: string;
 
   /**
-   * The buyer's first name.
+   * The buyer's first name. Use this alongside `lastName` when you need to
+   * display or process name parts separately. The value is `undefined` if
+   * the buyer didn't provide a first name or the store doesn't collect
+   * split names.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example 'John'
    */
   firstName?: string;
 
   /**
-   * The buyer's last name.
+   * The buyer's last name. Use this alongside `firstName` when you need to
+   * display or process name parts separately. The value is `undefined` if
+   * the buyer didn't provide a last name or the store doesn't collect
+   * split names.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example 'Doe'
    */
   lastName?: string;
 
   /**
-   * The buyer's company name.
+   * The buyer's company name. The value is `undefined` if the buyer didn't
+   * enter a company or the store doesn't collect company names.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example 'Shopify'
    */
   company?: string;
 
   /**
-   * The first line of the buyer's address, including street name and number.
+   * The first line of the street address, including the street number and
+   * name. The value is `undefined` if the buyer hasn't entered an address yet.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example '151 O'Connor Street'
    */
   address1?: string;
 
   /**
-   * The second line of the buyer's address, like apartment number, suite, etc.
+   * The second line of the buyer's address, such as apartment number, suite,
+   * or unit. The value is `undefined` if the buyer didn't provide a second
+   * address line.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example 'Ground floor'
    */
   address2?: string;
 
   /**
-   * The buyer's city.
+   * The city, town, or village of the address. The value is `undefined` if
+   * the buyer hasn't entered a city yet.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example 'Ottawa'
    */
   city?: string;
 
   /**
-   * The buyer's postal or ZIP code.
+   * The postal code or ZIP code of the address, used for mail sorting and
+   * delivery routing. The value is `undefined` if the buyer hasn't entered
+   * one yet or the country doesn't use postal codes.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example 'K2P 2L8'
    */
   zip?: string;
 
   /**
-   * The ISO 3166 Alpha-2 format for the buyer's country. Refer to https://www.iso.org/iso-3166-country-codes.html.
+   * The two-letter country code in [ISO 3166 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
+   * format. The value is `undefined` if the buyer hasn't selected a country
+   * yet.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example 'CA' for Canada.
    */
   countryCode?: CountryCode;
 
   /**
-   * The buyer's province code, such as state, province, prefecture, or region.
+   * The province, state, prefecture, or region code of the address. The
+   * format varies by country. The value is `undefined` if the buyer hasn't
+   * selected one yet or the country doesn't have provinces.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
    * @example 'ON' for Ontario.
    */
   provinceCode?: string;
 
   /**
-   * The buyer's phone number.
+   * The phone number associated with the address, typically in international
+   * format. The value is `undefined` if the buyer didn't provide a phone
+   * number or the store doesn't collect phone numbers.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data).
    *
-   * @example '+1 613 111 2222'.
+   * @example '+1 613 111 2222'
    */
   phone?: string;
 }
 
 export interface ShippingAddress extends MailingAddress {
   /**
-   * Specifies whether the address should be saved to the buyer's account.
+   * Controls whether the address is saved to the buyer's account. When
+   * `true`, the address won't be saved and is only used for this checkout.
+   * When `false` or `undefined`, the address might be saved to the buyer's
+   * account for future use.
    */
   oneTimeUse?: boolean;
 }

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

@@ -1,19 +1,28 @@
 import type {SubscribableSignalLike} from '../../shared';
 import type {ShippingOption} from '../standard/standard';
 
+/** @publicDocs */
 export interface ShippingOptionItemApi {
   /**
-   * The shipping option the extension is attached to.
+   * 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 shipping option the extension is attached to is currently selected in the UI.
+   * 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>;
 
   /**
-   * The render mode of the shipping option.
+   * The render mode of this shipping option, indicating how the extension is displayed in the checkout UI.
    */
   renderMode: ShippingOptionItemRenderMode;
 }
@@ -23,7 +32,7 @@ export interface ShippingOptionItemApi {
  */
 export interface ShippingOptionItemRenderMode {
   /**
-   * Whether the shipping option is rendered in an overlay.
+   * Whether the shipping option is rendered in an overlay. When `true`, the extension appears in a modal or sheet on top of the checkout page. When `false`, the extension renders inline within the shipping options list.
    */
   overlay: boolean;
 }

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

@@ -6,13 +6,14 @@ import type {
   Money,
 } from '../standard/standard';
 
+/** @publicDocs */
 export interface ShippingOptionListApi {
   /**
-   * The delivery group list the extension is attached to. The target will be undefined when there are no groups for a given type.
+   * The delivery group list that this extension is attached to. Use this to access all delivery groups and their options. The value is `undefined` when there aren't any delivery groups for the given type.
    */
   target: SubscribableSignalLike<DeliveryGroupList | undefined>;
   /**
-   * The list of selection groups available to the buyers. The property will be undefined when no such groups are available.
+   * The list of delivery selection groups available to the buyer, which let buyers choose between grouped delivery options. The value is `undefined` when no selection groups are available.
    */
   deliverySelectionGroups: SubscribableSignalLike<
     DeliverySelectionGroup[] | undefined
@@ -20,45 +21,48 @@ export interface ShippingOptionListApi {
 }
 
 /**
- * The delivery group list the extension is associated to.
+ * A collection of delivery groups that share the same group type.
  */
 export interface DeliveryGroupList {
   /**
-   * The group type of the delivery group list.
+   * The type of delivery groups in this list. This is the same `DeliveryGroupType` used on `DeliveryGroup.groupType`.
+   *
+   * - `'oneTimePurchase'`: Items bought as a single, non-recurring purchase.
+   * - `'subscription'`: Items bought through a [selling plan](https://shopify.dev/docs/apps/build/purchase-options/subscriptions) that results in recurring deliveries.
    */
   groupType: DeliveryGroupType;
   /**
-   * The delivery groups that compose this list.
+   * The delivery groups in this list. Each group contains cart lines and available delivery options for those items.
    */
   deliveryGroups: DeliveryGroup[];
 }
 
 /**
- * A selection group for delivery options.
+ * A named group of delivery options that the buyer can select as a unit.
  */
 export interface DeliverySelectionGroup {
   /**
-   * The handle of the selection group.
+   * A unique identifier for this selection group.
    */
   handle: string;
   /**
-   * If the selection group is selected.
+   * Whether the buyer has selected this delivery selection group. When `true`, the associated delivery options are active. When `false`, the buyer has selected a different group.
    */
   selected: boolean;
   /**
-   * The localized title of the selection group.
+   * The localized display title of this selection group, suitable for rendering in the checkout UI.
    */
   title: string;
   /**
-   * The associated delivery option handles with the selection group. The handles will match the delivery group's delivery option handles.
+   * The delivery options that belong to this selection group. Each reference's `handle` matches a delivery option handle in the associated delivery group.
    */
   associatedDeliveryOptions: DeliveryOptionReference[];
   /**
-   * The sum of each delivery option's cost.
+   * The combined cost of all delivery options in this group before discounts.
    */
   cost: Money;
   /**
-   * The sum of each delivery option's cost after discounts.
+   * The combined cost of all delivery options in this group after discounts have been applied. This is what the buyer actually pays.
    */
   costAfterDiscounts: Money;
 }