@shopify/ui-extensions 2025.10.0-rc.9 → 2025.10.0

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

@@ -0,0 +1,239 @@
+import type {ReadonlySignalLike} from '../../../../shared';
+import type {
+  Address,
+  Cart,
+  CartUpdateInput,
+  Customer,
+  CustomSale,
+  SetLineItemDiscountInput,
+  SetLineItemPropertiesInput,
+  SetLineItemSellingPlanInput,
+} from '../../types/cart';
+
+/**
+ * Access and modify the merchant’s current cart.
+ */
+export interface CartApi {
+  cart: CartApiContent;
+}
+
+export type CartDiscountType = 'Percentage' | 'FixedAmount' | 'Code';
+
+export type LineItemDiscountType = 'Percentage' | 'FixedAmount';
+
+export interface CartApiContent {
+  /**
+   * Provides read-only access to the current cart state and allows subscribing to cart changes.
+   * The `value` property provides the current cart state, and `subscribe` allows listening to changes.
+   */
+  current: ReadonlySignalLike<Cart>;
+
+  /** Bulk update the cart
+   *
+   * @param cartState the cart state to set
+   * @returns the updated cart
+   */
+  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.
+   */
+  applyCartDiscount(
+    type: CartDiscountType,
+    title: string,
+    amount?: string,
+  ): Promise<void>;
+
+  /**
+   * Add a code discount to the cart
+   *
+   * @param code the code for the discount to add to the cart
+   */
+  addCartCodeDiscount(code: string): Promise<void>;
+
+  /**
+   * Remove the cart discount
+   */
+  removeCartDiscount(): Promise<void>;
+
+  /**
+   * Remove all cart and line item discounts
+   *
+   * @param disableAutomaticDiscounts Whether or not automatic discounts should be enabled after removing the discounts.
+   */
+  removeAllDiscounts(disableAutomaticDiscounts: boolean): Promise<void>;
+
+  /**
+   * Clear the cart
+   */
+  clearCart(): Promise<void>;
+
+  /**
+   * Set the customer in the cart
+   *
+   * @param customer the customer object to add to the cart
+   */
+  setCustomer(customer: Customer): Promise<void>;
+
+  /**
+   * Remove the current customer from the cart
+   */
+  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
+   */
+  addCustomSale(customSale: CustomSale): Promise<string>;
+
+  /**
+   * Add a line item by variant ID to the cart.
+   * Returns the uuid of the line item added, or the empty string if the user dismissed an oversell guard modal without adding anything.
+   * Throws if POS fails to add the line item. Throws if POS fails to add the line item.
+   *
+   * @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, or the empty string if the user dismissed an oversell guard modal
+   * @throws {Error} if POS fails to add the line item
+   */
+  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
+   */
+  removeLineItem(uuid: string): Promise<void>;
+
+  /**
+   * Adds custom properties to the cart
+   *
+   * @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
+   */
+  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
+   */
+  addLineItemProperties(
+    uuid: string,
+    properties: Record<string, string>,
+  ): Promise<void>;
+
+  /**
+   * 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.
+   */
+  bulkAddLineItemProperties(
+    lineItemProperties: SetLineItemPropertiesInput[],
+  ): Promise<void>;
+
+  /**
+   * 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
+   */
+  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
+   */
+  setLineItemDiscount(
+    uuid: string,
+    type: LineItemDiscountType,
+    title: string,
+    amount: string,
+  ): Promise<void>;
+
+  /**
+   * 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.
+   */
+  bulkSetLineItemDiscounts(
+    lineItemDiscounts: SetLineItemDiscountInput[],
+  ): Promise<void>;
+
+  /**
+   * 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.
+   */
+  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.
+   */
+  setAttributedStaffToLineItem(
+    staffId: number | undefined,
+    lineItemUuid: string,
+  ): Promise<void>;
+
+  /**
+   * Remove all discounts from a line item
+   *
+   * @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
+   */
+  addAddress(address: Address): Promise<void>;
+
+  /**
+   * Delete an address from the customer (Customer must be present)
+   *
+   * @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
+   */
+  updateDefaultAddress(addressId: number): Promise<void>;
+
+  /**
+   * Add a selling plan to a line item in the cart.
+   *
+   * @param uuid the uuid of the line item that should receive the selling plan
+   * @param sellingPlanId the ID of the selling plan to add to the line item
+   */
+  addLineItemSellingPlan(input: SetLineItemSellingPlanInput): Promise<void>;
+
+  /**
+   * Remove the selling plan from a line item in the cart.
+   *
+   * @param uuid the uuid of the line item whose selling plan should be removed
+   */
+  removeLineItemSellingPlan(uuid: string): Promise<void>;
+}

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

