---
title: Intents API
description: >-
  The Intents API provides a way to invoke existing customer account workflows
  for managing buyer information.
api_version: 2026-01
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/intents-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/platform-apis/intents-api.md
---

# Intents API

The Intents API provides a way to invoke existing customer account workflows for managing buyer information.

## invoke

The `invoke` API is a function that accepts either a string query or an options object describing the intent to invoke and returns a Promise that resolves to an activity handle for the workflow.

## Intent format

Intents are invoked using a string query format: `${action}:${type},${value}`

Where:

* `action` - The operation to perform (`create`, `edit` or `open`)
* `type` - The resource type (e.g., `shopify/SubscriptionContract`)
* `value` - The resource identifier

## Supported resources

### Subscription contract

| Action | Type | Value | Data |
| - | - | - | - |
| `open` | `shopify/SubscriptionContract` | `gid://shopify/SubscriptionContract/{id}` | `{ field: 'paymentMethod' }` |

* **invoke**

  **{ (query: IntentQuery): Promise\<IntentActivity>; (intentURL: string, options?: IntentQueryOptions): Promise\<IntentActivity>; }**

  **required**

  Invoke an intent using the object or URL syntax.

  Object format: `{action, type, value?, data?}`

  URL format: `action:type[,value][?params]`

### IntentQuery

Structured description of an intent to invoke. Use this object form when programmatically composing an intent at runtime. It pairs an action (verb) with a resource type and optional inputs.

* action

  Verb describing the operation to perform on the target resource. Common values include \`create\` and \`open\`. The set of allowed verbs is intent-specific; unknown verbs will fail validation.

  ```ts
  IntentAction
  ```

* data

  Optional input payload passed to the intent. Used to seed forms or supply parameters. The accepted shape is intent-specific. For example: - Replacing a payment method on a subscription contract requires { field: 'paymentMethod' }

  ```ts
  Record<string, unknown>
  ```

* type

  The resource type (e.g. \`shopify/SubscriptionContract\`).

  ```ts
  string
  ```

* value

  The resource identifier for edit actions (e.g. \`gid://shopify/SubscriptionContract/123\`).

  ```ts
  string
  ```

### IntentAction

Allowed actions that can be performed by an intent. Common actions include: - \`'create'\`: Initiate creation of a new resource. - \`'open'\`: Modify an existing resource.

```ts
'create' | 'open' | string
```

### IntentActivity

Activity handle for tracking intent workflow progress.

* complete

  A Promise that resolves when the intent workflow completes, returning the response.

  ```ts
  Promise<IntentResponse>
  ```

### IntentResponse

Result of an intent activity. Discriminated union representing all possible completion outcomes for an invoked intent.

```ts
SuccessIntentResponse | ErrorIntentResponse | ClosedIntentResponse
```

### SuccessIntentResponse

Successful intent completion. - \`code\` is always \`'ok'\` - \`data\` contains the output payload

* code

  ```ts
  'ok'
  ```

* data

  Validated output payload produced by the workflow. The shape is intent-specific. Consumers should narrow by \`code === 'ok'\` before accessing.

  ```ts
  Record<string, unknown>
  ```

### ErrorIntentResponse

Failed intent completion. - \`code\` is always \`'error'\` - \`message\` summarizes the failure - \`issues\` optionally provides structured details for validation or field-specific problems following the Standard Schema convention

* code

  ```ts
  'error'
  ```

* issues

  ```ts
  { path?: string[]; message?: string; }[]
  ```

* message

  ```ts
  string
  ```

### ClosedIntentResponse

User dismissed or closed the workflow without completing it. Distinct from \`error\`: no failure occurred, the activity was simply abandoned by the user.

* code

  ```ts
  'closed'
  ```

### IntentQueryOptions

Options for URL-based invocations. When invoking via URL syntax, \`action\` and \`type\` are parsed from the string. This companion type captures the remaining optional fields that can be provided alongside the URL.

* data

  Optional input payload passed to the intent. Used to seed forms or supply parameters. The accepted shape is intent-specific. For example: - Replacing a payment method on a subscription contract requires { field: 'paymentMethod' }

  ```ts
  Record<string, unknown>
  ```

* value

  The resource identifier for edit actions (e.g. \`gid://shopify/SubscriptionContract/123\`).

  ```ts
  string
  ```

## IntentAction

Supported actions that can be performed on resources.

* `create`: Opens a creation workflow for a new resource
* `open`: Opens a workflow for an existing resource (requires `value` parameter)

**`'create' | 'open' | string`**

## IntentQuery

Structured description of an intent to invoke. Use this object form when programmatically composing an intent at runtime.

* **action**

  **IntentAction**

  **required**

  Verb describing the operation to perform on the target resource.

  Common values include `create` and `open`. The set of allowed verbs is intent-specific; unknown verbs will fail validation.

* **type**

  **string**

  **required**

  The resource type (e.g. `shopify/SubscriptionContract`).

* **data**

  **Record\<string, unknown>**

  Optional input payload passed to the intent.

  Used to seed forms or supply parameters. The accepted shape is intent-specific. For example:

  * Replacing a payment method on a subscription contract requires { field: 'paymentMethod' }

* **value**

  **string**

  The resource identifier for edit actions (e.g. `gid://shopify/SubscriptionContract/123`).

