Intents API

The Intents API launches Shopify's native admin interfaces for creating and editing resources. When your extension calls an intent, merchants complete their changes using the standard Shopify admin UI, and your app receives the result. This means you don't need to build custom forms.

Use this API to build workflows like adding products to collections, creating multiple related resources in a sequence (like a product, collection, and discount for a promotion), opening specific resources for editing, or launching discount creation with pre-selected types.

Anchor to Use casesUse cases

Resource creation: Invoke admin workflows to create products, collections, discounts, or other Shopify resources.
Resource editing: Open existing Shopify resources for editing using their admin workflows.
Workflow completion: Await the result of an intent to determine whether the merchant completed or cancelled the operation.
Admin consistency: Use native Shopify admin workflows instead of building custom forms for resource management.

Anchor to invoke methodinvoke method

The invoke method launches a Shopify admin workflow for creating or editing 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 edit operations (for example, 'gid://shopify/Product/123'). Required when editing existing resources. Omit for create operations.
data ({ [key: string]: unknown }): Additional context required by specific resource types. For example, discounts require a type, variants require a product ID, and metaobjects require a definition type.

Supported resources

The following tables show which resource types you can create or edit, and what values you need to pass for value and data for each operation.

Article

Articles are blog posts published on the Online Store. Use this to create or edit articles for merchant blogs.

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

Catalog

Catalogs are product groupings that organize products for different markets or channels. Use this to create or edit catalogs for B2B or multi-market selling.

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

Collection

Collections are groups of products organized manually or by automated rules. Use this to create or edit product collections.

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

Customer

Customers are profiles with contact information, order history, and metadata. Use this to create or edit customer accounts.

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

Delivery profile

Delivery profiles define shipping rates and rules for products across locations and zones. Use this to create or edit shipping configurations for different product groups.

Action	Type	Value	Data
`create`	`shopify/DeliveryProfile`	—	—
`edit`	`shopify/DeliveryProfile`	`gid://shopify/DeliveryProfile/{id}`	—

Discount

Discounts are price reductions applied to products, orders, or shipping. Use this to create or edit discount codes and automatic discounts. Creating discounts requires specifying a discount type.

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

Location

Locations are physical or virtual places where merchants store inventory and fulfill orders. Use this to create or edit locations for managing stock and fulfillment.

Action	Type	Value	Data
`create`	`shopify/Location`	—	—
`edit`	`shopify/Location`	`gid://shopify/Location/{id}`	—

Market

Markets are geographic regions with customized pricing, languages, and domains. Use this to create or edit markets for international selling.

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

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

Metafield definition

Metafield definitions are schemas that define custom data fields for resources. Use this to create or edit metafield definitions that merchants can use to add structured data to products, customers, and other resources.

Action	Type	Value	Data
`create`	`shopify/MetafieldDefinition`	—	`{ ownerType: 'Product' }`
`edit`	`shopify/MetafieldDefinition`	`gid://shopify/MetafieldDefinition/{id}`	`{ ownerType: 'Product' }`

Metaobject

Metaobjects are custom structured data entries based on metaobject definitions. Use this to create or edit metaobject instances that store complex custom data. Requires a definition type.

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

Metaobject definition

Metaobject definitions are schemas that define the structure for metaobjects. Use this to create or edit metaobject definitions that determine the fields and data types for custom structured data.

Action	Type	Value	Data
`create`	`shopify/MetaobjectDefinition`	—	—
`edit`	`shopify/MetaobjectDefinition`	—	`{ type: 'my_metaobject_definition_type' }`

Page

Pages are static content pages for the Online Store. Use this to create or edit pages like About Us, Contact, or custom informational pages.

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

Product

Products are items sold in the store with pricing, inventory, and variants. Use this to create or edit products.

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

Product variant

Product variants are specific combinations of product options like size and color. Use this to create or edit product variants. Creating variants requires a parent product ID.

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

Note

When editing products with variants, query the product.hasOnlyDefaultVariant field first. If true, then use the shopify/Product edit intent. If false, then use the shopify/ProductVariant edit intent for specific variants.

Settings

Settings are the configuration options for the store. Use this to invoke and edit settings.

Action	Type	Value	Data
`edit`	`settings/GiftCardExpiration`	—	—
`edit`	`settings/LocationDefault`	—	—
`edit`	`settings/NotificationsSenderEmail`	—	—
`edit`	`settings/NotificationsStaff`	—	—
`edit`	`settings/OrderIdFormat`	—	—
`edit`	`settings/OrderProcessing`	—	—
`edit`	`settings/PaymentCaptureMethod`	—	—
`edit`	`settings/StoreDefaults`	—	—
`edit`	`settings/StoreDetails`	—	—