@@ -0,0 +1,11 @@
+import type {LineItem} from '../../types/cart';
+
+/**
+ * Access to the selected line item in the merchant’s current cart.
+ */
+export interface CartLineItemApi {
+  /**
+   * The selected line item in the merchant’s current cart.
+   */
+  cartLineItem: LineItem;
+}

package/src/surfaces/point-of-sale/api/connectivity-api/connectivity-api.ts

@@ -0,0 +1,25 @@
+import type {ReadonlySignalLike} from '../../../../shared';
+
+export type ConnectivityStateSeverity = 'Connected' | 'Disconnected';
+
+export interface ConnectivityState {
+  /**
+   * Whether the device is connected to the internet
+   */
+  internetConnected: ConnectivityStateSeverity;
+}
+
+export interface ConnectivityApiContent {
+  /**
+   * Provides read-only access to the current connectivity state and allows subscribing to connectivity changes.
+   * The `value` property provides the current connectivity state, and `subscribe` allows listening to changes.
+   */
+  current: ReadonlySignalLike<ConnectivityState>;
+}
+
+/**
+ * Access information about the device connectivity
+ */
+export interface ConnectivityApi {
+  connectivity: ConnectivityApiContent;
+}

package/src/surfaces/point-of-sale/api/customer-api/customer-api.ts

@@ -0,0 +1,10 @@
+export interface CustomerApi {
+  customer: CustomerApiContent;
+}
+
+export interface CustomerApiContent {
+  /**
+   * The unique identifier for the customer
+   */
+  id: number;
+}

package/src/surfaces/point-of-sale/api/device-api/device-api.ts

@@ -0,0 +1,21 @@
+export interface DeviceApiContent {
+  /**
+   * The name of the device
+   */
+  name: string;
+  /**
+   * The string ID of the device
+   */
+  getDeviceId(): Promise<string>;
+  /**
+   * Whether the device is a tablet
+   */
+  isTablet(): Promise<boolean>;
+}
+
+/**
+ * Access information about the device, like name and ID
+ */
+export interface DeviceApi {
+  device: DeviceApiContent;
+}

package/src/surfaces/point-of-sale/api/draft-order-api/draft-order-api.ts

@@ -0,0 +1,20 @@
+export interface DraftOrderApi {
+  draftOrder: DraftOrderApiContent;
+}
+
+export interface DraftOrderApiContent {
+  /**
+   * The unique identifier for the draft order
+   */
+  id: number;
+
+  /**
+   * The name of the draft order
+   */
+  name: string;
+
+  /**
+   * The unique identifier of the customer associated with the draft order
+   */
+  customerId?: number;
+}

package/src/surfaces/point-of-sale/api/locale-api/locale-api.ts

@@ -0,0 +1,16 @@
+import type {ReadonlySignalLike} from '../../../../shared';
+
+export interface LocaleApiContent {
+  /**
+   * Provides read-only access to the current IETF-formatted locale and allows subscribing to locale changes.
+   * The `value` property provides the current locale, and `subscribe` allows listening to changes.
+   */
+  current: ReadonlySignalLike<string>;
+}
+
+/**
+ * Access the merchant’s current locale (in [IETF format](https://en.wikipedia.org/wiki/IETF_language_tag)) to internationalize your extension content.
+ */
+export interface LocaleApi {
+  locale: LocaleApiContent;
+}

