Intents - Swish Docs

Intents are the primary way to trigger Swish actions from your storefront. Each intent represents a specific action - saving a product, opening a list, starting a checkout - and the SDK handles the UI and workflow automatically.

Invoking intents

From JavaScript

Use swish.intents.invoke() to trigger an intent programmatically. It returns a promise that resolves to an activity handle with a complete property you can await for the result.

const activity = await swish.intents.invoke("save:item", {
  productId: 8234567890123,
});

const response = await activity.complete;

if (response.code === "ok") {
  console.log("Item saved:", response.data);
}

From HTML attributes

Add the swish-intent attribute to any clickable element. The SDK automatically attaches a click handler. Parameters use search-param style syntax after the intent name.

<button type="button" swish-intent="save:item?product=8234567890123">Save product</button>

<!-- Product handles work too -->
<button type="button" swish-intent="save:item?product=meadow-dress&variant=51565037781329">
  Save product
</button>

For drawer triggers with a live saved-item count, use <swish-drawer> instead of swish-intent - it wraps the same open-view intent and binds the count for you:

<swish-drawer view="home">
  <button type="button">
    Wishlist <span data-swish-bind="count" data-swish-when="has-saves" hidden>0</span>
  </button>
</swish-drawer>

From URL query strings

Trigger intents via URL parameters. This is useful for deep links in emails or external campaigns. Intent parameters are passed as standard URL query params alongside swish-intent.

# Open the Swish home drawer
https://your-store.com?swish-intent=view:home

# Save the product with ID 8234567890123
https://your-store.com?swish-intent=save:item&product=8234567890123

From Shopify product URLs

On product detail pages, the SDK automatically reads the product handle from the URL path and the variant from the query string. You can turn any product URL into a save link by adding &swish-intent=save:item.

https://your-store.com/products/meadow-dress?variant=51565037781329&swish-intent=save:item

This also works with anchor links inside your store:

<a href="/products/meadow-dress?variant=51565037781329&swish-intent=save:item">
  Save this product
</a>

From URL hash

A subset of navigation intents can be triggered via URL hash:

Hash	Intent
`#swish` or `#swish-home`	`view:home`
`#swish-lists`	`view:lists`
`#swish-orders`	`view:orders`
`#swish-saves`	`view:saves`
`#swish-notifications`	`view:notifications`
`#swish-profile`	`view:profile`

String parameter names

When invoking intents from HTML attributes or URLs, use these short parameter names:

String param	JS API param	Description
`product`	`productId`	Shopify product ID, GID, or handle.
`variant`	`variantId`	Shopify variant ID or GID.
`list`	`listId`	List ID.
`order`	`orderId`	Order ID.
`item`	`itemId`	Saved item ID.

The product parameter accepts a numeric ID, a Shopify GID, or a product handle (e.g. meadow-dress). When a handle is provided, the SDK resolves it to a product ID via the Storefront API.

The long-form names (productId, variantId, etc.) also work in strings and URLs as a fallback, but the short names are recommended.

Response format

Every intent resolves with a response containing a code field:

Code	Meaning
`ok`	The intent completed successfully. Response includes a `data` field.
`closed`	The user dismissed the UI without completing the action.
`error`	The intent failed. Response includes `message` and `issues` fields.

Listening for intent completions

Use swish.intents.listen() to subscribe to intent completions without invoking them yourself. This is useful for reacting to intents triggered by the Swish UI or declarative triggers.

const unsubscribe = swish.intents.listen("save:item", (response) => {
  if (response.code === "ok") {
    console.log("Item saved:", response.data);
  }
});

Cross-intent resolution

Some intents can resolve as a different intent depending on what the customer does. For example, unsave:item can resolve as edit:item-lists when the customer moves an item to another list instead of removing it. When this happens and the intent succeeds, the SDK fires listeners for both the originally invoked intent and the resolved intent. This means your listener catches the action regardless of which intent triggered it.

swish.intents.listen("edit:item-lists", (response) => {
  // Fires when edit:item-lists is invoked directly,
  // and when unsave:item resolves as edit:item-lists
  console.log("Item lists changed:", response.data);
});

Intents that can resolve as a different intent:

Invoked intent	Can resolve as	When
`unsave:item`	`edit:item-lists`	The customer moves the item to another list.
`initiate:quick-buy`	`create:cart-line`	A `variantId` is given and `promptVariantIfPresent` is `false`, the default.
`edit:item-lists`	`unsave:item`	Editing list assignments results in the item being removed.
`view:list-menu`	`edit:list`	The customer selects edit from the menu.
`view:list-menu`	`delete:list`	The customer selects delete from the menu.
`view:list-menu`	`edit:list-access`	The customer toggles public/private access.
`view:list-menu`	`initiate:share`	The customer selects share from the menu.
`view:account-menu`	`view:lists`	The customer selects their lists from the menu.
`view:account-menu`	`initiate:sign-out`	The customer selects sign out from the menu.

