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

package/src/docs/shared/components/Popover.ts

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Popover',
   description:
     'Popovers are used to display content in an overlay that can be triggered by a button.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Overlays',
   related: [],
 };

package/src/docs/shared/components/PressButton.ts

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Press button',
   description:
     'Allows users to toggle between active/inactive states. Use to represent a persistent on/off or selected/unselected status.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Actions',
   related: [],
 };

package/src/docs/shared/components/ProductThumbnail.ts

@@ -3,7 +3,7 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Product thumbnail',
   description: 'Use ProductThumbnail to display a product thumbnail',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Media and visuals',
   related: [],
 };

package/src/docs/shared/components/Progress.ts

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Progress',
   description:
     'Displays an indicator showing the completion status of a task. Use to visually communicate progress in either determinate (known percentage) or indeterminate (unknown duration) states.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Feedback and status indicators',
   related: [],
 };

package/src/docs/shared/components/QRCode.ts

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'QR code',
   description:
     'Displays a scannable QR code representing data such as URLs or text. Use to let users quickly access information by scanning with a smartphone or other device.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Media and visuals',
   related: [],
 };

package/src/docs/shared/components/QueryContainer.ts

@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     "The query container component establishes a container query context for responsive design. Use query container to define an element as a containment context, enabling child components or styles to adapt based on the container's size rather than viewport width." +
     '\n\nQuery containers support modern responsive patterns where components respond to their container dimensions, creating more flexible and reusable layouts.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/ScrollBox.ts

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Scroll box',
   description:
     'Provides a scrollable container for long content that exceeds the available space. Use to display lists, order summaries, or other lengthy content while maintaining a constrained layout.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/SearchField.ts