package/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts

@@ -0,0 +1,55 @@
+export interface NavigationNavigateOptions {
+  /**
+   * Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState().
+   */
+  state?: unknown;
+}
+
+/**
+ * The NavigationHistoryEntry interface of the Navigation API represents a single navigation history entry.
+ */
+export interface NavigationHistoryEntry {
+  /** Returns the key of the history entry. This is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. */
+  key: string;
+  /**
+   * Returns the URL of this history entry.
+   */
+  url: string | null;
+  /**
+   * Returns a clone of the available state associated with this history entry.
+   */
+  getState(): unknown;
+}
+
+/**
+ * The NavigationCurrentEntryChangeEvent interface of the Navigation API is the event object for the currententrychange event, which fires when the Navigation.currentEntry has changed.
+ */
+export interface NavigationCurrentEntryChangeEvent {
+  /**
+   * Returns the NavigationHistoryEntry that was navigated from.
+   */
+  from: NavigationHistoryEntry;
+}
+
+export interface Navigation {
+  /**
+   * The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
+   */
+  navigate: (url: string, options?: NavigationNavigateOptions) => Promise<void>;
+  /**
+   * The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
+   */
+  currentEntry: NavigationHistoryEntry;
+  /**
+   * The back() method of the Navigation interface navigates to the previous entry in the history list.
+   */
+  back(): void;
+  addEventListener(
+    type: 'currententrychange',
+    cb: (event: NavigationCurrentEntryChangeEvent) => void,
+  ): void;
+  removeEventListener(
+    type: 'currententrychange',
+    cb: (event: NavigationCurrentEntryChangeEvent) => void,
+  ): void;
+}

package/src/surfaces/point-of-sale/api/order-api/order-api.ts

@@ -0,0 +1,26 @@
+/**
+ * Interface to access the order
+ */
+export interface OrderApi {
+  order: OrderApiContent;
+}
+
+/**
+ * Interface for Order details
+ */
+export interface OrderApiContent {
+  /**
+   * The unique identifier for the order
+   */
+  id: number;
+
+  /**
+   * The name of the order
+   */
+  name: string;
+
+  /**
+   * The unique identifier of the customer associated with the order
+   */
+  customerId?: number;
+}

package/src/surfaces/point-of-sale/api/pin-pad-api.ts

@@ -0,0 +1,23 @@
+import {PinPadOptions, PinValidationResult} from '../types/pin-pad';
+
+export interface PinPadApiContent {
+  /** Shows a pin pad to the user in a modal dialog.
+   *
+   * @param onSubmit the function to be called when the PIN is submitted.
+   * The callback should be used to validate the PIN and return `accept` or `reject`.
+   * @param options the options for the pin pad
+   */
+  showPinPad(
+    onSubmit: (
+      pin: number[],
+    ) => Promise<PinValidationResult> | PinValidationResult,
+    options?: PinPadOptions,
+  ): void;
+}
+
+/**
+ * Access the Pin Pad API for pin pad functionality in a modal.
+ */
+export interface PinPadApi {
+  pinPad: PinPadApiContent;
+}

package/src/surfaces/point-of-sale/api/print-api/print-api.ts

