@shopify/ui-extensions 2025.7.0 → 2025.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2025.7.0",
+  "version": "2025.7.1",
   "scripts": {
     "docs:admin": "bash ./docs/surfaces/admin/build-docs.sh",
     "docs:admin:dev": "nodemon --watch src/surfaces/admin -e ts,tsx,json --exec 'yarn docs:admin'",

package/src/surfaces/checkout/targets.ts

@@ -24,7 +24,7 @@ import type {
   AllowedComponents,
   AnyComponentExcept,
 } from './shared';
-import {Announcement} from './api/announcement/announcement';
+import type {Announcement} from './api/announcement/announcement';
 
 /**
  * A UI extension will register for one or more extension targets using `shopify.extend()`.

package/src/surfaces/checkout.ts

@@ -143,6 +143,7 @@ export type {
   OrderStatusApi,
 } from './checkout/api/order-status/order-status';
 export type {OrderConfirmationApi} from './checkout/api/order-confirmation/order-confirmation';
+export type {Announcement} from './checkout/api/announcement/announcement';
 
 export type {CartLineItemApi} from './checkout/api/cart-line/cart-line-item';
 export type {PickupLocationListApi} from './checkout/api/pickup/pickup-location-list';

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

@@ -74,7 +74,10 @@ export interface Docs_Standard_StorageApi
   extends Pick<StandardApi<any>, 'storage'> {}
 
 export interface Docs_Standard_CustomerPrivacyApi
-  extends Pick<StandardApi<any>, 'customerPrivacy'> {}
+  extends Pick<
+    StandardApi<any>,
+    'customerPrivacy' | 'applyTrackingConsentChange'
+  > {}
 
 export interface Docs_Standard_UIApi extends Pick<StandardApi<any>, 'ui'> {}
 

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

@@ -184,11 +184,6 @@ export interface OrderStatusLocalization {
 export type AuthenticationState = 'fully_authenticated' | 'pre_authenticated';
 
 export interface OrderStatusApi<Target extends ExtensionTarget> {
-  /**
-   * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
-   */
-  analytics: Analytics;
-
   /**
    * Gift Cards that have been applied to the order.
    */
@@ -952,13 +947,6 @@ export interface StoreCreditAccount {
   balance: Money;
 }
 
-export interface Analytics {
-  /**
-   * Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing).
-   */
-  publish(name: string, data: {[key: string]: unknown}): Promise<boolean>;
-}
-
 /**
  * Represents the delivery information and options available for one or
  * more cart lines.

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

@@ -448,6 +448,50 @@ export interface SessionToken {
   get(): Promise<string>;
 }
 
+export interface Analytics {
+  /**
+   * Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing).
+   */
+  publish(name: string, data: Record<string, unknown>): Promise<boolean>;
+
+  /**
+   * A method for capturing details about a visitor on the online store.
+   */
+  visitor(data: {email?: string; phone?: string}): Promise<VisitorResult>;
+}
+/**
+ * Represents a visitor result.
+ */
+export type VisitorResult = VisitorSuccess | VisitorError;
+
+/**
+ * Represents a successful visitor result.
+ */
+export interface VisitorSuccess {
+  /**
+   * Indicates that the visitor information was validated and submitted.
+   */
+  type: 'success';
+}
+
+/**
+ * Represents an unsuccessful visitor result.
+ */
+export interface VisitorError {
+  /**
+   * Indicates that the visitor information is invalid and wasn't submitted.
+   * Examples are using the wrong data type or missing a required property.
+   */
+  type: 'error';
+
+  /**
+   * A message that explains the error. This message is useful for debugging.
+   * It's **not** localized, and therefore should not be presented directly
+   * to the buyer.
+   */
+  message: string;
+}
+
 export interface AllowedProcessing {
   /**
    * Can collect customer analytics about how the shop was used and interactions made on the shop.

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

@@ -9,6 +9,7 @@ import {
   StorefrontApiVersion,
   Ui,
   SessionToken,
+  Analytics,
   CustomerPrivacy,
   ApplyTrackingConsentChangeType,
 } from '../shared';
@@ -79,6 +80,11 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   sessionToken: SessionToken;
 
+  /**
+   * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
+   */
+  analytics: Analytics;
+
   /**
    * The settings matching the settings definition written in the
    * [`shopify.ui.extension.toml`](https://shopify.dev/docs/api/customer-account-ui-extensions/configuration) file.

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

@@ -66,6 +66,7 @@ export type {
   Company,
   Customer,
   SessionToken,
+  Analytics,
   ApplyTrackingConsentChangeType,
   CustomerPrivacy,
   TrackingConsentChangeResult,
@@ -74,6 +75,9 @@ export type {
   TrackingConsentMetafieldChange,
   VisitorConsent,
   VisitorConsentChange,
+  VisitorResult,
+  VisitorSuccess,
+  VisitorError,
 } from './api/shared';
 
 export type {CartLineItemApi} from './api/cart-line/cart-line-item';

package/src/surfaces/point-of-sale/render/api/cart-api/cart-api.ts

@@ -30,19 +30,17 @@ export interface CartApiContent {
   subscribable: RemoteSubscribable<Cart>;
 
   /** Bulk update the cart
+   *
    * @param cartState the cart state to set
    * @returns the updated cart
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   bulkCartUpdate(cartState: CartUpdateInput): Promise<Cart>;
 
   /** Apply a cart level discount
+   *
    * @param type the type of discount applied (example: 'Percentage')
    * @param title the title attributed with the discount
    * @param amount the percentage or fixed monetary amount deducted with the discount. Pass in `undefined` if using discount codes.
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   applyCartDiscount(
     type: CartDiscountType,
@@ -52,98 +50,83 @@ export interface CartApiContent {
 
   /**
    * Add a code discount to the cart
-   * @param code the code for the discount to add to the cart
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param code the code for the discount to add to the cart
    */
   addCartCodeDiscount(code: string): Promise<void>;
 
   /**
    * Remove the cart discount
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeCartDiscount(): Promise<void>;
 
   /**
    * Remove all cart and line item discounts
-   * @param disableAutomaticDiscounts Whether or not automatic discounts should be enabled after removing the discounts.
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param disableAutomaticDiscounts Whether or not automatic discounts should be enabled after removing the discounts.
    */
   removeAllDiscounts(disableAutomaticDiscounts: boolean): Promise<void>;
 
   /**
    * Clear the cart
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   clearCart(): Promise<void>;
 
   /**
    * Set the customer in the cart
-   * @param customer the customer object to add to the cart
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param customer the customer object to add to the cart
    */
   setCustomer(customer: Customer): Promise<void>;
 
   /**
    * Remove the current customer from the cart
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeCustomer(): Promise<void>;
 
   /**
    * Add a custom sale to the cart
+   *
    * @param customSale the custom sale object to add to the cart
    * @returns {string} the uuid of the line item added
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addCustomSale(customSale: CustomSale): Promise<string>;
 
   /**
    * Add a line item by variant ID to the cart
+   *
    * @param variantId the product variant's numeric ID to add to the cart
    * @param quantity the number of this variant to add to the cart
    * @returns {string} the uuid of the line item added
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addLineItem(variantId: number, quantity: number): Promise<string>;
 
   /**
    * Remove the line item at this uuid from the cart
-   * @param uuid the uuid of the line item that should be removed
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param uuid the uuid of the line item that should be removed
    */
   removeLineItem(uuid: string): Promise<void>;
 
   /**
    * Adds custom properties to the cart
-   * @param properties the custom key to value object to attribute to the cart
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param properties the custom key to value object to attribute to the cart
    */
   addCartProperties(properties: Record<string, string>): Promise<void>;
 
   /**
    * Removes the specified cart properties
-   * @param keys the collection of keys to be removed from the cart properties
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param keys the collection of keys to be removed from the cart properties
    */
   removeCartProperties(keys: string[]): Promise<void>;
 
   /**
    * Adds custom properties to the specified line item
+   *
    * @param uuid the uuid of the line item to which the properties should be stringd
    * @param properties the custom key to value object to attribute to the line item
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   addLineItemProperties(
     uuid: string,
@@ -152,9 +135,8 @@ export interface CartApiContent {
 
   /**
    * Adds custom properties to multiple line items at the same time.
-   * @param lineItemProperties the collection of custom line item properties to apply to their respective line items.
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param lineItemProperties the collection of custom line item properties to apply to their respective line items.
    */
   bulkAddLineItemProperties(
     lineItemProperties: SetLineItemPropertiesInput[],
@@ -162,21 +144,19 @@ export interface CartApiContent {
 
   /**
    * Removes the specified line item properties
+   *
    * @param uuid the uuid of the line item to which the properties should be removed
    * @param keys the collection of keys to be removed from the line item properties
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   removeLineItemProperties(uuid: string, keys: string[]): Promise<void>;
 
   /**
    * Add a discount on a line item to the cart
+   *
    * @param uuid the uuid of the line item that should receive a discount
    * @param type the type of discount applied (example: 'Percentage')
    * @param title the title attributed with the discount
    * @param amount the percentage or fixed monetary amount deducted with the discout
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   setLineItemDiscount(
     uuid: string,
@@ -187,9 +167,8 @@ export interface CartApiContent {
 
   /**
    * Set line item discounts to multiple line items at the same time.
-   * @param lineItemDiscounts a map of discounts to add. They key is the uuid of the line item you want to add the discount to. The value is the discount input.
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param lineItemDiscounts a map of discounts to add. They key is the uuid of the line item you want to add the discount to. The value is the discount input.
    */
   bulkSetLineItemDiscounts(
     lineItemDiscounts: SetLineItemDiscountInput[],
@@ -197,18 +176,16 @@ export interface CartApiContent {
 
   /**
    * Sets an attributed staff to all line items in the cart.
-   * @param staffId the ID of the staff. Providing undefined will clear the attributed staff from all line items.
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param staffId the ID of the staff. Providing undefined will clear the attributed staff from all line items.
    */
   setAttributedStaff(staffId: number | undefined): Promise<void>;
 
   /**
    * Sets an attributed staff to a specific line items in the cart.
+   *
    * @param staffId the ID of the staff. Providing undefined will clear the attributed staff on the line item.
    * @param lineItemUuid the UUID of the line item.
-   *
-   * @throws CartNotEditableError if the cart is not currently editable.
    */
   setAttributedStaffToLineItem(
     staffId: number | undefined,
@@ -217,33 +194,29 @@ export interface CartApiContent {
 
   /**
    * Remove all discounts from a line item
-   * @param uuid the uuid of the line item whose discounts should be removed
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param uuid the uuid of the line item whose discounts should be removed
    */
   removeLineItemDiscount(uuid: string): Promise<void>;
 
   /**
    * Add an address to the customer (Customer must be present)
-   * @param address the address object to add to the customer in cart
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param address the address object to add to the customer in cart
    */
   addAddress(address: Address): Promise<void>;
 
   /**
    * Delete an address from the customer (Customer must be present)
-   * @param addressId the address ID to delete
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param addressId the address ID to delete
    */
   deleteAddress(addressId: number): Promise<void>;
 
   /**
    * Update the default address for the customer (Customer must be present)
-   * @param addressId the address ID to set as the default address
    *
-   * @throws CartNotEditableError if the cart is not currently editable.
+   * @param addressId the address ID to set as the default address
    */
   updateDefaultAddress(addressId: number): Promise<void>;
 }

package/build/ts/surfaces/point-of-sale/render/api/cart-api/errors.d.ts

@@ -1,14 +0,0 @@
-import { CartApiContent } from './cart-api';
-type CartApiMethods = Omit<CartApiContent, 'subscribable'>;
-/**
- * An error thrown when an attempt to edit the cart is made while it is not editable.
- */
-export declare class CartNotEditableError extends Error {
-    /** The name of the method that attempted to modify the cart */
-    methodName: keyof CartApiMethods;
-    constructor(
-    /** The name of the method that attempted to modify the cart */
-    methodName: keyof CartApiMethods);
-}
-export {};
-//# sourceMappingURL=errors.d.ts.map

package/build/ts/surfaces/point-of-sale/render/api/cart-api/errors.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../../../src/surfaces/point-of-sale/render/api/cart-api/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAC,MAAM,YAAY,CAAC;AAE1C,KAAK,cAAc,GAAG,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;AAE3D;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,+DAA+D;IACxD,UAAU,EAAE,MAAM,cAAc;;IADvC,+DAA+D;IACxD,UAAU,EAAE,MAAM,cAAc;CAM1C"}

package/src/surfaces/point-of-sale/render/api/cart-api/errors.ts

@@ -1,17 +0,0 @@
-import {CartApiContent} from './cart-api';
-
-type CartApiMethods = Omit<CartApiContent, 'subscribable'>;
-
-/**
- * An error thrown when an attempt to edit the cart is made while it is not editable.
- */
-export class CartNotEditableError extends Error {
-  constructor(
-    /** The name of the method that attempted to modify the cart */
-    public methodName: keyof CartApiMethods,
-  ) {
-    super(
-      `attempted to modify cart when not editable (calling "${methodName}")`,
-    );
-  }
-}