@shopify/ui-extensions 2026.10.0-rc.8 → 2026.10.0

package/src/surfaces/checkout/api/address-autocomplete/format-suggestion.ts

@@ -1,3 +1,5 @@
+import type {AcceptedAddressInputField} from '../../../../shared';
+
 import type {
   AddressAutocompleteSuggestion,
   AutocompleteAddress,
@@ -15,6 +17,13 @@ export interface AddressAutocompleteFormatSuggestionApi {
 
 interface Target {
   selectedSuggestion: AddressAutocompleteSuggestion;
+
+  /**
+   * The inputs the address form being populated accepts. Use it to decide
+   * which fields to fill; the output isn't validated against it. `undefined`
+   * until the address format loads.
+   */
+  acceptedAddressInputFields?: AcceptedAddressInputField[];
 }
 
 /** @publicDocs */

package/src/surfaces/checkout/api/address-autocomplete/shared.ts

@@ -1,4 +1,5 @@
 import type {MailingAddress} from '../../../checkout';
+import type {AddressLineComponents} from '../shared';
 
 /**
  * An address object used to auto-populate the address form fields.
@@ -11,12 +12,20 @@ export interface AutocompleteAddress
     MailingAddress,
     | 'address1'
     | 'address2'
+    | 'addressCode'
     | 'city'
     | 'company'
     | 'countryCode'
     | 'provinceCode'
     | 'zip'
   > {
+  /**
+   * Components of `address1`/`address2`. Always send the flat lines as well: a
+   * form without component inputs ignores the components, so a components-only
+   * suggestion clears both lines in that form.
+   */
+  addressLineComponents?: AddressLineComponents;
+
   /**
    * The latitude coordinates of the buyer.
    *

package/src/surfaces/checkout/api/address-autocomplete/standard.ts

@@ -14,10 +14,9 @@ import type {
   Storage,
   Version,
 } from '../standard/standard';
-import type {Attribute, MailingAddress} from '../shared';
+import type {Attribute, Country, MailingAddress} from '../shared';
 import type {
   ApiVersion,
-  Country,
   GraphQLError,
   StorefrontApiVersion,
   Timezone,

package/src/surfaces/checkout/api/address-autocomplete/suggest.ts

@@ -1,3 +1,4 @@
+import type {AcceptedAddressInputField} from '../../../../shared';
 import type {CountryCode} from '../../../checkout';
 
 import type {AddressAutocompleteSuggestion} from './shared';
@@ -50,6 +51,13 @@ interface Target {
    * @example 'CA' for Canada.
    */
   selectedCountryCode?: CountryCode;
+
+  /**
+   * The inputs the address form accepts for `selectedCountryCode`. Use it to
+   * decide which fields to suggest; suggestions aren't validated against it.
+   * `undefined` until the address format loads.
+   */
+  acceptedAddressInputFields?: AcceptedAddressInputField[];
 }
 
 /** @publicDocs */

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

@@ -1,9 +1,5 @@
-import type {
-  Attribute,
-  SellingPlan,
-  MailingAddress,
-  ShippingAddress,
-} from '../shared';
+import type {AcceptedAddressInputField} from '../../../../shared';
+import type {Attribute, SellingPlan, ShippingAddress} from '../shared';
 
 /**
  * Clears the buyer's note from the checkout. Pass this to `applyNoteChange()` to remove any existing note.
@@ -578,7 +574,11 @@ export interface ShippingAddressUpdateChange {
   /**
    * Fields to update in the shipping address. You only need to provide
    * values for the fields you want to update. Any fields you don't list
-   * keep their current values.
+   * keep their current values. Address line components are written nested
+   * under `addressLineComponents`, the same shape they're read.
+   *
+   * @example
+   * {countryCode: 'BR', addressLineComponents: {streetName: 'Avenida Paulista', streetNumber: '1578'}}
    */
   address: Partial<ShippingAddress>;
 }
@@ -606,15 +606,25 @@ export interface ShippingAddressChangeResultSuccess {
   errors: null;
 }
 