@@ -0,0 +1,29 @@
+/**
+ * Access the print API for printing functionality
+ */
+export interface PrintApiContent {
+  /**
+   * Trigger a print dialog.
+   *
+   * The src must be either:
+   * - A relative path that will be appended to your app's [application_url](/docs/apps/build/cli-for-apps/app-configuration#application_url)
+   * - A full URL to your app's backend that will be used to return the document to print
+   *
+   * Supported document types:
+   * - HTML documents (recommended for best printing experience)
+   * - Text files
+   * - Image files (PNG, JPEG, etc.)
+   * - PDF files (Note: On Android devices, PDFs will be downloaded and must be printed using an external application)
+   *
+   * @param src the source URL of the content to print.
+   * @returns Promise<void> that resolves when content is ready and native print dialog appears.
+   */
+  print(src: string): Promise<void>;
+}
+
+/**
+ * Interface for printing
+ */
+export interface PrintApi {
+  print: PrintApiContent;
+}

package/src/surfaces/point-of-sale/api/product-api/product-api.ts

@@ -0,0 +1,14 @@
+export interface ProductApi {
+  product: ProductApiContent;
+}
+
+export interface ProductApiContent {
+  /**
+   * The unique identifier for the product.
+   */
+  id: number;
+  /**
+   * The unique identifier for the product variant.
+   */
+  variantId: number;
+}

package/src/surfaces/point-of-sale/api/product-search-api/product-search-api.ts

@@ -0,0 +1,94 @@
+import type {MultipleResourceResult} from '../../types/multiple-resource-result';
+import type {PaginatedResult} from '../../types/paginated-result';
+import type {Product, ProductVariant} from '../../types/product';
+
+export type ProductSortType =
+  | 'RECENTLY_ADDED'
+  | 'RECENTLY_ADDED_ASCENDING'
+  | 'ALPHABETICAL_A_TO_Z'
+  | 'ALPHABETICAL_Z_TO_A';
+
+/**
+ * Base interface for pagination.
+ */
+export interface PaginationParams {
+  /**
+   * Specifies the number of results to be returned in this page. The maximum number of items that will be returned is 50.
+   */
+  first?: number;
+  /**
+   * Specifies the page cursor. Items after this cursor will be returned.
+   */
+  afterCursor?: string;
+}
+
+/**
+ * Interface for product search
+ */
+export interface ProductSearchParams extends PaginationParams {
+  /**
+   * The search term to be used to search for POS products.
+   */
+  queryString?: string;
+  /**
+   * Specifies the order in which products should be sorted. When a `queryString` is provided, sortType will not have any effect, as the results will be returned in order by relevance to the `queryString`.
+   */
+  sortType?: ProductSortType;
+}
+
+export interface ProductSearchApiContent {
+  /** Search for products on the POS device.
+   * @param searchParams The parameters for the product search.
+   */
+  searchProducts(
+    searchParams: ProductSearchParams,
+  ): Promise<PaginatedResult<Product>>;
+
+  /** Fetches a single product's details.
+   * @param productId The ID of the product to lookup.
+   */
+  fetchProductWithId(productId: number): Promise<Product | undefined>;
+
+  /** Fetches multiple products' details.
+   * @param productIds Specifies the array of product IDs to lookup. This is limited to 50 products. All excess requested IDs will be removed from the array.
+   */
+  fetchProductsWithIds(
+    productIds: number[],
+  ): Promise<MultipleResourceResult<Product>>;
+
+  /** Fetches a single product variant's details.
+   * @param productVariantId The ID of the product variant to lookup.
+   */
+  fetchProductVariantWithId(
+    productVariantId: number,
+  ): Promise<ProductVariant | undefined>;
+
+  /** Fetches multiple product variants' details.
+   * @param productVariantIds Specifies the array of product variant IDs to lookup. This is limited to 50 product variants. All excess requested IDs will be removed from the array.
+   */
+  fetchProductVariantsWithIds(
+    productVariantIds: number[],
+  ): Promise<MultipleResourceResult<ProductVariant>>;
+
+  /** Fetches all product variants associated with a product.
+   * @param productId The product ID. All variants' details associated with this product ID are returned.
+   */
+  fetchProductVariantsWithProductId(
+    productId: number,
+  ): Promise<ProductVariant[]>;
+
+  /** Fetches a page of product variants associated with a product.
+   * @param paginationParams The parameters for pagination.
+   */
+  fetchPaginatedProductVariantsWithProductId(
+    productId: number,
+    paginationParams: PaginationParams,
+  ): Promise<PaginatedResult<ProductVariant>>;
+}
+
+/**
+ * Access Point of Sale's native product search functionality.
+ */
+export interface ProductSearchApi {
+  productSearch: ProductSearchApiContent;
+}

