Enrich JSDoc for Platform APIs property descriptions, 2026-01

Port enriched JSDoc descriptions from checkout-web to ui-extensions
2026-01. Covers Analytics, Extension, Localization, Metafields,
Session Token, Settings, Shop, Storage, and Storefront APIs.

Every description verified against the 2026-01 TypeScript types.

Partially closes shop/issues-learn#1046

Made-with: Cursor

Author: SteveSill

packages/ui-extensions/src/surfaces/checkout/api/standard/standard.ts

@@ -22,14 +22,11 @@ import type {SubscribableSignalLike} from '../../shared';
 export type {ApiVersion, Capability} from '../../../../shared';
 
 /**
- * A key-value storage object for the extension.
- *
- * Stored data is available only to this specific extension
- * and any of its instances.
- *
- * The storage backend is implemented with `localStorage` and
- * should persist across the buyer's checkout session.
- * However, data persistence isn't guaranteed.
+ * Persists key-value data across the buyer's session for a specific extension.
+ * Use storage to save preferences, dismiss states, or cached data that should
+ * survive page reloads without requiring a backend call. Stored data is only
+ * available to this specific extension. The storage backend is implemented with
+ * `localStorage` and data persistence isn't guaranteed.
  */
 export interface Storage {
   /**
@@ -50,13 +47,16 @@ export interface Storage {
   write(key: string, data: any): Promise<void>;
 
   /**
-   * Delete stored data by key.
+   * Delete a previously stored value by key. Use this instead of writing `null`
+   * or an empty string to cleanly remove an entry from storage.
    */
   delete(key: string): Promise<void>;
 }
 
 /**
- * The meta information about an extension target.
+ * Metadata about the running extension, including its API version, target,
+ * capabilities, and editor context. Use this to read configuration details or
+ * conditionally render content based on where the extension is running.
  */
 export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   /**
@@ -130,6 +130,11 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   version?: string;
 }
 
+/**
+ * Information about the editor environment when an extension is rendered
+ * inside the editor. The value is `undefined` when the extension is not
+ * rendering in an editor.
+ */
 export interface Editor {
   /**
    * Indicates whether the extension is rendering in the [checkout editor](https://shopify.dev/docs/apps/checkout). Always `'checkout'`.
@@ -294,9 +299,9 @@ export type Version = string;
 export type CheckoutToken = string;
 
 /**
- * This returns a translated string matching a key in a locale file.
- *
- * @example translate("banner.title")
+ * Translates a key from your extension's locale files into a localized string.
+ * Supports interpolation with placeholder replacements and pluralization
+ * via the special `count` option.
  */
 export interface I18nTranslate {
   <ReplacementType = string>(
@@ -307,6 +312,11 @@ export interface I18nTranslate {
     : (string | ReplacementType)[];
 }
 
+/**
+ * Utilities for translating strings, formatting currencies, numbers,
+ * and dates according to the buyer's locale. Use the I18n API alongside
+ * the Localization API to build fully localized extensions.
+ */
 export interface I18n {
   /**
    * Returns a localized number.
@@ -389,6 +399,11 @@ export interface Market {
   handle: string;
 }
 
+/**
+ * The buyer's language, country, and locale context. Properties on this
+ * interface are subscribable and update automatically when the buyer's
+ * locale changes.
+ */
 export interface Localization {
   /**
    * The currency that the buyer sees for money amounts in the checkout. Use this value to format prices and totals in the buyer's expected currency.
@@ -539,7 +554,10 @@ export interface BuyerJourneyStep {
 
 export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
-   * The methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
+   * Methods for publishing custom events to [Web Pixels](https://shopify.dev/docs/apps/marketing) and
+   * submitting visitor contact details to the shop backend. Use `publish()` to
+   * emit events that web pixels can listen to, and `visitor()` to send buyer
+   * contact information for attribution.
    */
   analytics: Analytics;
 
@@ -639,7 +657,9 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   discountAllocations: SubscribableSignalLike<CartDiscountAllocation[]>;
 
   /**
-   * The meta information about the extension.
+   * Metadata about the running extension, including the current target, API version,
+   * granted capabilities, and editor context. Use this to check permissions, detect
+   * the editor preview, or read the published version.
    */
   extension: Extension<Target>;
 
@@ -657,12 +677,10 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   extensionPoint: Target;
 
   /**
-   * Utilities for translating content and formatting values according to the current
+   * Utilities for translating strings, formatting currencies, numbers, and dates
+   * according to the buyer's locale. Use alongside
    * [`localization`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/localization)
-   * of the checkout.
-   *
-   * Refer to [`localization` examples](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/localization#examples)
-   * for more information.
+   * to build fully localized extensions.
    */
   i18n: I18n;
 
@@ -672,10 +690,11 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   lines: SubscribableSignalLike<CartLine[]>;
 
   /**
-   * The details about the location, language, and currency of the customer. For utilities to easily
-   * format and translate content based on these details, you can use the
+   * The buyer's language, country, currency, market, and timezone context. Properties
+   * are subscribable and update when the buyer changes their shipping address. For
+   * formatting and translation helpers, use
    * [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/{API_VERSION}/apis/localization#standardapi-propertydetail-i18n)
-   * object instead.
+   * instead.
    */
   localization: Localization;
 
@@ -761,18 +780,21 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   billingAddress?: SubscribableSignalLike<MailingAddress | undefined>;
 
-  /** The shop where the checkout is taking place. */
+  /**
+   * The store where the checkout is taking place, including the shop name,
+   * primary domain, `.myshopify.com` subdomain, and globally-unique ID.
+   * Use this to display store branding or route backend requests by shop.
+   */
   shop: Shop;
 
   /**
-   * The key-value storage for the extension.
-   *
-   * It uses `localStorage` and should persist across the customer's current checkout session.
+   * Key-value storage that persists across page loads within the current checkout
+   * session. Use this to save dismissed states, form progress, or cached data
+   * without a backend call. Data is shared across all activated extension targets
+   * of this extension.
    *
-   * > Caution: Data persistence isn't guaranteed and storage is reset when the customer starts a new checkout.
-   *
-   * Data is shared across all activated extension targets of this extension. In versions 2023-07 and earlier,
-   * each activated extension target had its own storage.
+   * > Caution: Data persistence isn't guaranteed. The storage backend uses
+   * `localStorage` and is cleared when the buyer starts a new checkout.
    */
   storage: Storage;
 
@@ -803,6 +825,12 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   localizedFields?: SubscribableSignalLike<LocalizedField[]>;
 }
 
+/**
+ * Authenticates requests between your extension and your app backend.
+ * Use session tokens to verify the identity of the customer and the shop
+ * context when making server-side API calls. The token is a signed JWT
+ * that contains claims such as the customer ID, shop domain, and expiration.
+ */
 export interface SessionToken {
   /**
    * Requests a session token that hasn't expired. You should call this method every
@@ -930,6 +958,10 @@ export interface AppliedGiftCard {
   balance: Money;
 }
 
+/**
+ * Read-only metadata about the merchant's store, including its name, primary
+ * domain, `.myshopify.com` subdomain, and globally-unique ID.
+ */
 export interface Shop {
   /**
    * A globally-unique identifier for the shop in the format `gid://shopify/Shop/<id>`.
@@ -1568,14 +1600,24 @@ export type ExtensionSettings = Record<
   string | number | boolean | undefined
 >;
 
+/**
+ * Methods for interacting with Shopify's analytics framework. Use `publish()` to
+ * emit custom events that all registered [Web Pixels](https://shopify.dev/docs/apps/marketing) on
+ * the page can listen to, and `visitor()` to submit buyer contact details
+ * directly to the shop backend for attribution.
+ */
 export interface Analytics {
   /**
-   * Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing).
+   * Emits a custom event to all [Web Pixels](https://shopify.dev/docs/apps/marketing) registered
+   * on the page. The event isn't sent to the shop backend. Returns `true` when
+   * the event is successfully dispatched.
    */
   publish(name: string, data: Record<string, unknown>): Promise<boolean>;
 
   /**
-   * A method for capturing details about a visitor on the online store.
+   * Submits buyer contact details to the shop backend for attribution and
+   * analytics purposes. Unlike `publish()`, this data isn't forwarded to
+   * web pixels on the page.
    */
   visitor(data: {email?: string; phone?: string}): Promise<VisitorResult>;
 }