### IntentAction

Allowed actions that can be performed by an intent. Common actions include: - \`'create'\`: Initiate creation of a new resource. - \`'open'\`: Modify an existing resource.

```ts
'create' | 'open' | string
```

## IntentQueryOptions

Options for invoking intents when using the query string format.

* **data**

  **Record\<string, unknown>**

  Optional input payload passed to the intent.

  Used to seed forms or supply parameters. The accepted shape is intent-specific. For example:

  * Replacing a payment method on a subscription contract requires { field: 'paymentMethod' }

* **value**

  **string**

  The resource identifier for edit actions (e.g. `gid://shopify/SubscriptionContract/123`).

## IntentActivity

Activity handle for tracking intent workflow progress.

* **complete**

  **Promise\<IntentResponse>**

  **required**

  A Promise that resolves when the intent workflow completes, returning the response.

### IntentResponse

Result of an intent activity. Discriminated union representing all possible completion outcomes for an invoked intent.

```ts
SuccessIntentResponse | ErrorIntentResponse | ClosedIntentResponse
```

### SuccessIntentResponse

Successful intent completion. - \`code\` is always \`'ok'\` - \`data\` contains the output payload

* code

  ```ts
  'ok'
  ```

* data

  Validated output payload produced by the workflow. The shape is intent-specific. Consumers should narrow by \`code === 'ok'\` before accessing.

  ```ts
  Record<string, unknown>
  ```

### ErrorIntentResponse

Failed intent completion. - \`code\` is always \`'error'\` - \`message\` summarizes the failure - \`issues\` optionally provides structured details for validation or field-specific problems following the Standard Schema convention

* code

  ```ts
  'error'
  ```

* issues

  ```ts
  { path?: string[]; message?: string; }[]
  ```

* message

  ```ts
  string
  ```

### ClosedIntentResponse

User dismissed or closed the workflow without completing it. Distinct from \`error\`: no failure occurred, the activity was simply abandoned by the user.

* code

  ```ts
  'closed'
  ```

## IntentResponse

Response object returned when the intent workflow completes.

**`SuccessIntentResponse | ErrorIntentResponse | ClosedIntentResponse`**

### ClosedIntentResponse

* **code**

  **'closed'**

  **required**

### ErrorIntentResponse

* **code**

  **'error'**

* **issues**

  **{ path?: string\[]; message?: string; }\[]**

* **message**

  **string**

### SuccessIntentResponse

* **code**

  **'ok'**

  **required**

* **data**

  **Record\<string, unknown>**

  **required**

  Validated output payload produced by the workflow.

  The shape is intent-specific. Consumers should narrow by `code === 'ok'` before accessing.

### SuccessIntentResponse

Successful intent completion. - \`code\` is always \`'ok'\` - \`data\` contains the output payload

* code

  ```ts
  'ok'
  ```

* data

  Validated output payload produced by the workflow. The shape is intent-specific. Consumers should narrow by \`code === 'ok'\` before accessing.

  ```ts
  Record<string, unknown>
  ```

### ErrorIntentResponse

Failed intent completion. - \`code\` is always \`'error'\` - \`message\` summarizes the failure - \`issues\` optionally provides structured details for validation or field-specific problems following the Standard Schema convention

* code

  ```ts
  'error'
  ```

* issues

  ```ts
  { path?: string[]; message?: string; }[]
  ```

* message

  ```ts
  string
  ```

### ClosedIntentResponse

User dismissed or closed the workflow without completing it. Distinct from \`error\`: no failure occurred, the activity was simply abandoned by the user.

* code

  ```ts
  'closed'
  ```

Examples

### Examples

* #### Replace payment method with object syntax

  ##### Default

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    async function handleReplacePaymentMethod() {
      const activity = await shopify.intents.invoke(
        {
          action: 'open',
          type: 'shopify/SubscriptionContract',
          value:
            'gid://shopify/SubscriptionContract/123',
          data: {field: 'paymentMethod'},
        },
      );

      const response = await activity.complete;

      if (response.code === 'ok') {
        console.log(
          'Intent completed successfully',
          response.data,
        );
      }
    }

    return (
      <s-button
        onClick={handleReplacePaymentMethod}
      >
        Edit subscription payment method
      </s-button>
    );
  }
  ```

* #### Replace payment method with string syntax

  ##### Description

  Replace the payment method on an active subscription contract. Opens a modal with vaulted cards.

  ##### Default

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    async function handleReplacePaymentMethod() {
      const activity = await shopify.intents.invoke(
        'open:shopify/SubscriptionContract,gid://shopify/SubscriptionContract/123?field=paymentMethod',
      );

      const response = await activity.complete;

      if (response.code === 'ok') {
        console.log(
          'Intent completed successfully',
          response.data,
        );
      }
    }

    return (
      <s-button
        onClick={handleReplacePaymentMethod}
      >
        Edit subscription payment method
      </s-button>
    );
  }
  ```