Intents API

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 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/DiscountNode/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

  Open the file picker so the merchant can choose existing files from the store. Use the `data` options to filter by media type, allow multiple selection, or pre-select files. The workflow resolves with the selected file IDs in `response.data.ids`.

  js

  const activity = await shopify.intents.invoke('pick:shopify/File', {
    data: {mediaTypes: ['MediaImage'], multiSelect: true},
  });
  
  const response = await activity.complete;
  
  if (response.code === 'ok') {
    console.log('Selected file IDs:', response.data.ids);
  } else if (response.code === 'closed') {
    console.log('Selection 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,
    });
  }