Intent reference

Items

`save:item`

Save a product to the customer’s list.

Parameter	Type	Required	Description
`productId`	`number \| string`	Yes	Shopify product ID or GID.
`variantId`	`number \| string`	No	Specific variant to save.
`quantity`	`number`	No	Quantity to save. Minimum 1.
`tags`	`string[]`	No	Tags to attach to the saved item.

await swish.intents.invoke("save:item", {
  productId: "gid://shopify/Product/8234567890123",
  variantId: 44234567890123,
});

`unsave:item`

Remove a saved item.

Parameter	Type	Required	Description
`itemId`	`string`	Yes	The saved item ID.
`delete`	`boolean`	No	Skip confirmation and delete immediately.

`edit:item-variant`

Change the selected variant on a saved item.

Parameter	Type	Required	Description
`itemId`	`string`	Yes	The saved item ID.
`productId`	`number \| string`	Yes	Shopify product ID or GID.
`variantId`	`number \| string`	No	The new variant to select.

`edit:item-quantity`

Change the quantity stored on a saved item. The product detail view in the drawer invokes it when the customer changes the quantity input on a saved item.

Parameter	Type	Required	Description
`itemId`	`string`	Yes	The saved item ID.
`quantity`	`number`	Yes	The new quantity. Minimum 1.

await swish.intents.invoke("edit:item-quantity", {
  itemId: item.id,
  quantity: 3,
});

`edit:item-lists`

Move or copy a saved item between lists.

Parameter	Type	Required	Description
`itemId`	`string`	Yes	The saved item ID.

Lists

`create:list`

Open the create list dialog. No parameters.

await swish.intents.invoke("create:list");

`edit:list`

Open the edit dialog for an existing list.

Parameter	Type	Required	Description
`listId`	`string`	Yes	The list ID.

`edit:list-access`

Change a list’s visibility.

Parameter	Type	Required	Description
`listId`	`string`	Yes	The list ID.
`access`	`"public" \| "private"`	Yes	The new access level.

`delete:list`

Delete a list.

Parameter	Type	Required	Description
`listId`	`string`	Yes	The list ID.

`initiate:share`

Open the share dialog for a list.

Parameter	Type	Required	Description
`listId`	`string`	Yes	The list ID.

Cart

`create:cart-line`

Add one or more items to the cart.

Single item
Multiple items

Parameter	Type	Required	Description
`variantId`	`number \| string`	Yes	Shopify variant ID or GID.
`quantity`	`number`	No	Defaults to 1.

await swish.intents.invoke("create:cart-line", {
  variantId: 44234567890123,
});

Parameter	Type	Required	Description
`items`	`Array<{ variantId, quantity? }>`	Yes	Array of items to add.

await swish.intents.invoke("create:cart-line", {
  items: [
    { variantId: 44234567890123, quantity: 2 },
    { variantId: 44234567890456 },
  ],
});

`initiate:checkout`

Start a checkout with one or more items. Accepts the same parameters as create:cart-line.

`save:cart-line`

Save removed cart items to the customer’s list. Typically triggered automatically when the removeCartLine.saveCartLine option is enabled.

Parameter	Type	Required	Description
`items`	`Array<{ productId, variantId, quantity, title?, image?, variantTitle? }>`	Yes	Cart items to save.

`view:home`

Open Swish on the view ui.defaultView names, which is the Home view unless you change it. No parameters.

`view:saves`

Open the saved items view. No parameters.

`view:lists`

Open the lists view. No parameters.

`view:list`

Open a specific list.

Parameter	Type	Required	Description
`listId`	`string`	Yes	The list ID.
`listType`	`"user" \| "smart" \| "shared"`	No	Defaults to `"user"`.

`view:orders`

Open the orders view. No parameters.

`view:order`

Open a specific order.

Parameter	Type	Required	Description
`orderId`	`number \| string`	Yes	The order ID.

`view:notifications`

Open the notifications view. No parameters.

`view:profile`

Open the customer profile. No parameters.

`view:product`

Open the product detail view.

Parameter	Type	Required	Description
`productId`	`number \| string`	Yes	Shopify product ID or GID.
`variantId`	`number \| string`	No	Specific variant to display.

Menus

Open the context menu for a list.

Parameter	Type	Required	Description
`listId`	`string`	Yes	The list ID.

Open the context menu for an order.

Parameter	Type	Required	Description
`orderId`	`string`	Yes	The order ID.

Open the context menu on a list detail page.

Parameter	Type	Required	Description
`listId`	`string`	Yes	The list ID.

Open the account menu behind the List detail page’s account button: the customer’s lists, their account page and sign out. Takes no parameters. The lists row is only offered where the drawer is on, and the account row is a plain link to the store’s account URL.

Auth

`initiate:sign-in`

Start the sign-in flow with a redirect.

Parameter	Type	Required	Description
`returnTo`	`string`	Yes	URL to redirect to after sign-in.

