@shopify/ui-extensions 2026.4.0-rc.2 → 2026.4.0

package/src/surfaces/point-of-sale/event/data/BaseApi.ts

@@ -2,5 +2,6 @@ import {StorageApi} from '../../api/storage-api/storage-api';
 
 /**
  * Base API access provided to extension targets, currently providing access to persistent storage for saving and retrieving extension data across sessions.
+ * @publicDocs
  */
 export type BaseApi = StorageApi;

package/src/surfaces/point-of-sale/event/data/BaseData.ts

@@ -1,13 +1,18 @@
-import type {ConnectivityState, Device, Session} from '../../../point-of-sale';
+import type {
+  ConnectivityApiContent,
+  Device,
+  Session,
+} from '../../../point-of-sale';
 
 /**
  * Base data object provided to all extension targets containing device information, session context, and connectivity state. This data is available at extension initialization and provides essential context about the runtime environment.
+ * @publicDocs
  */
 export interface BaseData {
   /**
    * The current Internet connectivity state of the POS device. Indicates whether the device is connected to or disconnected from the Internet. This state updates in real-time as connectivity changes, allowing extensions to adapt behavior for offline scenarios, show connectivity warnings, or queue operations for when connectivity is restored.
    */
-  connectivity: ConnectivityState;
+  connectivity: ConnectivityApiContent;
   /**
    * Comprehensive information about the physical POS device where the extension is currently running. Includes the device name, unique device ID, and form factor information (tablet vs other). This data is static for the session and helps extensions adapt to different device types, log device-specific information, or implement device-based configurations.
    */

package/src/surfaces/point-of-sale/event/data/CartUpdateEventData.ts

@@ -4,6 +4,7 @@ import {BaseApi} from './BaseApi';
 
 /**
  * The data object provided to cart update extension targets. Contains the current cart state along with device, session, and connectivity information. This data is passed to extensions whenever the cart changes, enabling real-time cart monitoring and cart-based business logic.
+ * @publicDocs
  */
 export interface CartUpdateEventData extends BaseData, BaseApi {
   /**

package/src/surfaces/point-of-sale/event/data/CashTrackingSessionData.ts

@@ -3,6 +3,7 @@ import {BaseApi} from './BaseApi';
 
 /**
  * The data object provided to cash tracking session start extension targets. Contains information about a newly opened cash tracking session along with device and session context.
+ * @publicDocs
  */
 export interface CashTrackingSessionStartData extends BaseData, BaseApi {
   /**
@@ -22,6 +23,7 @@ export interface CashTrackingSessionStartData extends BaseData, BaseApi {
 
 /**
  * The data object provided to cash tracking session complete extension targets. Contains information about a completed cash tracking session including when it opened and closed, along with device and session context.
+ * @publicDocs
  */
 export interface CashTrackingSessionCompleteData extends BaseData, BaseApi {
   /**

package/src/surfaces/point-of-sale/event/data/ExchangeTransactionData.ts

@@ -3,6 +3,7 @@ import {LineItem} from '../../types/cart';
 
 /**
  * Defines the data structure for completed exchange transactions.
+ * @publicDocs
  */
 export interface ExchangeTransactionData extends BaseTransactionComplete {
   /**

package/src/surfaces/point-of-sale/event/data/ReprintReceiptData.ts

@@ -1,16 +1,38 @@
 import {BaseTransactionComplete} from '../../types/base-transaction-complete';
+import {LineItem} from '../../types/cart';
 import {OrderLineItem} from '../../types/order';
 
 /**
  * Defines the data structure for receipt reprint requests.
+ * @publicDocs
  */
 export interface ReprintReceiptData extends BaseTransactionComplete {
   /**
-   * The transaction type identifier, always 'Sale' for sale transactions.
+   * The transaction type identifier, always 'Reprint' for reprint transactions.
    */
   transactionType: 'Reprint';
   /**
-   * An array of line items included in the sale transaction.
+   * An array of line items included in the transaction.
    */
   lineItems: OrderLineItem[];
+  /**
+   * The refund ID if a refund was issued for the return.
+   */
+  refundId?: number;
+  /**
+   * The return ID for the completed return transaction.
+   */
+  returnId?: number;
+  /**
+   * The exchange ID if the return is part of an exchange transaction.
+   */
+  exchangeId?: number;
+  /**
+   * An array of line items added to the customer in the exchange.
+   */
+  lineItemsAdded?: LineItem[];
+  /**
+   * An array of line items removed from the customer in the exchange.
+   */
+  lineItemsRemoved?: LineItem[];
 }

package/src/surfaces/point-of-sale/event/data/ReturnTransactionData.ts

@@ -3,6 +3,7 @@ import {LineItem} from '../../types/cart';
 
 /**
  * Defines the data structure for completed return transactions.
+ * @publicDocs
  */
 export interface ReturnTransactionData extends BaseTransactionComplete {
   /**

package/src/surfaces/point-of-sale/event/data/SaleTransactionData.ts

@@ -3,6 +3,7 @@ import {LineItem} from '../../types/cart';
 
 /**
  * Defines the data structure for completed sale transactions.
+ * @publicDocs
  */
 export interface SaleTransactionData extends BaseTransactionComplete {
   /**

package/src/surfaces/point-of-sale/event/data/TransactionCompleteData.ts

@@ -7,6 +7,7 @@ import {BaseApi} from './BaseApi';
 
 /**
  * The data object provided to receipt targets containing transaction details.
+ * @publicDocs
  */
 export interface TransactionCompleteData extends BaseData, BaseApi {
   /**
@@ -27,6 +28,7 @@ export interface TransactionCompleteData extends BaseData, BaseApi {
 
 /**
  * The data object provided to receipt targets containing transaction details and reprint information.
+ * @publicDocs
  */
 export interface TransactionCompleteWithReprintData extends BaseData, BaseApi {
   /**

package/src/surfaces/point-of-sale/event/output/BaseOutput.ts

@@ -16,6 +16,7 @@ interface ExtensionError extends Error {
 
 /**
  * Base output structure that extensions can return to communicate errors and warnings back to the POS system. Extensions populate this interface when they encounter issues during execution.
+ * @publicDocs
  */
 export interface BaseOutput {
   /**

package/src/surfaces/point-of-sale/extension-targets.ts

@@ -28,6 +28,9 @@ import type {ReceiptComponents} from './components/targets/ReceiptComponents';
 import type {BasicComponents} from './components/targets/BasicComponents';
 import type {TransactionCompleteWithReprintData} from './event/data';
 
+/**
+ * @publicDocs
+ */
 export interface EventExtensionTargets {
   'pos.transaction-complete.event.observe': (
     data: TransactionCompleteData,
@@ -43,6 +46,9 @@ export interface EventExtensionTargets {
   ) => Promise<BaseOutput>;
 }
 
+/**
+ * @publicDocs
+ */
 export interface RenderExtensionTargets {
   /**
    * Renders a single interactive tile component on the POS home screen's smart grid. The tile appears once during home screen initialization and remains persistent until navigation occurs. Use this target for high-frequency actions, status displays, or entry points to workflows that merchants need daily.
@@ -360,10 +366,22 @@ export interface RenderExtensionTargets {
   >;
 }
 
+/**
+ * @publicDocs
+ */
 export interface ExtensionTargets
   extends RenderExtensionTargets,
     EventExtensionTargets {}
 
+/**
+ * @publicDocs
+ */
 export type RenderExtensionTarget = keyof RenderExtensionTargets;
+/**
+ * @publicDocs
+ */
 export type EventExtensionTarget = keyof EventExtensionTargets;
+/**
+ * @publicDocs
+ */
 export type ExtensionTarget = keyof ExtensionTargets;

package/src/surfaces/point-of-sale/types/base-transaction-complete.ts

@@ -7,6 +7,7 @@ import type {TransactionType} from './transaction-type';
 
 /**
  * Base interface for completed transaction data shared across all transaction types.
+ * @publicDocs
  */
 export interface BaseTransactionComplete {
   /**

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

@@ -4,6 +4,7 @@ import {DiscountAllocation} from './discount-allocation';
 
 /**
  * Represents the shopping cart state, including line items, pricing, customer information, and applied discounts. Provides comprehensive access to all cart data and operations.
+ * @publicDocs
  */
 export interface Cart {
   /**
@@ -50,6 +51,7 @@ export interface Cart {
 
 /**
  * Specifies the parameters for updating cart information. Includes options for modifying customer data, notes, references, and other cart-level metadata.
+ * @publicDocs
  */
 export interface CartUpdateInput {
   /**
@@ -80,6 +82,7 @@ export interface CartUpdateInput {
 
 /**
  * Represents basic customer identification information. Contains the customer ID for linking to detailed customer data and enabling customer-specific features.
+ * @publicDocs
  */
 export interface Customer {
   /**
@@ -90,6 +93,7 @@ export interface Customer {
 
 /**
  * Represents an individual item in the shopping cart. Contains product information, pricing, quantity, discounts, and customization details for a single cart entry.
+ * @publicDocs
  */
 export interface LineItem {
   /**
@@ -172,6 +176,7 @@ export interface LineItem {
 
 /**
  * Represents a component of a [product bundle](/docs/apps/build/product-merchandising/bundles) line item. Bundle components contain the individual items that make up a bundle, each with their own pricing and tax information.
+ * @publicDocs
  */
 export interface LineItemComponent {
   /**
@@ -206,6 +211,7 @@ export interface LineItemComponent {
 
 /**
  * Represents a selling plan (subscription) associated with a line item, containing delivery schedule and plan identification details.
+ * @publicDocs
  */
 export interface SellingPlan {
   /**
@@ -232,6 +238,7 @@ export interface SellingPlan {
 
 /**
  * Represents a discount applied to a cart or transaction, including amount and description.
+ * @publicDocs
  */
 export interface Discount {
   /**
@@ -254,6 +261,7 @@ export interface Discount {
 
 /**
  * Specifies the parameters for adding custom properties to line items. Properties are key-value pairs used for storing metadata, tracking information, or integration data.
+ * @publicDocs
  */
 export interface SetLineItemPropertiesInput {
   /**
@@ -268,6 +276,7 @@ export interface SetLineItemPropertiesInput {
 
 /**
  * Specifies the parameters for applying discounts to individual line items. Includes the discount type, value, and reason for audit and reporting purposes.
+ * @publicDocs
  */
 export interface SetLineItemDiscountInput {
   /**
@@ -282,6 +291,7 @@ export interface SetLineItemDiscountInput {
 
 /**
  * Represents a discount applied to an individual line item in the cart.
+ * @publicDocs
  */
 export interface LineItemDiscount {
   /**
@@ -300,6 +310,7 @@ export interface LineItemDiscount {
 
 /**
  * Represents a custom sale item that is not associated with a product in the catalog. Includes pricing, taxation, and descriptive information for manually created line items.
+ * @publicDocs
  */
 export interface CustomSale {
   /**
@@ -322,6 +333,7 @@ export interface CustomSale {
 
 /**
  * Represents physical address information for customer shipping and billing. Contains standard address fields including street, city, region, postal code, and country data.
+ * @publicDocs
  */
 export interface Address {
   /**
@@ -380,6 +392,7 @@ export interface Address {
 
 /**
  * Specifies the parameters for assigning selling plans to line items. Used to add subscription or purchase option configurations to products.
+ * @publicDocs
  */
 export interface SetLineItemSellingPlanInput {
   /**

package/src/surfaces/point-of-sale/types/country-code.ts

@@ -2,6 +2,7 @@
 
 /**
  * The two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country codes representing all countries and territories. These standard codes are used for addresses, shipping destinations, tax jurisdictions, and regional settings.
+ * @publicDocs
  */
 export enum CountryCode {
   AF = 'AF',

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

@@ -1,5 +1,6 @@
 /**
  * Defines information about the POS device where the extension is running.
+ * @publicDocs
  */
 export interface Device {
   /**

package/src/surfaces/point-of-sale/types/direct-api-request-body.ts

@@ -1,5 +1,6 @@
 /**
  * Represents the structure of a direct API request body for [GraphQL](https://graphql.org/) operations. Contains the query/mutation string and optional variables for parameterized queries.
+ * @publicDocs
  */
 export interface DirectApiRequestBody {
   /**

package/src/surfaces/point-of-sale/types/discount-allocation.ts

@@ -2,6 +2,7 @@ import type {MoneyV2} from './money';
 
 /**
  * Represents the allocation of a discount to a specific line item.
+ * @publicDocs
  */
 export interface DiscountAllocation {
   /**

package/src/surfaces/point-of-sale/types/money.ts

@@ -1,5 +1,6 @@
 /**
  * Represents a monetary amount with currency information.
+ * @publicDocs
  */
 export interface Money {
   /**
@@ -14,6 +15,7 @@ export interface Money {
 
 /**
  * Represents a monetary amount as a string with explicit currency code.
+ * @publicDocs
  */
 export interface MoneyV2 {
   /**

package/src/surfaces/point-of-sale/types/multiple-resource-result.ts

@@ -1,5 +1,6 @@
 /**
  * Represents the result of a bulk resource lookup operation. Contains successfully found resources and identifiers for resources that were not found.
+ * @publicDocs
  */
 export interface MultipleResourceResult<T> {
   /**

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

@@ -2,6 +2,7 @@ import {LineItem} from './cart';
 
 /**
  * Represents a refund applied to a line item, including when it was created and the quantity refunded.
+ * @publicDocs
  */
 export interface LineItemRefund {
   /**
@@ -16,6 +17,7 @@ export interface LineItemRefund {
 
 /**
  * Represents a line item from an order, extending the base line item with current quantity and refund information.
+ * @publicDocs
  */
 export interface OrderLineItem extends LineItem {
   /**

package/src/surfaces/point-of-sale/types/paginated-result.ts

@@ -1,5 +1,6 @@
 /**
  * Represents the result of a paginated query. Contains the data items, pagination cursors for navigating pages, and information about whether more results exist.
+ * @publicDocs
  */
 export interface PaginatedResult<T> {
   /**

package/src/surfaces/point-of-sale/types/payment.ts

@@ -1,5 +1,6 @@
 /**
  * The available payment method types for POS transactions.
+ * @publicDocs
  */
 export type PaymentMethod =
   | 'Cash'
@@ -15,6 +16,7 @@ export type PaymentMethod =
 
 /**
  * Represents a payment applied to a transaction, including the amount, currency, and payment method type.
+ * @publicDocs
  */
 export interface Payment {
   /**

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

@@ -1,5 +1,6 @@
 /**
  * Represents the result of a PIN pad interaction, indicating whether PIN entry was completed and providing the entered PIN if available.
+ * @publicDocs
  */
 export interface PinPadResult {
   /**
@@ -14,6 +15,7 @@ export interface PinPadResult {
 
 /**
  * Represents the validation outcome for an entered PIN. Indicates whether the PIN should be accepted or rejected, with optional error messaging for rejected PINs.
+ * @publicDocs
  */
 export type PinValidationResult =
   /** The validation result indicating the PIN should be accepted for valid PINs. */
@@ -23,11 +25,13 @@ export type PinValidationResult =
 
 /**
  * The valid PIN length values (4-10 digits). Commonly used to configure minimum and maximum PIN length requirements.
+ * @publicDocs
  */
 export type PinLength = 4 | 5 | 6 | 7 | 8 | 9 | 10;
 
 /**
  * Defines a custom action button for the PIN pad interface with a label and click handler.
+ * @publicDocs
  */
 export interface PinPadActionType {
   /**
@@ -42,6 +46,7 @@ export interface PinPadActionType {
 
 /**
  * Specifies configuration options for displaying the PIN pad interface. Includes callback functions for PIN entry events, dismissal handling, and customizable labels and messaging.
+ * @publicDocs
  */
 export interface PinPadOptions {
   /**

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

@@ -1,5 +1,6 @@
 /**
  * Represents comprehensive product information including metadata, pricing, variants, and availability. Contains all data needed to display and work with products in the POS interface.
+ * @publicDocs
  */
 export interface Product {
   /**
@@ -106,6 +107,7 @@ export interface Product {
 
 /**
  * Represents a specific variant of a product with its own SKU, price, and inventory. Contains variant-specific attributes including options, availability, and identification data.
+ * @publicDocs
  */
 export interface ProductVariant {
   /**
@@ -192,6 +194,7 @@ export interface ProductVariant {
 
 /**
  * Represents a single option selection for a product variant, showing one chosen value from a product's configuration options. For example, if a product has Size and Color options, a variant might have one option for Size=Large and another for Color=Blue.
+ * @publicDocs
  */
 export interface ProductVariantOption {
   /**
@@ -208,11 +211,13 @@ export interface ProductVariantOption {
  * The inventory policy determining whether sales can continue when a variant has no inventory available:
  * - `'DENY'`: Sales are prevented when inventory reaches zero. Customers can't purchase out-of-stock variants. The "Add to cart" action is disabled or shows "Out of stock". This is the default and recommended policy for most physical products to prevent overselling.
  * - `'CONTINUE'`: Sales are allowed even when inventory is zero or negative. Customers can purchase out-of-stock variants, creating backorders. This enables pre-orders, made-to-order products, or drop-shipped items where inventory tracking is less critical.
+ * @publicDocs
  */
 export type ProductVariantInventoryPolicy = 'DENY' | 'CONTINUE';
 
 /**
  * Represents a product option definition showing one of the configurable attributes for a product (like Size, Color, Material) along with all the possible values customers can choose from. Products can have up to 3 options.
+ * @publicDocs
  */
 export interface ProductOption {
   /**

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

@@ -2,6 +2,7 @@ import type {CurrencyCode} from '../../../shared';
 
 /**
  * Defines information about the current POS session.
+ * @publicDocs
  */
 export interface Session {
   /**

package/src/surfaces/point-of-sale/types/shipping-line.ts

@@ -3,6 +3,7 @@ import type {TaxLine} from './tax-line';
 
 /**
  * Represents a shipping charge applied to an order, including the price and applicable taxes.
+ * @publicDocs
  */
 export interface ShippingLine {
   /**
@@ -25,6 +26,7 @@ export interface ShippingLine {
 
 /**
  * Represents a calculated shipping line with specific shipping or retail method type.
+ * @publicDocs
  */
 export interface CalculatedShippingLine extends ShippingLine {
   /**
@@ -41,6 +43,7 @@ export interface CalculatedShippingLine extends ShippingLine {
 
 /**
  * Represents a custom shipping line with merchant-defined shipping charges.
+ * @publicDocs
  */
 export interface CustomShippingLine extends ShippingLine {
   /**

package/src/surfaces/point-of-sale/types/storage.ts

@@ -1,3 +1,6 @@
+/**
+ * @publicDocs
+ */
 export class StorageError extends Error {
   public name = 'StorageError';
   constructor(
@@ -9,6 +12,7 @@ export class StorageError extends Error {
 }
 /**
  * Defines the storage interface for persisting extension data across sessions.
+ * @publicDocs
  */
 export interface Storage<
   BaseStorageTypes extends Record<string, any> = Record<string, unknown>,

package/src/surfaces/point-of-sale/types/tax-line.ts

@@ -2,6 +2,7 @@ import type {Money} from './money';
 
 /**
  * Represents a tax line applied to an item or transaction.
+ * @publicDocs
  */
 export interface TaxLine {
   /**

package/src/surfaces/point-of-sale/types/transaction-type.ts

@@ -4,5 +4,6 @@
  * - `'Return'`: A return transaction where a customer returns previously purchased items for a refund. This credits back payment to the customer and returns items to inventory.
  * - `'Exchange'`: An exchange transaction where a customer returns items and simultaneously purchases replacement items. This combines return and sale operations in a single transaction, often with a price adjustment.
  * - `'Reprint'`: A receipt reprint operation where an existing transaction's receipt is reprinted. No new transaction is created—this only regenerates the receipt document for an existing sale, return, or exchange.
+ * @publicDocs
  */
 export type TransactionType = 'Sale' | 'Return' | 'Exchange' | 'Reprint';