Platform APIs: improve descriptions and JSDoc for 2025-10

sordaz00 · sordaz00 · commit b7a710b6ac39 · 2026-03-25T11:01:42.000-05:00
Made-with: Cursor
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/generated/customer_account_ui_extensions/2025-10/generated_category_pages.json b/packages/ui-extensions/docs/surfaces/customer-account/generated/customer_account_ui_extensions/2025-10/generated_category_pages.json
@@ -0,0 +1 @@
+[]
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/generated/customer_account_ui_extensions/2025-10/generated_docs_data.json b/packages/ui-extensions/docs/surfaces/customer-account/generated/customer_account_ui_extensions/2025-10/generated_docs_data.json
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/generated/customer_account_ui_extensions/2025-10/generated_static_pages.json b/packages/ui-extensions/docs/surfaces/customer-account/generated/customer_account_ui_extensions/2025-10/generated_static_pages.json
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/analytics.doc.ts
@@ -4,15 +4,16 @@ import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Analytics API',
-  description: 'The API for interacting with web pixels.',
+  description: 'The Analytics API lets you track custom events and send visitor information to [Web Pixels](/docs/apps/marketing). Use this API to emit analytics events from your extension, such as tracking product views, button clicks, or conversion funnels.',
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
   type: 'API',
   definitions: [
     {
       title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title,
-      description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description,
+      description:
+        'The `AnalyticsApi` object provides methods for tracking events and visitor data. Access the following properties on the `AnalyticsApi` object to emit custom analytics events and submit visitor information to Web Pixels.',
       type: 'Docs_Standard_AnalyticsApi',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/extension.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/extension.doc.ts
@@ -4,15 +4,16 @@ import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Extension API',
-  description: 'The API for interacting with the metadata of an extension.',
+  description: 'The Extension API lets you access metadata about your extension at runtime, including its [target](/docs/api/customer-account-ui-extensions/{API_VERSION}/extension-targets-overview), version, and editor context. Use this API to conditionally render content based on where the extension is running or to retrieve configuration details.',
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
   type: 'API',
   definitions: [
     {
       title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title,
-      description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description,
+      description:
+        'The `ExtensionApi` object provides metadata about the running extension. Access the following properties on the `ExtensionApi` object to read the extension target, editor context, and capabilities.',
       type: 'Docs_Standard_ExtensionApi',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/localization.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/localization.doc.ts
@@ -4,15 +4,16 @@ import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Localization API',
-  description: 'The API for localizing your extension.',
+  description: 'The Localization API lets you adapt your extension to the language, country, and locale of the buyer. Use this API to [translate strings](/docs/apps/build/customer-accounts/localization/localize), format currencies and dates, and display region-specific content.',
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
   type: 'API',
   definitions: [
     {
       title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title,
-      description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description,
+      description:
+        "The `LocalizationApi` object provides the buyer's language, country, and locale context. Access the following properties on the `LocalizationApi` object to translate content, format values, and adapt your extension to the buyer's region.",
       type: 'Docs_Standard_LocalizationApi',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/navigation.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/navigation.doc.ts
@@ -3,8 +3,8 @@ import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 const data: ReferenceEntityTemplateSchema = {
   name: 'Navigation API',
   overviewPreviewDescription:
-    'The API provided to extensions to navigate to extensions or host page.',
-  description: `The API provided to extensions to navigate to extensions or host page.`,
+    'The Navigation API lets you navigate between pages in customer accounts, including other extensions and host pages.',
+  description: `The Navigation API lets you navigate between pages in customer accounts, including other extensions and host pages. Use this API to link to order details, profile pages, or [custom full-page extensions](/docs/api/customer-account-ui-extensions/{API_VERSION}#custom-protocols). Full-page extensions also get access to the current navigation entry and history state.`,
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
@@ -13,7 +13,7 @@ const data: ReferenceEntityTemplateSchema = {
     {
       title: 'Navigation',
       description:
-        'Navigation API for all extensions. [Refer to supported protocols](/docs/api/customer-account-ui-extensions/unstable#custom-protocols)',
+        'The `Navigation` object provides methods for navigating between pages in customer accounts. Access the following properties on the `Navigation` object to link to order details, profile pages, or other extensions using [supported protocols](/docs/api/customer-account-ui-extensions/{API_VERSION}#custom-protocols).',
       type: 'Navigation',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/query.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/query.doc.ts
@@ -4,15 +4,16 @@ import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Storefront API',
-  description: 'Querying the Storefront API.',
+  description: 'The Storefront API lets you query the [Storefront GraphQL API](/docs/api/storefront) directly from your extension. Use this API to fetch product data, collection details, or other storefront information without routing requests through your app backend. Requires the [`api_access` capability](/docs/api/customer-account-ui-extensions/configuration#api-access).',
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
   type: 'API',
   definitions: [
     {
       title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title,
-      description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description,
+      description:
+        'The `QueryApi` object provides a pre-authenticated function for querying the Storefront GraphQL API. Access the following properties on the `QueryApi` object to fetch product data, collections, and other storefront information directly from your extension.',
       type: 'Docs_Standard_QueryApi',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/session-token.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/session-token.doc.ts
@@ -4,15 +4,16 @@ import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Session Token API',
-  description: 'The API for interacting with session tokens.',
+  description: 'The Session Token API lets you authenticate 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 includes claims such as the customer ID, shop domain, and expiration time.',
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
   type: 'API',
   definitions: [
     {
       title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title,
-      description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description,
+      description:
+        'The `SessionTokenApi` object provides methods for retrieving signed JWTs. Access the following properties on the `SessionTokenApi` object to authenticate requests to your app backend with customer and shop context.',
       type: 'Docs_Standard_SessionTokenApi',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/settings.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/settings.doc.ts
@@ -4,15 +4,16 @@ import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Settings API',
-  description: 'The API for interacting with merchant settings.',
+  description: 'The Settings API lets you read merchant-defined configuration values for your extension. Use this API to build customizable extensions where merchants can control behavior, labels, or feature toggles through the [extension editor](/docs/api/customer-account-ui-extensions/configuration#settings-definition). Settings update in real time as merchants edit them.',
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
   type: 'API',
   definitions: [
     {
       title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title,
-      description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description,
+      description:
+        'The `SettingsApi` object provides merchant-defined configuration values. Access the following properties on the `SettingsApi` object to read settings that merchants configure in the extension editor, such as text labels, feature toggles, and display options.',
       type: 'Docs_Standard_SettingsApi',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/storage.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/storage.doc.ts
@@ -4,15 +4,16 @@ import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Storage API',
-  description: 'The API for interacting with local storage.',
+  description: 'The Storage API lets you persist key-value data across customer sessions for a specific extension target. Use this API to store preferences, dismiss states, or cached data that should survive page reloads without requiring a backend call.',
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
   type: 'API',
   definitions: [
     {
       title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title,
-      description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description,
+      description:
+        'The `StorageApi` object provides key-value persistence for the extension target. Access the following properties on the `StorageApi` object to read and write data that persists across customer sessions without requiring a backend call.',
       type: 'Docs_Standard_StorageApi',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/toast.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/toast.doc.ts
@@ -4,15 +4,16 @@ import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Toast API',
-  description: 'The API for interacting with toast.',
+  description: 'The Toast API lets you display brief, non-blocking notification messages to the customer. Use this API to confirm successful actions, report errors, or surface contextual feedback without interrupting the customer workflow. For persistent messages, use a [Banner](/docs/api/customer-account-ui-extensions/{API_VERSION}/ui-components/feedback-and-status-indicators/banner) component instead.',
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
   type: 'API',
   definitions: [
     {
       title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title,
-      description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description,
+      description:
+        'The `ToastApi` object provides methods for displaying non-blocking notifications. Access the following properties on the `ToastApi` object to show brief confirmation or error messages in response to customer actions.',
       type: 'Docs_Standard_ToastApi',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/version.doc.ts b/packages/ui-extensions/docs/surfaces/customer-account/reference/apis/version.doc.ts
@@ -4,15 +4,16 @@ import {CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION} from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Version API',
-  description: 'The API for interacting with version.',
+  description: 'The Version API lets you determine which API version your extension is running against. Use this API to conditionally enable features or handle breaking changes when your extension supports multiple API versions.',
   isVisualComponent: false,
   category: 'Target APIs',
   subCategory: 'Platform APIs',
   type: 'API',
   definitions: [
     {
       title: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.title,
-      description: CUSTOMER_ACCOUNT_STANDARD_API_DEFINITION.description,
+      description:
+        'The `VersionApi` object provides the current API version string. Access the following properties on the `VersionApi` object to determine which API version your extension is running against and conditionally enable features.',
       type: 'Docs_Standard_VersionApi',
     },
   ],
diff --git a/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.jsx b/packages/ui-extensions/docs/surfaces/customer-account/reference/examples/apis/analytics-publish.example.jsx
@@ -18,7 +18,7 @@ function Extension() {
       .then((result) => {
         if (result) {
           console.log(
-            'succesfully published event, web pixels can now recieve this event',
+            'successfully published event, web pixels can now receive this event',
           );
         } else {
           console.log('failed to publish event');
diff --git a/packages/ui-extensions/src/shared.ts b/packages/ui-extensions/src/shared.ts
@@ -19,17 +19,17 @@ export type ApiVersion =
 /**
  * The capabilities an extension has access to.
  *
- * * [`api_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#api-access): the extension can access the Storefront API.
+ * * `api_access`: the extension can access the Storefront API.
  *
- * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls.
+ * * `network_access`: the extension can make external network calls.
  *
- * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
+ * * `block_progress`: the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
  *
- * * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect buyer consent for SMS marketing.
+ * * `collect_buyer_consent.sms_marketing`: the extension can collect buyer consent for SMS marketing.
  *
- * * [`collect_buyer_consent.customer_privacy`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can register buyer consent decisions that will be honored on Shopify-managed services.
+ * * `collect_buyer_consent.customer_privacy`: the extension can register buyer consent decisions that will be honored on Shopify-managed services.
  *
- * * [`iframe.sources`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#iframe): the extension can embed an external URL in an iframe.
+ * * `iframe.sources`: the extension can embed an external URL in an iframe.
  */
 
 export type Capability =
@@ -849,9 +849,12 @@ export type CountryCode =
   | 'ZW'
   | 'ZZ';
 
+/**
+ * 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. This is the internationally recognized standard for representing countries and territories.
+   * 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.
    */
@@ -902,7 +905,7 @@ export type LocalizedFieldKey =
   | 'TAX_EMAIL_IT';
 
 /**
- * Union of supported storefront API versions
+ * The supported Storefront API versions. Pass one of these values to `query()` to target a specific API version when querying the Storefront GraphQL API.
  */
 export type StorefrontApiVersion =
   | '2022-04'
@@ -921,22 +924,37 @@ export type StorefrontApiVersion =
   | '2025-07'
   | '2025-10';
 
+/**
+ * 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. This is the internationally recognized standard for representing countries and territories.
+   * 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;
 }
 
 /**
- * GraphQL error returned by the Shopify Storefront APIs.
+ * An error returned by the Storefront GraphQL API. Contains a human-readable `message` and an `extensions` object with the request ID and error code for debugging.
  */
 export interface GraphQLError {
+  /**
+   * A human-readable description of the error.
+   */
   message: string;
+  /**
+   * Additional error metadata including the request ID and error code.
+   */
   extensions: {
+    /**
+     * The unique identifier for the API request, useful for debugging with Shopify support.
+     */
     requestId: string;
+    /**
+     * A machine-readable error code identifying the type of error.
+     */
     code: string;
   };
 }
diff --git a/packages/ui-extensions/src/surfaces/customer-account/api/shared.ts b/packages/ui-extensions/src/surfaces/customer-account/api/shared.ts
diff --git a/packages/ui-extensions/src/surfaces/customer-account/api/standard-api/standard-api.ts b/packages/ui-extensions/src/surfaces/customer-account/api/standard-api/standard-api.ts