@@ -3,8 +3,8 @@ import type {SharedReferenceEntityTemplateSchema} from '../docs-type';
 const data: SharedReferenceEntityTemplateSchema = {
   name: 'Search field',
   description:
-    'The search field component captures search terms for filtering and search functionality. Use it to enable inline search within specific sections or lists, like filtering products or searching customers. For general text input, use [text field](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/text-field).',
-  category: 'Polaris web components',
+    'The search field component captures search terms for filtering and search functionality. Use it to enable inline search within specific sections or lists, like filtering products or searching customers. For general text input, use [text field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/text-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Section.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Section',
   description:
     'The section component groups related content into clearly-defined thematic areas with consistent styling and structure. Use section to organize page content into logical blocks, each with its own heading and visual container.' +
-    '\n\nSections automatically adapt their styling based on nesting depth and adjust heading levels to maintain meaningful, accessible page hierarchies. For simple visual separation without headings, use [divider](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/layout-and-structure/divider).',
-  category: 'Polaris web components',
+    '\n\nSections automatically adapt their styling based on nesting depth and adjust heading levels to maintain meaningful, accessible page hierarchies. For simple visual separation without headings, use [divider](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/divider).',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/Select.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Select',
   description:
     'The select component allows users to choose one option from a dropdown menu. Use select when presenting four or more choices to keep interfaces uncluttered and scannable, or when space is limited.' +
-    '\n\nSelect components support option grouping, placeholder text, help text, and validation states to create clear selection interfaces. For more visual selection layouts with radio buttons or checkboxes, use [choice list](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/choice-list).',
-  category: 'Polaris web components',
+    '\n\nSelect components support option grouping, placeholder text, help text, and validation states to create clear selection interfaces. For more visual selection layouts with radio buttons or checkboxes, use [choice list](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/choice-list).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Sheet.ts

@@ -6,7 +6,7 @@ const data: SharedReferenceEntityTemplateSchema = {
 The Sheet component displays essential information for customers at the bottom of the screen, appearing above other elements. Use it sparingly to avoid distracting customers during checkout. This component requires access to [Customer Privacy API](/docs/api/checkout-ui-extensions/latest/configuration#collect-buyer-consent) to be rendered.
 
 The library automatically applies the [WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) to both the activator and the sheet content.`,
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Overlays',
   related: [],
 };

package/src/docs/shared/components/SkeletonParagraph.ts

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Skeleton paragraph',
   description:
     'Displays a placeholder representation of text content while it loads. Use to improve perceived performance by showing users where text will appear.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

package/src/docs/shared/components/Spinner.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Spinner',
   description:
     'The spinner component displays an animated indicator showing users that content or actions are loading. Use spinner to communicate ongoing processes like fetching data, processing requests, or waiting for operations to complete.' +
-    '\n\nSpinners support multiple sizes and should be used for page or section loading states. For button loading states, use the `loading` property on the [button](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/actions/button) component instead.',
-  category: 'Polaris web components',
+    '\n\nSpinners support multiple sizes and should be used for page or section loading states. For button loading states, use the `loading` property on the [button](/docs/api/{API_NAME}/{API_VERSION}/web-components/actions/button) component instead.',
+  category: 'Web components',
   subCategory: 'Feedback and status indicators',
   related: [],
 };

package/src/docs/shared/components/Stack.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Stack',
   description:
     'The stack component organizes elements horizontally or vertically along the block or inline axis. Use stack to structure layouts, group related components, control spacing between elements, or create flexible arrangements that adapt to content.' +
-    '\n\nStacks support gap spacing, alignment, wrapping, and distribution properties to create consistent, responsive layouts without custom CSS. For complex multi-column layouts with precise grid positioning, use [grid](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/layout-and-structure/grid).',
-  category: 'Polaris web components',
+    '\n\nStacks support gap spacing, alignment, wrapping, and distribution properties to create consistent, responsive layouts without custom CSS. For complex multi-column layouts with precise grid positioning, use [grid](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/grid).',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/Summary.ts

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Summary',
   description:
     'Provides a clickable label for collapsible Details content. Use to create clear, accessible disclosure controls that show or hide additional information.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

package/src/docs/shared/components/Switch.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Switch',
   description:
     'The switch component provides a clear way for users to toggle options or settings on and off. Use switch for binary controls that take effect immediately, like enabling features, activating settings, or controlling visibility.' +
-    "\n\nSwitches provide instant visual feedback and are ideal for settings that don't require a save action to apply changes. For selections that require explicit submission, use [checkbox](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/checkbox) instead.",
-  category: 'Polaris web components',
+    "\n\nSwitches provide instant visual feedback and are ideal for settings that don't require a save action to apply changes. For selections that require explicit submission, use [checkbox](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/checkbox) instead.",
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Table.ts

@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'The table component displays data clearly in rows and columns, helping users view, analyze, and compare structured information. Use table to present datasets, product lists, order details, or any tabular content that benefits from organized rows and columns.' +
     '\n\nTables automatically adapt to screen size, rendering as lists on small screens and tables on larger ones for optimal readability across devices.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Layout and structure',
   related: [],
 };

package/src/docs/shared/components/TableBody.ts

@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'The table body component represents the main content area of a table, containing the data rows. Use table body as a child of table to structure your table data, with each table row within the body representing a single record or entry.' +
     '\n\nTable body must contain table row components, which in turn contain table cell components for the actual data values.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/TableCell.ts

@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'The table cell component represents a single data cell within a table row. Use table cell as a child of table row to display individual data values, with each cell corresponding to a column in the table.' +
     '\n\nTable cell automatically inherits styling and alignment from its parent table structure and supports text content or other inline components.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/TableHeader.ts

@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'The table header component represents a single column header within a table header row. Use table header as a child of table header row to define column headings and optionally enable column sorting.' +
     '\n\nTable header provides semantic meaning for screen readers and can include sorting controls when configured. Each header corresponds to a column in the table body.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/TableHeaderRow.ts

@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'The table header row component represents the header row of a table, containing column headings. Use table header row as the first child of table (before table body) to define the table structure and provide column labels.' +
     '\n\nTable header row must contain table header components for each column. These headers provide context for the data columns and can support sorting functionality.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/TableRow.ts

@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'The table row component represents a single row of data within a table body. Use table row as a child of table body to structure individual records or entries in the table.' +
     '\n\nTable row must contain table cell components, with each cell representing a data value for the corresponding column. The number of cells should match the number of headers in the table.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Structure',
   related: [],
 };

package/src/docs/shared/components/Text.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Text',
   description:
     'The text component displays inline text with specific visual styles or tones. Use text to emphasize or differentiate words or phrases within paragraphs or other block-level components, applying weight, color, or semantic styling.' +
-    '\n\nText supports multiple visual variants, alignment options, and line clamping for flexible inline typography control. For block-level text content, use [paragraph](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/typography-and-content/paragraph).',
-  category: 'Polaris web components',
+    '\n\nText supports multiple visual variants, alignment options, and line clamping for flexible inline typography control. For block-level text content, use [paragraph](/docs/api/{API_NAME}/{API_VERSION}/web-components/typography-and-content/paragraph).',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

package/src/docs/shared/components/TextArea.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Text area',
   description:
     'The text area component captures multi-line text input. Use it to collect descriptions, notes, comments, or other extended text content.' +
-    '\n\nThe component supports configurable height, character limits, and validation. For single-line text input, use [text field](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/text-field).',
-  category: 'Polaris web components',
+    '\n\nThe component supports configurable height, character limits, and validation. For single-line text input, use [text field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/text-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/TextField.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Text field',
   description:
     'The text field component captures single-line text input. Use it to collect short, free-form information like names, titles, or identifiers.' +
-    '\n\nThe component supports various input configurations including placeholders, character limits, and validation. For multi-line text entry, use [text area](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/text-area). For specialized input types, use [email field](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/email-field), [URL field](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/url-field), [password field](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/password-field), or [search field](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/search-field).',
-  category: 'Polaris web components',
+    '\n\nThe component supports various input configurations including placeholders, character limits, and validation. For multi-line text entry, use [text area](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/text-area). For specialized input types, use [email field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/email-field), [URL field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/url-field), [password field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/password-field), or [search field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/search-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/Thumbnail.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Thumbnail',
   description:
     'The thumbnail component displays small preview images representing content, products, or media items. Use thumbnail to provide visual identification in lists, tables, or cards where space is constrained and quick recognition is important.' +
-    '\n\nThumbnails support multiple sizes, alt text for accessibility, and fallback states for missing images. For full-size images, use [image](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/media-and-visuals/image). For user profile images, use [avatar](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/media-and-visuals/avatar).',
-  category: 'Polaris web components',
+    '\n\nThumbnails support multiple sizes, alt text for accessibility, and fallback states for missing images. For full-size images, use [image](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/image). For user profile images, use [avatar](/docs/api/{API_NAME}/{API_VERSION}/web-components/media-and-visuals/avatar).',
+  category: 'Web components',
   subCategory: 'Media and visuals',
   related: [],
 };

package/src/docs/shared/components/Time.ts

@@ -4,7 +4,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Time',
   description:
     'Represents a specific point or duration in time. Use to display dates, times, or durations clearly and consistently. May include a machine-readable `datetime` attribute for improved accessibility and functionality.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

package/src/docs/shared/components/Tooltip.ts

@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
   description:
     'The tooltip component displays helpful information in a small overlay when users hover over or focus on an element. Use tooltip to provide additional context, explain functionality, or clarify terms without cluttering the interface with permanent text.' +
     '\n\nTooltips support keyboard accessibility, positioning options, and activation on both hover and focus for inclusive interaction patterns.',
-  category: 'Polaris web components',
+  category: 'Web components',
   subCategory: 'Overlays',
   related: [],
 };

package/src/docs/shared/components/URLField.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'URL field',
   description:
     'The URL field component collects URLs from users with built-in formatting and validation. Use URL field for website addresses, link destinations, or any URL input to provide URL-specific keyboard layouts and automatic validation.' +
-    '\n\nURL fields support protocol prefixing, validation, and help text to guide users toward entering properly formatted web addresses. For general text input, use [text field](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/forms/text-field).',
-  category: 'Polaris web components',
+    '\n\nURL fields support protocol prefixing, validation, and help text to guide users toward entering properly formatted web addresses. For general text input, use [text field](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/text-field).',
+  category: 'Web components',
   subCategory: 'Forms',
   related: [],
 };

package/src/docs/shared/components/UnorderedList.ts

@@ -4,8 +4,8 @@ const data: SharedReferenceEntityTemplateSchema = {
   name: 'Unordered list',
   description:
     "The unordered list component displays a bulleted list of related items where sequence isn't critical. Use unordered list to present collections of features, options, requirements, or any group of items where order doesn't affect meaning." +
-    '\n\nUnordered lists automatically add bullet points and support nested lists for hierarchical content organization. For sequential items where order is important, use [ordered list](/docs/api/{API_NAME}/{API_VERSION}/polaris-web-components/layout-and-structure/ordered-list).',
-  category: 'Polaris web components',
+    '\n\nUnordered lists automatically add bullet points and support nested lists for hierarchical content organization. For sequential items where order is important, use [ordered list](/docs/api/{API_NAME}/{API_VERSION}/web-components/layout-and-structure/ordered-list).',
+  category: 'Web components',
   subCategory: 'Typography and content',
   related: [],
 };

package/src/shared.ts

@@ -20,17 +20,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 =
@@ -850,10 +850,14 @@ export type CountryCode =
   | 'ZW'
   | 'ZZ';
 
+/**
+ * A buyer's country, identified by its ISO country code.
+ */
 export interface Country {
   /**
-   * The ISO-3166-1 code for this country.
-   * @see https://www.iso.org/iso-3166-country-codes.html
+   * 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;
 }
@@ -902,7 +906,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,21 +925,37 @@ export type StorefrontApiVersion =
   | '2025-07'
   | '2025-10';
 
+/**
+ * A buyer's country, identified by its ISO country code.
+ */
 export interface Country {
   /**
-   * The ISO-3166-1 code for this country.
-   * @see https://www.iso.org/iso-3166-country-codes.html
+   * 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;
   };
 }

package/src/surfaces/admin/api/action/action.ts

@@ -4,6 +4,7 @@ import type {Data} from '../shared';
 
 /**
  * The `ActionExtensionApi` object provides methods for action extensions that render in modal overlays. Access the following properties on the `ActionExtensionApi` object to interact with the current context, control the modal, and display picker dialogs.
+ * @publicDocs
  */
 export interface ActionExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardRenderingExtensionApi<ExtensionTarget> {

package/src/surfaces/admin/api/block/block.ts

@@ -4,6 +4,7 @@ import type {Data} from '../shared';
 
 /**
  * The `Navigation` object provides methods for navigating between extensions and admin pages.
+ * @publicDocs
  */
 export interface Navigation {
   /**
@@ -17,6 +18,7 @@ export interface Navigation {
 
 /**
  * The `BlockExtensionApi` object provides methods for block extensions that render inline content on admin pages. Access the following properties on the `BlockExtensionApi` object to interact with the current context, navigate to other extensions, and display picker dialogs.
+ * @publicDocs
  */
 export interface BlockExtensionApi<ExtensionTarget extends AnyExtensionTarget>
   extends StandardRenderingExtensionApi<ExtensionTarget> {

package/src/surfaces/admin/api/checkout-rules/launch-options.ts

@@ -1,7 +1,8 @@
 /**
  * A [metafield](/docs/apps/build/metafields) that stores validation function configuration data. Use metafields to persist settings that control how your validation function behaves, such as minimum quantities, restricted shipping zones, or custom validation rules.
+ * @publicDocs
  */
-interface Metafield {
+export interface Metafield {
   /** A human-readable description explaining the metafield's purpose and how it affects validation behavior. Use this to document your settings for other developers. */
   description?: string;
   /** The unique global identifier (GID) for this metafield. Use this ID to reference the metafield in GraphQL queries or updates. */
@@ -18,8 +19,9 @@ interface Metafield {
 
 /**
  * A validation configuration that exists and is active in the shop. Use this object to access the validation's current settings and metafields when merchants edit an existing validation.
+ * @publicDocs
  */
-interface Validation {
+export interface Validation {
   /** The validation's unique global identifier (GID). Use this ID to reference the validation in GraphQL operations or when saving updated settings. */
   id: string;
   /** An array of [metafields](/docs/apps/build/metafields) that store the validation's configuration values. Use these metafields to populate your settings UI with the current validation configuration. */
@@ -28,14 +30,16 @@ interface Validation {
 
 /**
  * A [Shopify Function](/docs/apps/build/functions) that implements cart and checkout validation logic. This identifies which function the settings interface is configuring.
+ * @publicDocs
  */
-interface ShopifyFunction {
+export interface ShopifyFunction {
   /** The [Shopify Function's](/docs/apps/build/functions) unique global identifier (GID). Use this ID to associate settings changes with the correct function. */
   id: string;
 }
 
 /**
  * The `data` object exposed to validation settings extensions in the `admin.settings.validation.render` target. Use this to access the current validation configuration and populate your settings interface with existing values.
+ * @publicDocs
  */
 export interface ValidationData {
   /** The validation configuration containing the validation ID and metafields. Present when editing an existing validation, absent when creating a new validation. Use the presence of this value to determine if you're in create or edit mode. */

package/src/surfaces/admin/api/checkout-rules/metafields.ts

@@ -2,8 +2,9 @@ import {SupportedDefinitionType} from '../shared';
 
 /**
  * A metafield update or creation operation. Use this to set or modify metafield values that store validation function configuration data.
+ * @publicDocs
  */
-interface MetafieldUpdateChange {
+export interface MetafieldUpdateChange {
   /** Identifies this as an update operation. Always set to `'updateMetafield'` for updates. */
   type: 'updateMetafield';
   /** The unique key identifying the metafield within its namespace. Use descriptive keys that indicate the setting's purpose (for example, `'min_quantity'` or `'shipping_restriction'`). */
@@ -18,8 +19,9 @@ interface MetafieldUpdateChange {
 
 /**
  * A metafield removal operation. Use this to delete metafields that are no longer needed for your validation configuration.
+ * @publicDocs
  */
-interface MetafieldRemoveChange {
+export interface MetafieldRemoveChange {
   /** Identifies this as a removal operation. Always set to `'removeMetafield'` for deletions. */
   type: 'removeMetafield';
   /** The unique key of the metafield to remove. Must match the key used when the metafield was created. */
@@ -30,13 +32,15 @@ interface MetafieldRemoveChange {
 
 /**
  * A metafield change operation that can either update or remove a metafield. Pass this to `applyMetafieldChange` to modify validation settings stored in metafields.
+ * @publicDocs
  */
-type MetafieldChange = MetafieldUpdateChange | MetafieldRemoveChange;
+export type MetafieldChange = MetafieldUpdateChange | MetafieldRemoveChange;
 
 /**
  * A failed metafield change operation result. Use the error message to understand what went wrong and fix the issue, such as validation errors, permission problems, or invalid metafield types.
+ * @publicDocs
  */
-interface MetafieldChangeResultError {
+export interface MetafieldChangeResultError {
   /** Indicates the operation failed. Check this value to determine if you need to handle an error. */
   type: 'error';
   /** A human-readable error message explaining why the operation failed. Use this to debug issues or display feedback to merchants. */
@@ -45,21 +49,24 @@ interface MetafieldChangeResultError {
 
 /**
  * A successful metafield change operation result. The metafield was updated or removed as requested and the changes are now saved.
+ * @publicDocs
  */
-interface MetafieldChangeSuccess {
+export interface MetafieldChangeSuccess {
   /** Indicates the operation succeeded. When this value is `'success'`, the metafield change was applied successfully. */
   type: 'success';
 }
 
 /**
  * The result returned after attempting to change a metafield. Check the `type` property to determine if the operation succeeded (`'success'`) or failed (`'error'`), then handle the result appropriately in your extension.
+ * @publicDocs
  */
-type MetafieldChangeResult =
+export type MetafieldChangeResult =
   | MetafieldChangeSuccess
   | MetafieldChangeResultError;
 
 /**
  * A function that applies metafield changes to validation settings. Call this function with an update or removal operation, then await the Promise to receive a result indicating success or failure. Use the result to provide feedback or handle errors in your settings interface.
+ * @publicDocs
  */
 export type ApplyMetafieldChange = (
   change: MetafieldChange,

package/src/surfaces/admin/api/checkout-rules/validation-settings.ts

@@ -6,6 +6,7 @@ import {ValidationData} from './launch-options';
 
 /**
  * The `ValidationSettingsApi` object provides methods for configuring cart and checkout validation functions. Access the following properties on the `ValidationSettingsApi` object to manage validation settings and metafields.
+ * @publicDocs
  */
 export interface ValidationSettingsApi<
   ExtensionTarget extends AnyExtensionTarget,

package/src/surfaces/admin/api/customer-segment-template/customer-segment-template.ts

@@ -4,6 +4,7 @@ import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-target
 
 /**
  * The `CustomerSegmentTemplateApi` object provides methods for creating customer segment templates. Access the following properties on the `CustomerSegmentTemplateApi` object to build templates with translated content.
+ * @publicDocs
  */
 export interface CustomerSegmentTemplateApi<
   ExtensionTarget extends AnyExtensionTarget,
@@ -16,11 +17,13 @@ export interface CustomerSegmentTemplateApi<
 
 /**
  * Standard customer metafields that can be referenced as template dependencies.
+ * @publicDocs
  */
 export type CustomerStandardMetafieldDependency = 'facts.birth_date';
 
 /**
  * Defines a customer segment template that merchants can use to create targeted customer groups.
+ * @publicDocs
  */
 export interface CustomerSegmentTemplate {
   /**

package/src/surfaces/admin/api/discount-function-settings/discount-function-settings.ts

@@ -6,6 +6,7 @@ import {DiscountFunctionSettingsData, DiscountsApi} from './launch-options';
 
 /**
  * The `DiscountFunctionSettingsApi` object provides methods for configuring discount functions. Access the following properties on the `DiscountFunctionSettingsApi` object to manage function settings and metafields.
+ * @publicDocs
  */
 export interface DiscountFunctionSettingsApi<
   ExtensionTarget extends AnyExtensionTarget,