@shopify/ui-extensions 2026.10.0 → 2026.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2026.10.0",
+  "version": "2026.10.2",
   "scripts": {
     "docs:admin": "node ./docs/surfaces/admin/build-docs.mjs",
     "docs:checkout": "bash ./docs/surfaces/checkout/build-docs.sh",

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

@@ -51,7 +51,7 @@ export interface RedeemableAddChange {
   attributes: RedeemableAttribute[];
 
   /**
-   * The identifier used to represent the redeemable (e.g. the gift card code).
+   * The identifier used to represent the redeemable, for example the gift card code.
    */
   identifier: string;
 }

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

@@ -113,7 +113,7 @@ export interface AddressLineComponents {
   streetNumber?: string;
 
   /**
-   * Additional address information (e.g. apartment, suite, or unit).
+   * Additional address information, for example an apartment, suite, or unit.
    *
    * {% 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).
    *
@@ -122,7 +122,7 @@ export interface AddressLineComponents {
   additionalInformation?: string;
 
   /**
-   * A regional or city subdivision (e.g. county, metropolitan region,
+   * A regional or city subdivision (for example, county, metropolitan region,
    * neighborhood, ward).
    *
    * {% 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).
@@ -209,15 +209,21 @@ export interface MailingAddress {
   address2?: string;
 
   /**
-   * The components of `address1`/`address2`. `undefined` when the country's
-   * address layout doesn't store components or none have been entered. The
-   * flat lines are published alongside them.
-   *
-   * Writable through `applyShippingAddressChange`, which does not validate a
-   * change against `Country.acceptedAddressInputFields`. Sent alongside a flat
-   * line, the components win and recompose it. Where a country accepts
-   * components without storing them, the write composes the flat line and only
-   * the line is published.
+   * The parts of `address1` and `address2`, such as street name, street
+   * number and apartment. The value is `undefined` if the country doesn't
+   * store address components or none have been entered. `address1` and
+   * `address2` are still provided alongside them.
+   *
+   * Writable through `applyShippingAddressChange`, which doesn't check the
+   * components against `Country.acceptedAddressInputFields`. For each street
+   * line, changed components always win over the line, and the line is
+   * rebuilt from them. Components that match the current address count as
+   * unchanged. In countries that store components, an edited line wins over
+   * unchanged components, so an extension can spread the address it read and
+   * correct only `address1`. If the country accepts components but doesn't
+   * store them, the line is built from the components and only the line is
+   * saved. If the country's address format has no components, a change that
+   * includes them is rejected.
    *
    * {% 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).
    *

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

@@ -452,8 +452,6 @@ export interface Localization {
    * changes the country of their shipping address. The value is
    * `undefined` if the market is unknown.
    *
-   * > Caution: This `market` field is deprecated and will be removed in a future version of the API.
-   *
    * @deprecated This `market` field will be removed in a future version of the API.
    */
   market: SubscribableSignalLike<Market | undefined>;

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

@@ -1032,7 +1032,7 @@ export interface PaymentTermsTemplate {
    */
   id: string;
   /**
-   * The name of the payment terms translated to the buyer's current language, such as "Net 30" or "Due on receipt". See [localization.language](/docs/api/customer-account-ui-extensions/{API_VERSION}/apis/localization#properties-propertydetail-localization).
+   * The name of the payment terms translated to the buyer's current language, such as "Net 30" or "Due on receipt". See [localization.language](/docs/api/customer-account-ui-extensions/{API_VERSION}/target-apis/platform-apis/localization-api#docsstandardlocalizationapi-propertydetail-localization).
    */
   name: string;
   /**

package/src/surfaces/point-of-sale/events/transaction-complete-event.ts

@@ -17,6 +17,10 @@ interface BaseTransactionCompleteEvent {
    * The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` when order creation is pending.
    */
   readonly orderId?: number;
+  /**
+   * The source identifier POS assigned to this transaction. Matches the `sourceIdentifier` of the order this transaction belongs to. Returns `undefined` when POS didn't assign one.
+   */
+  readonly sourceIdentifier?: string;
   /**
    * The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association.
    */
@@ -29,6 +33,10 @@ interface BaseTransactionCompleteEvent {
    * The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify.
    */
   readonly taxTotal: Money;
+  /**
+   * Whether the prices in this transaction include taxes (tax-inclusive pricing), rather than taxes being added on top. Matches the `taxesIncluded` field on the `Order` object in the GraphQL Admin API. Returns `undefined` when this information isn't available.
+   */
+  readonly taxesIncluded?: boolean;
   /**
    * The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations.
    */
@@ -38,11 +46,11 @@ interface BaseTransactionCompleteEvent {
    */
   readonly grandTotal: Money;
   /**
-   * An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount tendered, and currency. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal`.
+   * An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount, and currency. For cash payments on sales, the amount is the cash the customer handed over, so it can exceed the amount owed. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal` plus any `cashRoundingAdjustment`.
    */
   readonly paymentMethods: Payment[];
   /**
-   * The remaining balance still owed on this transaction as a `Money` object. Typically zero for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: grandTotal minus sum of all payment amounts.
+   * The remaining balance still owed on this transaction as a `Money` object. Typically zero for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: `grandTotal` plus any `cashRoundingAdjustment`, minus the sum of all payment amounts. In a split payment where an earlier cash payment already gave change, a balance that is still unpaid is reported as a positive amount without subtracting that change.
    */
   readonly balanceDue: Money;
   /**
@@ -62,7 +70,7 @@ interface BaseTransactionCompleteEvent {
    */
   readonly tipAmount?: Money;
   /**
-   * The cash rounding adjustment applied to this transaction as a `Money` object. Returns `undefined` when no cash rounding adjustment was applied.
+   * The cash rounding adjustment applied to this transaction as a `Money` object. Positive when the cash total was rounded up and negative when it was rounded down. Returns `undefined` when no cash rounding adjustment was applied.
    */
   readonly cashRoundingAdjustment?: Money;
 }

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

@@ -19,6 +19,10 @@ export interface BaseTransactionComplete {
    * The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` for transactions that don't create orders (for example, reprints) or when order creation is pending.
    */
   orderId?: number;
+  /**
+   * The source identifier POS assigned to this transaction. Matches the `sourceIdentifier` of the order this transaction belongs to. Returns `undefined` when POS didn't assign one.
+   */
+  sourceIdentifier?: string;
   /**
    * The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association.
    */
@@ -31,6 +35,10 @@ export interface BaseTransactionComplete {
    * The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify.
    */
   taxTotal: Money;
+  /**
+   * Whether the prices in this transaction include taxes (tax-inclusive pricing), rather than taxes being added on top. Matches the `taxesIncluded` field on the `Order` object in the GraphQL Admin API. Returns `undefined` when this information isn't available.
+   */
+  taxesIncluded?: boolean;
   /**
    * The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations.
    */
@@ -40,11 +48,11 @@ export interface BaseTransactionComplete {
    */
   grandTotal: Money;
   /**
-   * An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount tendered, and currency. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal`.
+   * An array of all payment methods used to complete this transaction. Each payment entry specifies the payment type (for example, cash, credit card), amount, and currency. For cash payments on sales, the amount is the cash the customer handed over, so it can exceed the amount owed. Multiple entries indicate split payments where the customer paid using multiple methods (for example, part cash, part credit card). The sum of all payment amounts should equal or exceed the `grandTotal` plus any `cashRoundingAdjustment`.
    */
   paymentMethods: Payment[];
   /**
-   * The remaining balance still owed on this transaction as a `Money` object. Typically `{amount: 0, currency: "USD"}` for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: grandTotal minus sum of all payment amounts.
+   * The remaining balance still owed on this transaction as a `Money` object. Typically `{amount: 0, currency: "USD"}` for fully paid transactions. A positive balance indicates partial payment or layaway scenarios. A negative balance indicates overpayment, where change should be returned to the customer. Calculated as: `grandTotal` plus any `cashRoundingAdjustment`, minus the sum of all payment amounts. In a split payment where an earlier cash payment already gave change, a balance that is still unpaid is reported as a positive amount without subtracting that change.
    */
   balanceDue: Money;
   /**
@@ -64,7 +72,7 @@ export interface BaseTransactionComplete {
    */
   tipAmount?: Money;
   /**
-   * The cash rounding adjustment applied to this transaction as a `Money` object. Returns `undefined` when no cash rounding adjustment was applied.
+   * The cash rounding adjustment applied to this transaction as a `Money` object. Positive when the cash total was rounded up and negative when it was rounded down. Returns `undefined` when no cash rounding adjustment was applied.
    */
   cashRoundingAdjustment?: Money;
 }

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

@@ -20,7 +20,7 @@ export type PaymentMethod =
  */
 export interface Payment {
   /**
-   * The payment amount.
+   * The payment amount. For cash payments on `Sale` transactions in POS 11.16.0 and later, this is the cash the customer handed over, including any change given back. For other payment methods, other transaction types, and cash in earlier POS versions, it's the amount recorded on the payment transaction.
    */
   amount: number;
   /**