Anchor to invoke invoke { (query: ): Promise<>; (intentURL: string, options?: ): Promise<>; }: Invoke an intent using the object syntax.

Invoke an intent using the URL syntax.

URL format: action:type[,value][?params].
Anchor to response response: If in an intent workflow, provides mechanisms to resolve the intent with a given response.

IntentQuery

action
```
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' }
```
{ [key: string]: unknown; }
```
type
```
IntentType
```
value
The resource identifier for edit actions (e.g., 'gid://shopify/Product/123').
```
string
```

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'

IntentActivity

Activity handle for tracking intent workflow progress.

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

IntentResponse

Response object returned when the intent workflow completes.

ClosedIntentResponse | SuccessIntentResponse | ErrorIntentResponse

ClosedIntentResponse

User dismissed or closed the workflow without completing it.

code
```
'closed'
```

SuccessIntentResponse

Successful intent completion.

code
```
'ok'
```
data
```
{ [key: string]: unknown; }
```

ErrorIntentResponse

Failed intent completion.

code
```
'error'
```
issues
```
Issue[]
```
message
```
string
```

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' }
```
{ [key: string]: unknown; }
```
value
The resource identifier for edit actions (e.g., 'gid://shopify/Product/123').
```
string
```

IntentResponseApi

closed
If in an intent workflow, resolves the intent with a closed response.
```
() => Promise<void>
```
error
If in an intent workflow, resolves the intent with an error response and the provided message and issues, if any.
```
(message: string, issues?: Issue[]) => Promise<void>
```
ok
If in an intent workflow, resolves the intent with a success response and the provided data, if any.
```
(data?: { [key: string]: unknown; }) => Promise<void>
```

Anchor to IntentResponseIntentResponse

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

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

ClosedIntentResponse | SuccessIntentResponse | ErrorIntentResponse

Anchor to ClosedIntentResponse

ClosedIntentResponse

Anchor to code code 'closed'

Anchor to ErrorIntentResponse

ErrorIntentResponse

Anchor to code code 'error'
Anchor to issues issues Issue[]
Anchor to message message string

Anchor to SuccessIntentResponse

SuccessIntentResponse

Anchor to code code 'ok'
Anchor to data data { [key: string]: unknown; }

Anchor to requestrequest

When your app is opened through an app intent (for example, via an admin.app.intent.link target), the platform delivers the incoming intent to your embedded app in two complementary ways:

shopify.intents.request: A subscribable that exposes the current intent request to your app. Read the current request synchronously from shopify.intents.request.value. When your app isn't running inside an intent workflow, the value is null. Use shopify.intents.request.subscribe(callback) to react to changes if the host updates the current intent without reloading the iframe (for example, when a single-page app navigates between intent targets).
?intent=<URL-encoded JSON>: On the initial page load, the same payload is appended to your app's URL as a single intent query parameter. Read it from the incoming request URL when server-side rendering (for example, in a Remix loader or Next.js getServerSideProps), or from window.location in client-side code before App Bridge is ready.

Both paths expose the same action, type, value, and data fields. The exact contents of data differ slightly between the two paths. See the data row of the table for details.

Field	Type	Description
`action`	`string`	The operation the merchant is performing (for example, `'create'` or `'edit'`).
`type`	`string`	The intent type declared under `[[extensions.targeting.intents]]` in your extension's `shopify.extension.toml`. See Register your extension as an intent. For example, `application/email`.
`value`	`unknown`	The primary resource identifier when present. The exact shape is defined by your intent schema's `value` field; for an `application/email` intent that might be a campaign ID like `'42'`. Optional.
`data`	`{ [key: string]: unknown }`	Additional input fields defined by your intent's schema. From `shopify.intents.request.value`: the raw `data` from the original invocation, with no merging. From the URL `intent=` JSON: the same `data`, additionally merged with any input-schema fields whose `mapTo` is `'form_data'` (or the schema default). Fields declared with `mapTo: 'query_param'` arrive as separate query parameters on the launch URL (not inside the `intent=` JSON); fields with `mapTo: 'param'` land in the URL path. Optional.

Note: Read the intent payload once on load and store it in your app's state, or subscribe to it if your app stays mounted across intent transitions. The request tells you what to render. The merchant then completes the workflow in your UI, and you report the result through shopify.intents.response.

The URL intent= JSON may include additional internal fields beyond the four documented above. Those are runtime-only and not part of the public contract; treat them as Shopify-internal and don't rely on them in your app.

Anchor to response methodsresponse methods

The response methods resolve an app intent from inside the extension that's handling it. When your extension implements an app intent (for example, through an admin.app.intent.link target), call one of these methods to return control to the invoker with the appropriate outcome.

ok(data?): Resolves the intent with a success response. The optional data object is returned to the invoker as response.data.
error(message, issues?): Resolves the intent with an error response. The message describes the failure, and issues is an optional array of Standard Schema validation issues.
closed(): Resolves the intent as closed, indicating the merchant cancelled the workflow without completing it.

Each method returns a promise that resolves once the response has been delivered.

Anchor to closed closed () => Promise<void> required: If in an intent workflow, resolves the intent with a closed response.
Anchor to error error (message: string, issues?: Issue[]) => Promise<void> required: If in an intent workflow, resolves the intent with an error response and the provided message and issues, if any.
Anchor to ok ok (data?: { [key: string]: unknown; }) => Promise<void> required: If in an intent workflow, resolves the intent with a success response and the provided data, if any.

Examples

js

const activity = await shopify.intents.invoke('create:shopify/Collection');

const response = await activity.complete;

if (response.code === 'ok') {

console.log('Collection created:', response.data);

} else if (response.code === 'closed') {

console.log('Creation cancelled by user');

} else if (response.code === 'error') {

console.log('Error:', response.message);

}

Preview

Examples

Description

Launch the collection creation workflow in the Shopify admin. The merchant completes the form using the standard Shopify admin UI, and your app receives the result when the workflow completes.

js

const activity = await shopify.intents.invoke('create:shopify/Collection');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Collection created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the article creation workflow in the Shopify admin. The merchant writes and publishes the article using the standard Shopify admin UI, and your app receives the result when the workflow completes.

js

const activity = await shopify.intents.invoke('create:shopify/Article');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Article created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing article for editing in the Shopify admin. Pass the article's GID (for example, `gid://shopify/Article/123456789`) as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Article', {
  value: 'gid://shopify/Article/123456789',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Article updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the catalog creation workflow in the Shopify admin. The merchant completes the form using the standard Shopify admin UI, and your app receives the result when the workflow completes.