`initiate:sign-out`

Sign the customer out and redirect to the store root. No parameters.

await swish.intents.invoke("initiate:sign-out");

UI

`initiate:quick-buy`

Open the quick buy dialog for a product, or add a known variant straight to the cart.

Parameter	Type	Required	Description
`productId`	`number \| string`	Yes	Shopify product ID or GID.
`variantId`	`number \| string`	No	The variant to add, or to pre-select in the dialog.
`quantity`	`number`	No	The amount added, or the quantity the dialog opens on, 1 or more. Defaults to 1.

With a variantId, there is nothing left to pick, so the variant goes straight to the cart and the intent resolves as create:cart-line. Without one, the dialog opens for the customer to pick a variant. Set promptVariantIfPresent to true to open the dialog on a known variant too.

const activity = await swish.intents.invoke("initiate:quick-buy", {
  productId: 8375112,
  variantId: 44921038,
  quantity: 2,
});

const response = await activity.complete;
if (response.code === "ok" && response.intent === "create:cart-line") {
  console.log("Added to cart:", response.data);
}

`create:subscription`

Open the Notify Me dialog so a shopper can ask to hear when a sold-out variant is back in stock. Submitting it creates a back-in-stock subscription. Subscriptions are variant-level, but variantId is optional: omit it and the dialog shows a variant picker and resolves the variant before it subscribes. Pass it and the dialog opens straight on that variant with only the email left to fill in.

Parameter	Type	Required	Description
`productId`	`number \| string`	Yes	Shopify product ID or GID.
`variantId`	`number \| string`	No	Shopify variant ID or GID. Omit to let the shopper pick in the dialog.

// The shopper has picked a size, and it is sold out.
const activity = await swish.intents.invoke("create:subscription", {
  productId: 8375112,
  variantId: 44921038,
});

const response = await activity.complete;
if (response.code === "ok") {
  console.log(response.data.subscription.id);
}

On a product that is sold out in every size with nothing picked yet, leave variantId off. The dialog opens on an empty picker and the subscription it returns is for the variant the shopper settled on there.

const activity = await swish.intents.invoke("create:subscription", {
  productId: 8375112,
});

A signed-in shopper’s email is pre-filled from context.customer.email; a guest types one and subscribes on a session token. Submitting confirms in place and the dialog stays there until the shopper dismisses it, so activity.complete resolves when they close the confirmation rather than the moment they submit. A shopper who subscribes and then closes still comes back as ok with their subscription; one who closes without subscribing comes back as closed.

`show:toast`

Display a toast notification.

Parameter	Type	Required	Description
`text`	`string`	Yes	The toast message.
`title`	`string`	No	Optional heading.
`image`	`string`	No	Image URL to display.
`icon`	`string`	No	Icon name to display.
`variant`	`"compact" \| "full"`	No	Toast layout style.
`action`	`{ label, url? }`	No	Action button with optional link.

await swish.intents.invoke("show:toast", {
  title: "Added to wishlist",
  text: "Classic Leather Jacket saved.",
  variant: "compact",
  action: { label: "View list", url: "/pages/wishlist" },
});

​Invoking intents

​From JavaScript

​From HTML attributes

​From URL query strings

​From Shopify product URLs

​From URL hash

​String parameter names

​Response format

​Listening for intent completions

​Cross-intent resolution

​Intent reference

​Items

​save:item

​unsave:item

​edit:item-variant

​edit:item-quantity

​edit:item-lists

​Lists

​create:list

​edit:list

​edit:list-access

​delete:list

​initiate:share

​Cart

​create:cart-line

​initiate:checkout

​save:cart-line

​Navigation

​view:home

​view:saves

​view:lists

​view:list

​view:orders

​view:order

​view:notifications

​view:profile

​view:product

​Menus

​view:list-menu

​view:order-menu

​view:list-detail-page-menu

​view:account-menu

​Auth

​initiate:sign-in

​initiate:sign-out

​UI

​initiate:quick-buy

​create:subscription

​show:toast

Invoking intents

From JavaScript

From HTML attributes

From URL query strings

From Shopify product URLs

From URL hash

String parameter names

Response format

Listening for intent completions

Cross-intent resolution

Intent reference

Items

`save:item`

`unsave:item`

`edit:item-variant`

`edit:item-quantity`

`edit:item-lists`

Lists

`create:list`

`edit:list`

`edit:list-access`

`delete:list`

`initiate:share`

Cart

`create:cart-line`

`initiate:checkout`

`save:cart-line`

Navigation

`view:home`

`view:saves`

`view:lists`

`view:list`

`view:orders`

`view:order`

`view:notifications`

`view:profile`

`view:product`

Menus

`view:list-menu`

`view:order-menu`

`view:list-detail-page-menu`

`view:account-menu`

Auth

`initiate:sign-in`

`initiate:sign-out`

UI

`initiate:quick-buy`

`create:subscription`

`show:toast`