+/**
+ * The input a shipping address change failed on: an accepted input, `'name'`,
+ * or `'addressLineComponents'` when the components object itself is invalid.
+ * @publicDocs
+ */
+export type ShippingAddressChangeErrorField =
+  | AcceptedAddressInputField
+  | 'addressLineComponents'
+  | 'name';
+
 /**
  * An error corresponding to a particular field from a given change. Use the `field` property to determine which address field caused the error.
  * @publicDocs
  */
 export interface ShippingAddressChangeFieldError {
   /**
-   * The `MailingAddress` field that caused the error, such as `'countryCode'` or `'zip'`. The value is `undefined` if the error isn't specific to a single field.
+   * The address input that caused the error, such as `'countryCode'` or `'zip'`, or an address line component such as `'streetName'`. The value is `undefined` if the error isn't specific to a single input.
    */
-  field?: keyof MailingAddress;
+  field?: ShippingAddressChangeErrorField;
 
   /**
    * A message that explains the error. This message is useful for debugging.

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

@@ -1,4 +1,25 @@
-import type {CountryCode} from '../../../shared';
+import type {AcceptedAddressInputField, CountryCode} from '../../../shared';
+
+/**
+ * A buyer's country, identified by its ISO country code.
+ * @publicDocs
+ */
+export interface Country {
+  /**
+   * The two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
+   *
+   * @example 'CA' for Canada, 'US' for United States.
+   */
+  isoCode: CountryCode;
+  /**
+   * The address inputs this country's format carries, as guidance for what to
+   * write: `applyShippingAddressChange` does not validate a change against
+   * this list. A country that carries a line component lists the flat line
+   * too, so either can be written. Listed inputs may be optional or hidden
+   * from the buyer. `undefined` until the address format loads.
+   */
+  acceptedAddressInputFields?: AcceptedAddressInputField[];
+}
 
 /** @publicDocs */
 export interface ValidationError {
@@ -67,6 +88,59 @@ export interface Attribute {
   value: string;
 }
 
+/**
+ * Components of the `address1`/`address2` lines on a `MailingAddress`, for
+ * countries whose address format accepts them.
+ * @publicDocs
+ */
+export interface AddressLineComponents {
+  /**
+   * The street name, without the number.
+   *
+   * {% 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 'Avenida Paulista'
+   */
+  streetName?: string;
+
+  /**
+   * The house or building number.
+   *
+   * {% 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 '1578'
+   */
+  streetNumber?: string;
+
+  /**
+   * Additional address information (e.g. 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).
+   *
+   * @example 'Apto 42'
+   */
+  additionalInformation?: string;
+
+  /**
+   * A regional or city subdivision (e.g. 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).
+   *
+   * @example 'Bela Vista'
+   */
+  district?: string;
+
+  /**
+   * A finer subdivision within `district`, when the country uses both.
+   *
+   * {% 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 'Kelurahan Menteng'
+   */
+  subdistrict?: string;
+}
+
 /** @publicDocs */
 export interface MailingAddress {
   /**
@@ -134,6 +208,41 @@ 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.
+   *
+   * {% 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
+   * {
+   *   streetName: 'Avenida Paulista',
+   *   streetNumber: '1578',
+   *   additionalInformation: 'Apto 42',
+   *   district: 'Bela Vista'
+   * }
+   */
+  addressLineComponents?: AddressLineComponents;
+
+  /**
+   * A postal or national address code that identifies the address
+   * independently of its street lines, used by countries such as Saudi
+   * Arabia. The value is `undefined` if the country doesn't use one or it
+   * hasn't been provided.
+   *
+   * {% 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 'RRRR1234'
+   */
+  addressCode?: string;
+
   /**
    * The city, town, or village of the address. The value is `undefined` if
    * the buyer hasn't entered a city yet.

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

@@ -2,15 +2,16 @@ import type {
   ValidationError,
   SellingPlan,
   Attribute,
+  Country,
   MailingAddress,
   ShippingAddress,
 } from '../shared';
 import type {ExtensionTarget} from '../../extension-targets';
 import type {
+  AcceptedAddressInputField,
   ApiVersion,
   Capability,
   CurrencyCode,
-  Country,
   CountryCode,
   Timezone,
   GraphQLError,
@@ -433,6 +434,15 @@ export interface Localization {
    */
   country: SubscribableSignalLike<Country | undefined>;
 
+  /**
+   * The inputs `applyShippingAddressChange` accepts for `countryCode`. Resolves
+   * to an empty array if shipping restrictions exclude the country. Rejects if
+   * the address format cannot be loaded.
+   */
+  acceptedAddressInputFieldsForCountry(
+    countryCode: CountryCode,
+  ): Promise<AcceptedAddressInputField[]>;
+
   /**
    * The [market](/docs/apps/build/markets) context of the checkout,
    * carried over from the cart context. Markets group countries and

package/src/surfaces/checkout/components/Box.d.ts

@@ -8,7 +8,7 @@
 /* eslint-disable import-x/namespace */
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {BoxProps$1,MaybeAllValuesShorthandProperty,BorderSizeKeyword, BorderStyleKeyword,ColorKeyword} from './components-shared.d.ts';
+import type {BoxProps$1,MaybeAllValuesShorthandProperty,BorderSizeKeyword, BorderStyleKeyword, SizeUnits,ColorKeyword} from './components-shared.d.ts';
 
 /**
  * The subset of border size values available for this component.
@@ -84,6 +84,61 @@ export interface BoxElementProps extends Pick<BoxProps$1, 'accessibilityLabel' |
      * @default 'none'
      */
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<BoxProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
+    /**
+     * Sets the box's block position by specifying offsets from the box's
+     * default position, following the CSS `inset-block` shorthand:
+     * a block-start offset followed by a block-end offset, where only one
+     * of the two can be a size so each axis is only offset once.
+     *
+     * When `position` is set to `absolute`, offsets are insets from the
+     * nearest positioned ancestor. A percentage value refers to the block
+     * size of that ancestor.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/inset-block
+     *
+     * @default 'auto'
+     * @private
+     */
+    insetBlock?: `auto ${SizeUnits}` | `${SizeUnits} auto` | 'auto';
+    /**
+     * Sets the box's inline position by specifying offsets from the box's
+     * default position, following the CSS `inset-inline` shorthand:
+     * an inline-start offset followed by an inline-end offset, where only
+     * one of the two can be a size so each axis is only offset once.
+     *
+     * When `position` is set to `absolute`, offsets are insets from the
+     * nearest positioned ancestor. A percentage value refers to the inline
+     * size of that ancestor.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/inset-inline
+     *
+     * @default 'auto'
+     * @private
+     */
+    insetInline?: `auto ${SizeUnits}` | `${SizeUnits} auto` | 'auto';
+    /**
+     * Changes how the box is positioned.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/position
+     *
+     * @default 'relative'
+     * @private
+     */
+    position?: 'absolute' | 'relative';
+    /**
+     * Specifies a transformation of the box.
+     *
+     * Only two-dimensional translations are supported. The first value
+     * translates along the inline axis and the second along the block axis;
+     * inline translations are flipped in right-to-left writing modes.
+     * A percentage value refers to the corresponding size of the box itself.
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/transform
+     *
+     * @default 'none'
+     * @private
+     */
+    transform?: `translate(${SizeUnits})` | `translate(${SizeUnits}, ${SizeUnits})` | `translate(${SizeUnits},${SizeUnits})` | 'none';
 }
 export interface BoxElement extends BoxElementProps, Omit<HTMLElement, 'id'> {
 }

package/src/surfaces/checkout/components/MoneyField.d.ts

@@ -46,7 +46,8 @@ export interface MoneyFieldElementEvents {
      */
     blur?: CallbackEventListener<typeof tagName>;
     /**
-     * A callback fired when the money field value changes.
+     * A callback fired when the money field value is committed on blur or after pressing Enter.
+     * Also fired on each step when using the Up Arrow and Down Arrow keys.
      *
      * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
@@ -59,6 +60,7 @@ export interface MoneyFieldElementEvents {
     focus?: CallbackEventListener<typeof tagName>;
     /**
      * A callback fired when the user inputs data into the money field.
+     * Also fired on each step when using the Up Arrow and Down Arrow keys.
      *
      * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
      */

package/src/surfaces/checkout/components/NumberField.d.ts

@@ -88,7 +88,8 @@ export interface NumberFieldElementEvents {
      */
     blur?: CallbackEventListener<typeof tagName>;
     /**
-     * A callback fired when the number field value changes.
+     * A callback fired when the number field value is committed on blur or after pressing Enter.
+     * Also fired on each step when using the increment/decrement controls or the Up Arrow and Down Arrow keys.
      *
      * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
@@ -101,6 +102,7 @@ export interface NumberFieldElementEvents {
     focus?: CallbackEventListener<typeof tagName>;
     /**
      * A callback fired when the user inputs data into the number field.
+     * Also fired on each step when using the increment/decrement controls or the Up Arrow and Down Arrow keys.
      *
      * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
      */

package/src/surfaces/checkout/components/components-shared.d.ts

@@ -1384,7 +1384,7 @@ export interface ButtonBehaviorProps extends InteractionProps, FocusEventProps {
 }
 export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 	/**
-	 * The URL to navigate to when clicked. The `click` event fires first, then navigation occurs. If `commandFor` is also set, the command executes instead of navigation.
+	 * The URL to navigate to when clicked, including `mailto:` and `tel:` URLs. The `click` event fires first, then navigation occurs. If `commandFor` is also set, the command executes instead of navigation.
 	 */
 	href?: string;
 	/**

package/src/surfaces/checkout/preact/country.ts

@@ -1,5 +1,5 @@
 import type {RenderExtensionTarget} from '../extension-targets';
-import type {Country} from '../../../shared';
+import type {Country} from '../api/shared';
 
 import {useApi} from './api';
 import {useSubscription} from './subscription';

package/src/surfaces/checkout.ts

@@ -79,7 +79,9 @@ export type {
 } from './checkout/api/standard/standard';
 
 export type {
+  AddressLineComponents,
   Attribute,
+  Country,
   SellingPlan,
   ValidationError,
   MailingAddress,
@@ -134,6 +136,7 @@ export type {
   NoteChangeResultError,
   ShippingAddressChange,
   ShippingAddressChangeFieldError,
+  ShippingAddressChangeErrorField,
   ShippingAddressChangeResult,
   ShippingAddressChangeResultError,
   ShippingAddressChangeResultSuccess,

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

@@ -5,7 +5,6 @@ import type {
   Capability,
   CurrencyCode,
   Timezone,
-  Country,
   CountryCode,
   GraphQLError,
   StorefrontApiVersion,
@@ -18,13 +17,24 @@ export {
   Capability,
   CurrencyCode,
   Timezone,
-  Country,
   CountryCode,
   GraphQLError,
   StorefrontApiVersion,
   SubscribableSignalLike,
 };
 
+/**
+ * A buyer's country, identified by its ISO country code.
+ */
+export interface Country {
+  /**
+   * The two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
+   *
+   * @example 'CA' for Canada, 'US' for United States.
+   */
+  isoCode: CountryCode;
+}
+
 /**
  * Persists key-value data across customer sessions for a specific extension target. Use storage to save preferences, dismiss states, or cached data that should survive page reloads without requiring a backend call.
  *
@@ -347,24 +357,32 @@ export interface AuthenticatedAccount {
   /**
    * The authenticated customer's account information. The value is `undefined` if the customer isn't logged in.
    */
-  customer: SubscribableSignalLike<Customer | undefined>;
+  customer: SubscribableSignalLike<AuthenticatedAccountCustomer | undefined>;
 }
 
 /**
- * The authenticated customer's account, identified by a globally-unique ID.
+ * The authenticated customer's account, identified by a numeric customer ID represented as a string.
  *
  * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
- * @publicDocs
+ * @deprecated Use `AuthenticatedAccountCustomer` instead.
  */
 export interface Customer {
   /**
-   * A globally-unique identifier for the customer in the format `gid://shopify/Customer/<id>`.
+   * The customer's numeric ID represented as a string.
    *
-   * @example 'gid://shopify/Customer/123'
+   * @example '123'
    */
   id: string;
 }
 
+/**
+ * The authenticated customer's account, identified by a numeric customer ID represented as a string.
+ *
+ * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
+ * @publicDocs
+ */
+export interface AuthenticatedAccountCustomer extends Customer {}
+
 /**
  * @publicDocs
  */

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

@@ -61,6 +61,7 @@ export type {
   Language,
   Storage,
   AuthenticatedAccount,
+  AuthenticatedAccountCustomer,
   PurchasingCompany,
   Company,
   Customer,

package/src/surfaces/customer-account/preact/authenticated-account.ts

@@ -1,17 +1,17 @@
 import type {RenderExtensionTarget} from '../extension-targets';
-import type {Customer, PurchasingCompany} from '../api';
+import type {AuthenticatedAccountCustomer, PurchasingCompany} from '../api';
 
 import {useApi} from './api';
 import {useSubscription} from './subscription';
 
 /**
- * Returns the current authenticated `Customer`.
+ * Returns the current `AuthenticatedAccountCustomer`.
  *
  * The value is `undefined` if the customer isn't authenticated.
  */
 export function useAuthenticatedAccountCustomer<
   Target extends RenderExtensionTarget,
->(): Customer | undefined {
+>(): AuthenticatedAccountCustomer | undefined {
   const account = useApi<Target>().authenticatedAccount;
 
   return useSubscription(account.customer);

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

@@ -138,6 +138,20 @@ export interface MutableCartApiContent {
     options?: AddLineItemOptions,
   ): Promise<string>;
 
+  /**
+   * Set the quantity of an existing line item identified by its `UUID`, preserving the line item's properties, discounts, and selling plans. This is equivalent to a merchant adjusting the quantity on the native cart line.
+   *
+   * If POS has split the line into multiple allocations that share the same `UUID` (for example, lines split across delivery methods), the target line is ambiguous and the call throws instead of guessing.
+   *
+   * Only available on API version `2026-10` and later.
+   *
+   * @param uuid the UUID of the line item to update
+   * @param quantity the new absolute quantity; must be an integer of 1 or greater. To remove a line item, use `removeLineItem` instead.
+   * @returns A promise that resolves after the cart state reflects the change.
+   * @throws {Error} if the line item is not found, the `UUID` matches multiple split-line allocations, the quantity is invalid, the cart is not editable because it is a return or exchange, or the POS app version does not support this method.
+   */
+  updateLineItemQuantity(uuid: string, quantity: number): Promise<void>;
+
   /**
    * Remove a specific line item from the cart using its `UUID`. The line item will be completely removed from the cart along with any associated discounts, properties, or selling plans.
    *

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

@@ -11,6 +11,10 @@ export interface DeviceApiContent {
    * A short, unique identifier for the device, assigned by Shopify.
    */
   registerName: string;
+  /**
+   * The Shopify-assigned fiscal register identifier for the device, such as Sweden's manufacturing number (tillverkningsnummer).
+   */
+  fiscalDeviceIdentifier?: string;
   /**
    * Retrieves the unique string identifier for the device. Returns a promise that resolves to the device ID. Use for device-specific data storage, analytics tracking, or implementing device-based permissions and configurations.
    * Note: While Shopify POS attempts to maintain a stable identifier, it is not guaranteed to be permanent and may change.

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

@@ -9,3 +9,11 @@ export interface Docs_AppBackgroundEventMethods
     BackgroundShopifyGlobal,
     'addEventListener' | 'removeEventListener'
   > {}
+
+/**
+ * Validation interceptor method available on the `shopify` global for app
+ * background extensions.
+ * @publicDocs
+ */
+export interface Docs_AppBackgroundInterceptMethods
+  extends Pick<BackgroundShopifyGlobal, 'intercept'> {}

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

@@ -7,15 +7,16 @@ import type {ApiVersion} from '../../../../shared';
  * multiple targets. Access these properties through `shopify.extension`.
  *
  * @example
- * <caption>Read the API version and active target</caption>
- * <description>Display the configured API version and the active extension target. Use `shopify.extension.apiVersion` for version-aware logic and `shopify.extension.target` when a single module handles multiple targets.</description>
+ * <caption>Read the API version, published version, and active target</caption>
+ * <description>Display the configured API version, the published app version this build was deployed in, and the active extension target. Use `shopify.extension.apiVersion` for version-aware logic, `shopify.extension.version` to report which build a merchant is running, and `shopify.extension.target` when a single module handles multiple targets.</description>
  * ```jsx
  * const Extension = () => {
- *   const {apiVersion, target} = shopify.extension;
+ *   const {apiVersion, version, target} = shopify.extension;
  *   return (
  *     <s-page heading="Extension Info">
  *       <s-stack direction="block">
  *         <s-text>API Version: {apiVersion}</s-text>
+ *         <s-text>Version: {version ?? 'development build'}</s-text>
  *         <s-text>Target: {target}</s-text>
  *       </s-stack>
  *     </s-page>
@@ -38,12 +39,31 @@ export interface ExtensionApiContent<T> {
    * @example 'pos.home.tile.render', 'pos.home.modal.render'
    */
   target: T;
+  /**
+   * The name of the published app version that this extension was deployed in.
+   * This is the same name shown on the Versions page of your dev dashboard, and
+   * the name you choose when you run `shopify app deploy`.
+   *
+   * Use it to tell which build of your extension a merchant is running. POS
+   * caches extension bundles and runs them offline, so a device can stay on an
+   * older version for some time after you deploy a new one.
+   *
+   * This is an opaque name, not a version number. Compare it for equality; don't
+   * sort it or read parts out of it.
+   *
+   * `undefined` when the extension runs from a local development server, because
+   * a build that hasn't been deployed has no published version.
+   *
+   * @example 'restaurant-table-manager-2', 'casa-loyalty-493'
+   */
+  version?: string;
 }
 
 /**
  * The `ExtensionApi` object provides metadata about the currently running
- * extension, including the configured API version and the active extension
- * target. Access these properties through `shopify.extension`.
+ * extension, including the configured API version, the published app version it
+ * was deployed in, and the active extension target. Access these properties
+ * through `shopify.extension`.
  * @publicDocs
  */
 export interface ExtensionApi<T> {