---
title: Intents
description: >-
  The Intents API provides a way to invoke existing admin workflows for
  creating, editing, and managing Shopify resources.
api_name: app-bridge-library
source_url:
  html: 'https://shopify.dev/docs/api/app-bridge-library/apis/intents'
  md: 'https://shopify.dev/docs/api/app-bridge-library/apis/intents.md'
---

# Intents

The Intents API provides a way to invoke existing admin workflows for creating, editing, and managing Shopify resources.

## 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` or `edit`)
* `type` - The resource type (e.g., `shopify/Product`)
* `value` - The resource identifier (only for edit actions)

## Supported Resources

### Article

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Article` | — | — |
| `edit` | `shopify/Article` | `gid://shopify/Article/{id}` | — |

### Catalog

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Catalog` | — | — |
| `edit` | `shopify/Catalog` | `gid://shopify/Catalog/{id}` | — |

### Collection

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Collection` | — | — |
| `edit` | `shopify/Collection` | `gid://shopify/Collection/{id}` | — |

### Customer

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Customer` | — | — |
| `edit` | `shopify/Customer` | `gid://shopify/Customer/{id}` | — |

### Discount

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Discount` | — | `{ type: 'amount-off-product' \| 'amount-off-order' \| 'buy-x-get-y' \| 'free-shipping' }` |
| `edit` | `shopify/Discount` | `gid://shopify/Discount/{id}` | — |

### Market

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Market` | — | — |
| `edit` | `shopify/Market` | `gid://shopify/Market/{id}` | — |

### Menu

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Menu` | — | — |
| `edit` | `shopify/Menu` | `gid://shopify/Menu/{id}` | — |

### Metafield Definition

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/MetafieldDefinition` | — | — |
| `edit` | `shopify/MetafieldDefinition` | `gid://shopify/MetafieldDefinition/{id}` | — |

### Metaobject

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Metaobject` | — | `{ type: 'shopify--color-pattern' }` |
| `edit` | `shopify/Metaobject` | `gid://shopify/Metaobject/{id}` | — |

### Metaobject Definition

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/MetaobjectDefinition` | — | — |
| `edit` | `shopify/MetaobjectDefinition` | `gid://shopify/MetaobjectDefinition/{id}` | — |

### Page

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Page` | — | — |
| `edit` | `shopify/Page` | `gid://shopify/Page/{id}` | — |

### Product

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/Product` | — | — |
| `edit` | `shopify/Product` | `gid://shopify/Product/{id}` | — |

### Product Variant

| Action | Type | Value | Data |
| - | - | - | - |
| `create` | `shopify/ProductVariant` | — | `{ productId: 'gid://shopify/Product/{id}' }` |
| `edit` | `shopify/ProductVariant` | `gid://shopify/ProductVariant/{id}` | — |

* invoke

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

  Invoke an intent using the object syntax.

  Invoke an intent using the URL syntax.

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

### IntentQuery

* action

  ```ts
  IntentAction
  ```

* data

  Additional data required for certain intent types. For example: - Discount creation requires { type: 'amount-off-product' | 'amount-off-order' | 'buy-x-get-y' | 'free-shipping' } - ProductVariant creation requires { productId: 'gid://shopify/Product/123' } - Metaobject creation requires { type: 'shopify--color-pattern' }

  ```ts
  { [key: string]: unknown; }
  ```

* type

  ```ts
  IntentType
  ```

* value

  The resource identifier for edit actions (e.g., 'gid://shopify/Product/123').

  ```ts
  string
  ```

```ts
export interface IntentQuery extends IntentQueryOptions {
  action: IntentAction;
  type: IntentType;
}
```

### IntentAction

The action to perform on a resource.

```ts
'create' | 'edit'
```

### IntentType

Supported resource types that can be targeted by intents.

```ts
'shopify/Article' | 'shopify/Catalog' | 'shopify/Collection' | 'shopify/Customer' | 'shopify/Discount' | 'shopify/Market' | 'shopify/Menu' | 'shopify/MetafieldDefinition' | 'shopify/Metaobject' | 'shopify/MetaobjectDefinition' | 'shopify/Page' | 'shopify/Product' | 'shopify/ProductVariant'
```

### IntentActivity

Activity handle for tracking intent workflow progress.

* complete

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

  ```ts
  Promise<IntentResponse>
  ```

```ts
export interface IntentActivity {
  /**
   * A Promise that resolves when the intent workflow completes, returning the response.
   */
  complete?: Promise<IntentResponse>;
}
```

### IntentResponse

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

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

### ClosedIntentResponse