package/src/surfaces/point-of-sale/api/scanner-api/scanner-api.ts

@@ -0,0 +1,42 @@
+import type {ReadonlySignalLike} from '../../../../shared';
+
+/** The scanner source the POS device supports. */
+export type ScannerSource = 'camera' | 'external' | 'embedded';
+
+export interface ScannerSubscriptionResult {
+  /** The string data from the last scanner event received. */
+  data?: string;
+  /** The scanning source from which the scan event came. */
+  source?: ScannerSource;
+}
+
+export interface ScannerSources {
+  /**
+   * The current available scanner sources.
+   * The `value` property provides the current sources, and `subscribe` allows listening to changes.
+   */
+  current: ReadonlySignalLike<ScannerSource[]>;
+}
+
+export interface ScannerData {
+  /**
+   * The current scan data.
+   * The `value` property provides the current scan result, and `subscribe` allows listening to new scans.
+   */
+  current: ReadonlySignalLike<ScannerSubscriptionResult>;
+}
+
+export interface ScannerApiContent {
+  /**
+   * Provides read-only access to scanner data and allows subscribing to new scan events.
+   */
+  scannerData: ScannerData;
+  /**
+   * Provides read-only access to the available scanner sources on the POS device.
+   */
+  sources: ScannerSources;
+}
+
+export interface ScannerApi {
+  scanner: ScannerApiContent;
+}

package/src/surfaces/point-of-sale/api/session-api/session-api.ts

@@ -0,0 +1,22 @@
+import type {Session} from '../../types/session';
+
+export interface SessionApiContent {
+  /**
+   * Access information on the current POS session.
+   */
+  currentSession: Session;
+  /**
+   * Get a fresh session token for communication with your app's backend service.
+   * When the authenticated user (the user that logged into Shopify POS with their email address) doesn't have the correct app permissions enabled for your app, null will be returned. This is irrelevant of which POS Staff member is pinned in, as those are not authenticated users.
+   * For more information, see our [app permissions documentation](https://help.shopify.com/en/manual/your-account/users/roles/permissions/store-permissions#apps-and-channels-permissions).
+   * Calls to Shopify APIs must be made by your app’s backend service.
+   */
+  getSessionToken: () => Promise<string | undefined>;
+}
+
+/**
+ * Access information on the current Session, including data on the current shop, user, staff and location.
+ */
+export interface SessionApi {
+  session: SessionApiContent;
+}

package/src/surfaces/point-of-sale/api/standard/standard-api.ts

@@ -0,0 +1,21 @@
+import {ConnectivityApi} from '../connectivity-api/connectivity-api';
+import {DeviceApi} from '../device-api/device-api';
+import {LocaleApi} from '../locale-api/locale-api';
+import {SessionApi} from '../session-api/session-api';
+import {ToastApi} from '../toast-api/toast-api';
+import {ProductSearchApi} from '../product-search-api/product-search-api';
+import {PrintApi} from '../print-api/print-api';
+import {StorageApi} from '../storage-api/storage-api';
+import {PinPadApi} from '../pin-pad-api';
+
+export type StandardApi<T> = {[key: string]: any} & {
+  extensionPoint: T;
+} & LocaleApi &
+  ToastApi &
+  SessionApi &
+  PrintApi &
+  ProductSearchApi &
+  DeviceApi &
+  ConnectivityApi &
+  StorageApi &
+  PinPadApi;