Choose a version:

Intents

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

Anchor to invokeinvoke

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' }`

Anchor to invoke invoke { (query: ): Promise<>; (intentURL: string, options?: ): Promise<>; } 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.
```
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 (e.g. `shopify/SubscriptionContract`).
```
string
```
value
The resource identifier for edit actions (e.g. `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
```
'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
```
'error'
```

issues

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

message
```
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
```
'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 (e.g. `gid://shopify/SubscriptionContract/123`).
```
string
```

Anchor to intentactionIntentAction

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

Anchor to intentqueryIntentQuery

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

Anchor to action action 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.
Anchor to type type string required: The resource type (e.g. shopify/SubscriptionContract).
Anchor to data 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' }
Anchor to value 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.

'create' | 'open' | string

Anchor to intentqueryoptionsIntentQueryOptions

Options for invoking intents when using the query string format.

Anchor to data 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' }
Anchor to value value string: The resource identifier for edit actions (e.g. gid://shopify/SubscriptionContract/123).

Anchor to intentactivityIntentActivity

Activity handle for tracking intent workflow progress.

Anchor to complete complete Promise<> 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.

SuccessIntentResponse | ErrorIntentResponse | ClosedIntentResponse

SuccessIntentResponse

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

code
```
'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

code
```
'error'
```

issues

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

message
```
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
```
'closed'
```

Anchor to intentresponseIntentResponse

Response object returned when the intent workflow completes.

SuccessIntentResponse | ErrorIntentResponse | ClosedIntentResponse

Anchor to ClosedIntentResponse

ClosedIntentResponse

Anchor to code code 'closed' required

Anchor to ErrorIntentResponse

ErrorIntentResponse

Anchor to code code 'error'
Anchor to issues issues { path?: string[]; message?: string; }[]
Anchor to message message string

Anchor to SuccessIntentResponse

SuccessIntentResponse

Anchor to code code 'ok' required
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.

SuccessIntentResponse

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

code
```
'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

code
```
'error'
```

issues

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

message
```
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
```
'closed'
```

Examples

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

Replace payment method with object syntax

Default

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

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

Was this page helpful?