Choose a version:

Intents API

The Intents API lets you invoke built-in customer account workflows like updating payment methods on subscription contracts. Use this API to trigger standard Shopify actions from your extension without rebuilding complex flows from scratch.

Intents can be invoked using either a structured object or a string query format. Both approaches return an activity handle that you can await to track the workflow's completion.

Note

The Intents API currently supports a single resource: opening the payment method replacement flow for subscription contracts. See Supported resources for details.

Anchor to Use casesUse cases

Update subscription payment methods: Open the built-in payment method replacement flow for a subscription contract, letting customers swap their vaulted card without leaving the extension.
Trigger standard account workflows: Invoke Shopify-managed experiences for common tasks instead of building custom UI for each one.
Track workflow outcomes: Await the result of shopify.intents.invoke() to detect when a workflow completes and update your extension's UI accordingly.

Support

Targets (24)

Supported targets

Anchor to invoke methodinvoke method

The invoke method opens a Shopify-managed workflow for managing resources. The method returns a promise that resolves to an activity handle you can await to get the workflow result.

The method accepts either:

String query: ${action}:${type},${value} with optional second parameter (IntentQueryOptions)
Object: Properties for action, type, value, and data

IntentQueryOptions parameters

Optional parameters for the invoke method when using the string query format:

value (string): The resource identifier (for example, 'gid://shopify/SubscriptionContract/123'). Required when opening existing resources.
data ({ [key: string]: unknown }): Additional context required by specific resource types. For example, subscription contracts require { field: 'paymentMethod' }.

Anchor to invoke invoke { (query: ): Promise<>; (intentURL: string, options?: ): Promise<>; } required: Triggers a built-in Shopify workflow by passing a structured intent object. Specify an action (such as 'open'), a resource type, and an optional value identifying the resource. Returns a promise that resolves to an IntentActivity you can use to track completion.

Triggers a built-in Shopify workflow using a URL string in the format action:type[,value][?params]. Use this overload when composing intents from dynamic strings rather than structured objects.

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.
```
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' }`.
```
Record<string, unknown>
```
type
The resource type (such as `shopify/SubscriptionContract`).
```
string
```
value
The resource identifier for edit actions (such as `gid://shopify/SubscriptionContract/123`).
```
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.

'create' | 'open' | string

IntentActivity

Activity handle for tracking intent workflow progress.

complete
A Promise that resolves when the intent workflow completes, returning the response.
```
Promise<IntentResponse>
```

IntentResponse

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

SuccessIntentResponse | ErrorIntentResponse | ClosedIntentResponse

SuccessIntentResponse

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

code
Always `'ok'` for a successful response.
```
'ok'
```
data
Validated output payload produced by the workflow. The shape is intent-specific. Consumers should narrow by `code === 'ok'` before accessing.
```
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
Set to `'error'` when present. This property is optional.
```
'error'
```
issues
Structured details for validation or field-specific problems, following the Standard Schema convention.
```
{ path?: string[]; message?: string; }[]
```
message
A human-readable summary of the failure.
```
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
Always `'closed'` when the user dismissed the workflow without completing it.
```
'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' }`.
```
Record<string, unknown>
```
value
The resource identifier for edit actions (such as `gid://shopify/SubscriptionContract/123`).
```
string
```

Anchor to Supported resourcesSupported resources

The following table shows which resource types you can open and what values you need to pass for value and data.

Anchor to Subscription contractSubscription contract

Subscription contracts represent recurring billing agreements. Use this to open the payment method replacement flow for an active subscription.

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

Anchor to IntentResponseIntentResponse

The result returned when an intent workflow completes. Check the code property to determine the outcome:

'ok': The customer completed the workflow successfully.
'error': The workflow failed due to validation or other errors.
'closed': The customer cancelled without completing.

SuccessIntentResponse | ErrorIntentResponse | ClosedIntentResponse

Anchor to ClosedIntentResponse

ClosedIntentResponse

Anchor to code code 'closed' required: Always 'closed' when the user dismissed the workflow without completing it.

Anchor to ErrorIntentResponse

ErrorIntentResponse

Anchor to code code 'error': Set to 'error' when present. This property is optional.
Anchor to issues issues { path?: string[]; message?: string; }[]: Structured details for validation or field-specific problems, following the Standard Schema convention.
Anchor to message message string: A human-readable summary of the failure.

Anchor to SuccessIntentResponse

SuccessIntentResponse

Anchor to code code 'ok' required: Always 'ok' for a successful response.
Anchor to data 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.

Examples

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>

);

}

Examples

Description

Open the built-in payment method replacement flow for a subscription contract. This example invokes the intent using the structured object format and logs the result when the workflow completes.

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>
  );
}

Description

Handle different outcomes after an intent workflow completes, including success, cancellation, and errors. This example awaits `activity.complete`, checks the response code, and updates the UI with a toast notification based on the result.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';

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

function Extension() {
  const [status, setStatus] = useState('idle');

  async function handleUpdatePayment() {
    setStatus('loading');

    try {
      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') {
        setStatus('success');
        shopify.toast.show(
          'Payment method updated',
        );
      } else if (response.code === 'closed') {
        setStatus('idle');
        shopify.toast.show(
          'Payment update was cancelled',
        );
      } else {
        setStatus('error');
        shopify.toast.show(
          'Something went wrong. Please try again.',
          {isError: true},
        );
      }
    } catch (error) {
      setStatus('error');
      shopify.toast.show(
        'Something went wrong. Please try again.',
        {isError: true},
      );
    }
  }

  return (
    <s-stack direction="block" gap="base">
      <s-button
        onClick={handleUpdatePayment}
        disabled={status === 'loading'}
      >
        {status === 'loading'
          ? 'Opening...'
          : 'Update payment method'}
      </s-button>
      {status === 'success' && (
        <s-text tone="success">
          Payment method updated successfully.
        </s-text>
      )}
    </s-stack>
  );
}

Anchor to Best practicesBest practices

Prefer object syntax for dynamic intents: When building the intent parameters programmatically from variables, use the structured object format. It's easier to read and less error-prone than string interpolation.
Use string syntax for static intents: When the action, type, and value are known at write time, the compact string format keeps your code concise.
Always await the activity handle: Call await activity.complete to detect when the workflow finishes. This lets you refresh data or update UI in response to the customer's action.
Check the response code before acting on results: Verify that response.code is 'ok' before using response.data. The workflow may be cancelled or fail, and your extension should handle those cases gracefully.

Anchor to LimitationsLimitations

Intent workflows pause your extension until completion. You can't run other operations while an intent is open.
The workflow UI can't be customized. Field order, labels, and validation messages are controlled by Shopify and can't be modified.

Was this page helpful?