js

const activity = await shopify.intents.invoke('create:shopify/Catalog');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Catalog created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing catalog for editing in the Shopify admin. Pass the catalog's GID as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Catalog', {
  value: 'gid://shopify/Catalog/123456789',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Catalog updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing collection for editing in the Shopify admin. Pass the collection's GID as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Collection', {
  value: 'gid://shopify/Collection/987654321',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Collection updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the customer creation workflow in the Shopify admin. The merchant completes the form using the standard Shopify admin UI, and your app receives the result when the workflow completes.

js

const activity = await shopify.intents.invoke('create:shopify/Customer');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Customer created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing customer for editing in the Shopify admin. Pass the customer's GID as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Customer', {
  value: 'gid://shopify/Customer/456789123',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Customer updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description
Launch the delivery profile creation workflow in the Shopify admin. The merchant configures shipping zones, rates, and product assignments using the standard Shopify admin UI, and your app receives the result when the workflow completes.
js
```
const activity = await shopify.intents.invoke('create:shopify/DeliveryProfile');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Delivery profile created:', response.data);
}
```

Description

Open an existing delivery profile for editing in the Shopify admin. Pass the delivery profile's GID as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/DeliveryProfile', {
  value: 'gid://shopify/DeliveryProfile/123456789',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Delivery profile updated:', response.data);
}

Description

Launch the discount creation workflow in the Shopify admin. You must specify the discount type in the `data` parameter. Valid types are `'amount-off-product'`, `'amount-off-order'`, `'buy-x-get-y'`, and `'free-shipping'`. Your app receives the result when the merchant completes the workflow.

js

const activity = await shopify.intents.invoke('create:shopify/Discount', {
  data: {type: 'amount-off-product'},
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Discount created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing discount for editing in the Shopify admin. Pass the discount's GID as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Discount', {
  value: 'gid://shopify/Discount/123456789',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Discount updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Create a new location. Opens the location creation workflow.

js

const activity = await shopify.intents.invoke('create:shopify/Location');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Location created:', response.data);
}

Description

Edit an existing location. Requires a location GID.

js

const activity = await shopify.intents.invoke('edit:shopify/Location', {
  value: 'gid://shopify/Location/123456789',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Location updated:', response.data);
}

Description

Edit the default location.

js

const activity = await shopify.intents.invoke('edit:settings/LocationDefault');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Settings updated:', response.data);
}

Description

Launch the market creation workflow in the Shopify admin. The merchant completes the form using the standard Shopify admin UI, and your app receives the result when the workflow completes.

js

const activity = await shopify.intents.invoke('create:shopify/Market');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Market created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing market for editing in the Shopify admin. Pass the market's GID as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Market', {
  value: 'gid://shopify/Market/123456789',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Market updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the menu creation workflow in the Shopify admin. The merchant completes the form using the standard Shopify admin UI, and your app receives the result when the workflow completes.

js

const activity = await shopify.intents.invoke('create:shopify/Menu');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Menu created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing menu for editing in the Shopify admin. Pass the menu's GID as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Menu', {
  value: 'gid://shopify/Menu/123456789',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Menu updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the metafield definition creation workflow in the Shopify admin. You must specify the owner type in the `data` parameter (for example, `'product'`). Your app receives the result when the merchant completes the workflow.

js

const activity = await shopify.intents.invoke(
  'create:shopify/MetafieldDefinition',
  {data: {ownerType: 'product'}},
);

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Metafield definition created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing metafield definition for editing in the Shopify admin. Pass the metafield definition's GID as the value and the owner type in the `data` parameter. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke(
  'edit:shopify/MetafieldDefinition',
  {
    value: 'gid://shopify/MetafieldDefinition/123456789',
    data: {ownerType: 'product'},
  },
);

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Metafield definition updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the metaobject creation workflow in the Shopify admin. You must specify the metaobject type in the `data` parameter (for example, `'shopify--color-pattern'`). Your app receives the result when the merchant completes the workflow.

js

const activity = await shopify.intents.invoke('create:shopify/Metaobject', {
  data: {type: 'shopify--color-pattern'},
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Metaobject created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing metaobject for editing in the Shopify admin. Pass the metaobject's GID as the value and the metaobject type in the `data` parameter. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Metaobject', {
  value: 'gid://shopify/Metaobject/123456789',
  data: {type: 'shopify--color-pattern'},
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Metaobject updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the metaobject definition creation workflow in the Shopify admin. The merchant completes the form using the standard Shopify admin UI, and your app receives the result when the workflow completes.

js

const activity = await shopify.intents.invoke(
  'create:shopify/MetaobjectDefinition',
);

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Metaobject definition created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing metaobject definition for editing in the Shopify admin. Pass the metaobject definition type in the `data` parameter. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke(
  'edit:shopify/MetaobjectDefinition',
  {data: {type: 'my_metaobject_definition_type'}},
);

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Metaobject definition updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the page creation workflow in the Shopify admin. The merchant completes the form using the standard Shopify admin UI, and your app receives the result when the workflow completes.

js

const activity = await shopify.intents.invoke('create:shopify/Page');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Page created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing page for editing in the Shopify admin. Pass the page's GID as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Page', {
  value: 'gid://shopify/Page/123456789',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Page updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the product creation workflow in the Shopify admin. The merchant completes the form using the standard Shopify admin UI, and your app receives the result when the workflow completes.

js

const activity = await shopify.intents.invoke('create:shopify/Product');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Product created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing product for editing in the Shopify admin. Pass the product's GID as the value. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/Product', {
  value: 'gid://shopify/Product/123456789',
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Product updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Launch the product variant creation workflow in the Shopify admin. You must specify the parent product's GID in the `data` parameter. Your app receives the result when the merchant completes the workflow.

js

const activity = await shopify.intents.invoke('create:shopify/ProductVariant', {
  data: {productId: 'gid://shopify/Product/123456789'},
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Product variant created:', response.data);
} else if (response.code === 'closed') {
  console.log('Creation cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Open an existing product variant for editing in the Shopify admin. Pass the variant's GID as the value and the parent product's GID in the `data` parameter. Your app receives the updated data when the merchant saves their changes.

js

const activity = await shopify.intents.invoke('edit:shopify/ProductVariant', {
  value: 'gid://shopify/ProductVariant/123456789',
  data: {productId: 'gid://shopify/Product/123456789'},
});

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Product variant updated:', response.data);
} else if (response.code === 'closed') {
  console.log('Edit cancelled by user');
} else if (response.code === 'error') {
  console.log('Error:', response.message);
}

Description

Invoke and edit store details.

js

const activity = await shopify.intents.invoke('edit:settings/StoreDetails');

const response = await activity.complete;

if (response.code === 'closed') {
  console.log('Settings closed:', response.data);
}

Description

Invoke and edit store defaults.

js

const activity = await shopify.intents.invoke('edit:settings/StoreDefaults');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Settings updated:', response.data);
}

Description

Invoke and edit order ID format.

js

const activity = await shopify.intents.invoke('edit:settings/OrderIdFormat');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Settings updated:', response.data);
}

Description

Invoke and edit order processing.

js

const activity = await shopify.intents.invoke('edit:settings/OrderProcessing');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Settings updated:', response.data);
}

Description

Invoke and edit the gift card expiration policy for the store.

js

const activity = await shopify.intents.invoke('edit:settings/GiftCardExpiration');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Settings updated:', response.data);
}

Description

Invoke and edit the payment capture method for the store.

js

const activity = await shopify.intents.invoke('edit:settings/PaymentCaptureMethod');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Settings updated:', response.data);
}

Description

Invoke and edit the sender email address used for customer notifications.

js

const activity = await shopify.intents.invoke('edit:settings/NotificationsSenderEmail');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Settings updated:', response.data);
}

Description

Invoke and edit the staff notification settings for the store.

js

const activity = await shopify.intents.invoke('edit:settings/NotificationsStaff');

const response = await activity.complete;

if (response.code === 'ok') {
  console.log('Settings updated:', response.data);
}

Description

From inside an app intent, resolve the intent with a success, error, or closed response. Call `shopify.intents.response.ok(data)` when the merchant completes the workflow, `shopify.intents.response.error(message)` when it fails, or `shopify.intents.response.closed()` when the merchant cancels. The invoking surface receives the matching [`IntentResponse`](#intentresponse).

js

// Inside an embedded app route that's been registered as an admin link
// intent (see /docs/apps/build/sidekick/build-app-actions), resolve the
// intent by calling one of the response methods when the merchant
// finishes the workflow.

async function handleSave(formValues) {
  try {
    const result = await saveEmailCampaign(formValues);
    await shopify.intents.response.ok({campaignId: result.id});
  } catch (error) {
    await shopify.intents.response.error(error.message);
  }
}

async function handleCancel() {
  await shopify.intents.response.closed();
}

Description

Read the incoming intent payload from `shopify.intents.request.value` when your app is opened as an app intent. Use the `action`, `type`, `value`, and `data` fields to drive your initial render. The value is `null` outside an intent workflow. Use `shopify.intents.request.subscribe(callback)` if your app stays mounted across intent transitions and you need to react to updates.

js

// Read the incoming intent payload when your app is opened as an app
// intent. The current value is available synchronously at
// `shopify.intents.request.value`. It's `null` when the app isn't
// running inside an intent workflow.

const request = shopify.intents.request?.value;

if (request) {
  // request.action — the operation (for example, 'create' or 'edit')
  // request.type — the intent type declared in shopify.extension.toml
  // request.value — the primary resource identifier when present
  // request.data — fields defined by the intent's input schema
  renderEmailComposer({
    action: request.action,
    campaignId: request.value,
    subject: request.data?.subject,
    recipient: request.data?.recipient,
  });
}

// If your app stays mounted across intent transitions (for example, a
// single-page app navigating between intent targets), subscribe to
// changes instead.
const unsubscribe = shopify.intents.request?.subscribe((next) => {
  if (next) renderEmailComposer({action: next.action, campaignId: next.value});
});

Description

Read the incoming intent payload synchronously from the URL when your app is launched via an app intent. The platform appends the same payload as a URL-encoded JSON `intent` query parameter, so you can parse it from `window.location` before App Bridge is ready (for example, during server-side rendering).

js

// Read the incoming intent payload synchronously from the URL. When your
// app is launched via an app intent, the platform appends the payload as
// a URL-encoded JSON `intent` query parameter.
//
// In server-side rendering contexts (for example, Remix loaders or
// Next.js `getServerSideProps`), parse the intent from the incoming
// request URL. In client-side code, parse it from `window.location`
// before App Bridge loads.

// Client-side example:
const params = new URLSearchParams(window.location.search);
const rawIntent = params.get('intent');

if (rawIntent) {
  const request = JSON.parse(rawIntent);

  renderEmailComposer({
    action: request.action,
    campaignId: request.value,
    subject: request.data?.subject,
    recipient: request.data?.recipient,
  });
}

Was this page helpful?