@shopify/ui-extensions 2026.4.0-rc.3 → 2026.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2026.4.0-rc.3",
+  "version": "2026.4.1",
   "scripts": {
     "docs:admin": "node ./docs/surfaces/admin/build-docs.mjs",
     "docs:checkout": "bash ./docs/surfaces/checkout/build-docs.sh",
@@ -129,7 +129,7 @@
   ],
   "devDependencies": {
     "@remote-ui/async-subscription": "^2.1.16",
-    "@shopify/generate-docs": "https://registry.npmjs.org/@shopify/generate-docs/-/generate-docs-0.19.8.tgz",
+    "@shopify/generate-docs": "https://registry.npmjs.org/@shopify/generate-docs/-/generate-docs-1.1.0.tgz",
     "@quilted/react-testing": "^0.6.11",
     "typescript": "^4.9.0",
     "@faker-js/faker": "^8.4.1",

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,

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

@@ -5,8 +5,9 @@ import type {
 
 /**
  * A [metafield](/docs/apps/build/metafields) that stores discount function configuration data. Use metafields to persist settings that control how your discount function behaves, such as discount thresholds, eligibility rules, or custom discount logic parameters.
+ * @publicDocs
  */
-interface Metafield {
+export interface Metafield {
   /** A human-readable description explaining the metafield's purpose and how it affects discount 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. */
@@ -23,16 +24,19 @@ interface Metafield {
 
 /**
  * The discount class that determines where the discount applies in the purchase flow. Use this to understand what type of discount the merchant is configuring (product-level, order-level, or shipping).
+ * @publicDocs
  */
 export type DiscountClass = 'product' | 'order' | 'shipping';
 
 /**
  * The method used to apply a discount. Use `'automatic'` for discounts that apply automatically at checkout, or `'code'` for discounts that require a code entered by the customer.
+ * @publicDocs
  */
-type DiscountMethod = 'automatic' | 'code';
+export type DiscountMethod = 'automatic' | 'code';
 
 /**
  * The `data` object exposed to discount function settings extensions in the `admin.discount-details.function-settings.render` target. Use this to access the current discount configuration and populate your settings interface with existing values.
+ * @publicDocs
  */
 export interface DiscountFunctionSettingsData {
   /** The discount's unique global identifier (GID) in the [GraphQL Admin API](/docs/api/admin-graphql) format (for example, `gid://shopify/DiscountAutomaticApp/123`). Use this ID to associate settings with the correct discount or query discount data. */
@@ -43,6 +47,7 @@ export interface DiscountFunctionSettingsData {
 
 /**
  * The `DiscountsApi` object provides reactive access to discount configuration. Use the signals to read discount classes and method, and the update function to change which parts of the purchase (products, order, or shipping) the discount affects.
+ * @publicDocs
  */
 export interface DiscountsApi {
   /**

package/src/surfaces/admin/api/discount-function-settings/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 discount 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_purchase_amount'` or `'eligible_customer_tags'`). */
@@ -18,8 +19,9 @@ interface MetafieldUpdateChange {
 
 /**
  * A metafield removal operation. Use this to delete metafields that are no longer needed for your discount 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 discount 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 discount function 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/generated/generated.ts

@@ -0,0 +1,76 @@
+/** Response handle on `shopify.intents.response` with a typed `ok` payload. */
+export interface ShopifyGeneratedIntentResponse<Data = unknown> {
+  ok(data?: Data): Promise<void>;
+}
+
+export interface ShopifyGeneratedIntentVariant<
+  Request = unknown,
+  ResponseData = unknown,
+> {
+  request: Request;
+  response?: ShopifyGeneratedIntentResponse<ResponseData>;
+}
+
+// Replaces `value`/`subscribe` on a signal-like object while preserving other keys.
+type ReplaceSubscribableValue<Base, Value> = Base extends {
+  value: unknown;
+  subscribe: (callback: (value: infer _) => void) => () => void;
+}
+  ? Omit<Base, 'value' | 'subscribe'> & {
+      readonly value: Value;
+      subscribe: (callback: (value: Value) => void) => () => void;
+    }
+  : {
+      readonly value: Value;
+      subscribe: (callback: (value: Value) => void) => () => void;
+    };
+
+type MergeGeneratedIntentResponse<BaseIntents, Variants> =
+  Variants extends infer Variant
+    ? Variant extends {request: infer GeneratedRequest}
+      ? Omit<Variant, 'request' | 'response'> & {
+          request: BaseIntents extends {request: infer BaseRequest}
+            ? ReplaceSubscribableValue<BaseRequest, GeneratedRequest | null>
+            : {
+                readonly value: GeneratedRequest | null;
+                subscribe: (
+                  callback: (value: GeneratedRequest | null) => void,
+                ) => () => void;
+              };
+        } & (Variant extends {response: infer GeneratedResponse}
+            ? BaseIntents extends {response: infer BaseResponse}
+              ? {
+                  response: Omit<NonNullable<BaseResponse>, 'ok'> &
+                    NonNullable<GeneratedResponse>;
+                }
+              : {response: NonNullable<GeneratedResponse>}
+            : unknown)
+      : Variant
+    : never;
+
+/**
+ * Merges generated intent variants into a target's base `Api`. Narrows
+ * `intents.request` to the union and specialises `intents.response.ok`;
+ * introduces `intents` if the base has none.
+ */
+export type WithGeneratedIntents<Api, Variants> = Api extends {
+  intents?: infer BaseIntents;
+}
+  ? Omit<Api, 'intents'> & {
+      intents: Omit<NonNullable<BaseIntents>, 'request' | 'response'> &
+        MergeGeneratedIntentResponse<NonNullable<BaseIntents>, Variants>;
+    }
+  : Api & {intents: Variants};
+
+/**
+ * Merges generated tool registrations into a target's base `Api`. Replaces
+ * `tools.register` with the typed overloads in `Tools`; introduces `tools` if
+ * the base has none.
+ */
+export type WithGeneratedTools<Api, Tools> = Api extends {
+  tools?: infer BaseTools;
+}
+  ? Omit<Api, 'tools'> & {
+      tools: Omit<NonNullable<BaseTools>, 'register'> & Tools;
+    }
+  : Api & {tools: Tools};

package/src/surfaces/admin/api/intents/intent-render.ts

@@ -0,0 +1,26 @@
+import type {StandardRenderingExtensionApi} from '../standard/standard-rendering';
+import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
+import type {IntentResponseApi} from './intents';
+
+/**
+ * The intents API available to intent render extensions. Unlike other targets where `response` is optional, intent render extensions always run inside an intent workflow so `response` is guaranteed.
+ * @publicDocs
+ */
+export interface IntentRenderIntents {
+  /**
+   * Resolves the current intent from within the invoked extension. Use `ok()` to signal success, `error()` to report failure, or `closed()` to indicate the merchant cancelled.
+   */
+  response: IntentResponseApi;
+}
+
+/**
+ * The `IntentRenderApi` object provides methods for extensions that render in response to an app intent. Access the intent data to determine what action the merchant requested and use `intents.response` to resolve the intent when complete.
+ * @publicDocs
+ */
+export interface IntentRenderApi<ExtensionTarget extends AnyExtensionTarget>
+  extends StandardRenderingExtensionApi<ExtensionTarget> {
+  /**
+   * Provides methods for resolving the current intent. Always available for intent render extensions since they are always invoked inside an intent workflow.
+   */
+  intents: IntentRenderIntents;
+}

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

@@ -1,5 +1,6 @@
 /**
  * The response returned when a merchant closes or cancels the workflow without completing it. Check for this response to handle cancellation gracefully in your extension.
+ * @publicDocs
  */
 export interface ClosedIntentResponse {
   /** Indicates the workflow was closed without completion. When `'closed'`, the merchant exited the workflow before finishing. */
@@ -8,6 +9,7 @@ export interface ClosedIntentResponse {
 
 /**
  * The response returned when a merchant successfully completes the workflow. Use this to access the created or updated resource data.
+ * @publicDocs
  */
 export interface SuccessIntentResponse {
   /** Indicates successful completion. When `'ok'`, the merchant completed the workflow and the resource was created or updated. */
@@ -18,6 +20,7 @@ export interface SuccessIntentResponse {
 
 /**
  * The response returned when the workflow fails due to validation errors or other issues. Use this to display error messages and help merchants fix problems.
+ * @publicDocs
  */
 export interface ErrorIntentResponse {
   /** Indicates the workflow failed. When `'error'`, the workflow encountered validation errors or other issues that prevented completion. */
@@ -25,18 +28,24 @@ export interface ErrorIntentResponse {
   /** A general error message describing what went wrong. Use this to display feedback when specific field errors aren't available. */
   message?: string;
   /** Specific validation issues or field errors. Present when validation fails on particular fields, allowing you to show targeted error messages. */
-  issues?: {
-    /** The path to the field that has an error (for example, `['product', 'title']`). Use this to identify which field caused the validation failure. */
-    path?: string[];
-    /** A description of what's wrong with this field. Display this to help merchants understand how to fix the error. */
-    message?: string;
-    /** A machine-readable error code for this issue. Use this for programmatic error handling or logging. */
-    code?: string;
-  }[];
+  issues?: Issue[];
+}
+
+/**
+ * A structured issue describing a validation or workflow error.
+ */
+export interface Issue {
+  /** The path to the field that has an error (for example, `['product', 'title']`). Use this to identify which field caused the validation failure. */
+  path?: string[];
+  /** A description of what's wrong with this field. Display this to help merchants understand how to fix the error. */
+  message?: string;
+  /** A machine-readable error code for this issue. Use this for programmatic error handling or logging. */
+  code?: string;
 }
 
 /**
  * The result of an intent workflow. Check the `code` property to determine the outcome: `'ok'` for success, `'error'` for failure, or `'closed'` if the merchant cancelled.
+ * @publicDocs
  */
 export type IntentResponse =
   | SuccessIntentResponse
@@ -45,6 +54,7 @@ export type IntentResponse =
 
 /**
  * A handle for tracking an in-progress intent workflow.
+ * @publicDocs
  */
 export interface IntentActivity {
   /**
@@ -53,13 +63,35 @@ export interface IntentActivity {
   complete?: Promise<IntentResponse>;
 }
 
+/**
+ * The `IntentResponseApi` object provides methods for resolving the current intent from within an invoked extension. This API is only present when your extension is running inside an intent workflow.
+ */
+export interface IntentResponseApi {
+  /**
+   * Resolves the current intent successfully. Pass output data when your intent defines a response schema.
+   */
+  ok(data?: SuccessIntentResponse['data']): Promise<void>;
+
+  /**
+   * Resolves the current intent with an error. Use `issues` to provide field-specific validation details when available.
+   */
+  error(message: string, issues?: Issue[]): Promise<void>;
+
+  /**
+   * Resolves the current intent as closed without completing the workflow.
+   */
+  closed(): Promise<void>;
+}
+
 /**
  * The type of operation to perform: creating a new resource or editing an existing one.
+ * @publicDocs
  */
 export type IntentAction = 'create' | 'edit';
 
 /**
  * The types of Shopify resources that support intent-based creation and editing workflows.
+ * @publicDocs
  */
 export type IntentType =
   | 'shopify/Article'
@@ -79,6 +111,7 @@ export type IntentType =
 
 /**
  * Additional parameters for intent invocation when using the string query format. Use these options to provide resource IDs for editing or pass required context data for resource creation.
+ * @publicDocs
  */
 export interface IntentQueryOptions {
   /**
@@ -93,6 +126,7 @@ export interface IntentQueryOptions {
 
 /**
  * A structured intent specification defining what workflow to launch. Use this format when you prefer object syntax over string query format.
+ * @publicDocs
  */
 export interface IntentQuery extends IntentQueryOptions {
   /**
@@ -128,6 +162,7 @@ export interface IntentQuery extends IntentQueryOptions {
  * });
  * const response = await activity.complete;
  * ```
+ * @publicDocs
  */
 export interface IntentInvokeApi {
   (query: IntentQuery): Promise<IntentActivity>;
@@ -136,8 +171,14 @@ export interface IntentInvokeApi {
 
 /**
  * The `Intents` object provides methods for launching standardized Shopify workflows to create or edit resources. Intents enable your extension to trigger native admin interfaces for products, customers, discounts, and other resources, then receive the results when merchants complete the workflow.
+ * @publicDocs
  */
 export interface Intents {
+  /**
+   * Resolves the current intent from within an invoked extension. This property is only present when your extension is running inside an intent workflow.
+   */
+  response?: IntentResponseApi;
+
   /**
    * The URL that launched the current intent workflow, if your extension was opened through an intent. Use this to determine how your extension was invoked and access any parameters passed in the URL.
    */

package/src/surfaces/admin/api/order-routing-rule/data.ts

@@ -2,8 +2,9 @@ import type {SupportedDefinitionType} from './metafields';
 
 /**
  * A [metafield](/docs/apps/build/metafields) associated with an order routing rule. Use metafields to persist settings that control how your order routing function behaves, such as location preferences, routing criteria, or custom fulfillment rules.
+ * @publicDocs
  */
-interface Metafield {
+export interface Metafield {
   /** The unique global identifier (GID) for this metafield. Present for existing metafields, absent for new ones. Use this ID to reference the metafield in GraphQL operations. */
   id?: string | null;
   /** The unique key identifying this metafield within its namespace. This key determines how you access the metafield value (for example, `'preferred_location'` or `'routing_priority'`). */
@@ -18,8 +19,9 @@ interface Metafield {
 
 /**
  * An order routing rule configuration that determines how orders are routed to fulfillment locations. Use this to access the rule's current settings and populate your configuration interface.
+ * @publicDocs
  */
-interface OrderRoutingRule {
+export interface OrderRoutingRule {
   /** The display label for the order routing rule shown to merchants in the admin. Use this to identify the rule in lists and settings pages. */
   label: string;
   /** A description explaining the rule's purpose and how it routes orders. Use this to help merchants understand what the rule does. */
@@ -34,6 +36,7 @@ interface OrderRoutingRule {
 
 /**
  * The `data` object exposed to order routing rule extensions in the `admin.settings.order-routing-rule.render` target. Use this to access the current rule configuration and build your settings interface.
+ * @publicDocs
  */
 export interface Data {
   /** The order routing rule being configured by the merchant. Use this to access the rule's properties and populate your settings UI with existing configuration values. */