User dismissed or closed the workflow without completing it.

* code

  ```ts
  'closed'
  ```

```ts
export interface ClosedIntentResponse {
  code?: 'closed';
}
```

### SuccessIntentResponse

Successful intent completion.

* code

  ```ts
  'ok'
  ```

* data

  ```ts
  { [key: string]: unknown; }
  ```

```ts
export interface SuccessIntentResponse {
  code?: 'ok';
  data?: {[key: string]: unknown};
}
```

### ErrorIntentResponse

Failed intent completion.

* code

  ```ts
  'error'
  ```

* issues

  ```ts
  Issue[]
  ```

* message

  ```ts
  string
  ```

```ts
export interface ErrorIntentResponse {
  code?: 'error';
  message?: string;
  issues?: StandardSchemaV1.Issue[];
}
```

### IntentQueryOptions

Options for invoking intents when using the query string format.

* data

  Additional data required for certain intent types. For example: - Discount creation requires { type: 'amount-off-product' | 'amount-off-order' | 'buy-x-get-y' | 'free-shipping' } - ProductVariant creation requires { productId: 'gid://shopify/Product/123' } - Metaobject creation requires { type: 'shopify--color-pattern' }

  ```ts
  { [key: string]: unknown; }
  ```

* value

  The resource identifier for edit actions (e.g., 'gid://shopify/Product/123').

  ```ts
  string
  ```

```ts
export interface IntentQueryOptions {
  /**
   * The resource identifier for edit actions (e.g., 'gid://shopify/Product/123').
   */
  value?: string;
  /**
   * Additional data required for certain intent types.
   * For example:
   * - Discount creation requires { type: 'amount-off-product' | 'amount-off-order' | 'buy-x-get-y' | 'free-shipping' }
   * - ProductVariant creation requires { productId: 'gid://shopify/Product/123' }
   * - Metaobject creation requires { type: 'shopify--color-pattern' }
   */
  data?: {[key: string]: unknown};
}
```

## IntentAction

Supported actions that can be performed on resources.

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

`'create' | 'edit'`

## IntentType

Supported resource types that can be targeted by intents.

`'shopify/Article' | 'shopify/Catalog' | 'shopify/Collection' | 'shopify/Customer' | 'shopify/Discount' | 'shopify/Market' | 'shopify/Menu' | 'shopify/MetafieldDefinition' | 'shopify/Metaobject' | 'shopify/MetaobjectDefinition' | 'shopify/Page' | 'shopify/Product' | 'shopify/ProductVariant'`

## IntentQueryOptions

Options for invoking intents when using the query string format.

* data

  { \[key: string]: unknown; }

  Additional data required for certain intent types. For example:

  * Discount creation requires { type: 'amount-off-product' | 'amount-off-order' | 'buy-x-get-y' | 'free-shipping' }
  * ProductVariant creation requires { productId: 'gid://shopify/Product/123' }
  * Metaobject creation requires { type: 'shopify--color-pattern' }

* value

  string

  The resource identifier for edit actions (e.g., 'gid://shopify/Product/123').

## IntentResponse

Response object returned when the intent workflow completes.

`ClosedIntentResponse | SuccessIntentResponse | ErrorIntentResponse`

### ClosedIntentResponse

* code

  'closed'

### ErrorIntentResponse

* code

  'error'

* issues

  Issue\[]

* message

  string

### SuccessIntentResponse

* code

  'ok'

* data

  { \[key: string]: unknown; }

### ClosedIntentResponse

User dismissed or closed the workflow without completing it.

* code

  ```ts
  'closed'
  ```

```ts
export interface ClosedIntentResponse {
  code?: 'closed';
}
```

### SuccessIntentResponse

Successful intent completion.

* code

  ```ts
  'ok'
  ```

* data

  ```ts
  { [key: string]: unknown; }
  ```

```ts
export interface SuccessIntentResponse {
  code?: 'ok';
  data?: {[key: string]: unknown};
}
```

### ErrorIntentResponse

Failed intent completion.

* code

  ```ts
  'error'
  ```

* issues

  ```ts
  Issue[]
  ```

* message

  ```ts
  string
  ```

```ts
export interface ErrorIntentResponse {
  code?: 'error';
  message?: string;
  issues?: StandardSchemaV1.Issue[];
}
```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/admin/apis/intents.png)

## Examples

Intents for each Shopify resource type

### Article

### Catalog

### Collection

### Customer

### Discount

### Market

### Menu

### Metafield Definition

### Metaobject

### Metaobject Definition

### Page

### Product

### Product Variant