> ## Documentation Index
> Fetch the complete documentation index at: https://swish.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Intents

> Reference for all Swish SDK intents, their parameters, and invocation methods.

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.

```js theme={null}
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.

```html theme={null}
<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>`](https://swish.app/docs/references/sdk/elements#swish-drawer) instead of `swish-intent` - it wraps the same open-view intent and binds the count for you:

```html theme={null}
<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:

```html theme={null}
<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.

> [!TIP]
>
> 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.

```js theme={null}
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.

```js theme={null}
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. |

```js theme={null}
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. |

```js theme={null}
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.

```js theme={null}
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.

> [tab] Single item
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `variantId` | `number \| string` | Yes | Shopify variant ID or GID. |
> | `quantity` | `number` | No | Defaults to 1. |
>
> ```js theme={null}
> await swish.intents.invoke("create:cart-line", {
>   variantId: 44234567890123,
> });
> ```

> [tab] Multiple items
>
> | Parameter | Type | Required | Description |
> | - | - | - | - |
> | `items` | `Array<{ variantId, quantity? }>` | Yes | Array of items to add. |
>
> ```js theme={null}
> 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. |

### Navigation

#### `view:home`

Open Swish on the view [`ui.defaultView`](https://swish.app/docs/references/sdk/configuration) 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

#### `view:list-menu`

Open the context menu for a list.

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

#### `view:order-menu`

Open the context menu for an order.

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

#### `view:list-detail-page-menu`

Open the context menu on a list detail page.

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

#### `view:account-menu`

Open the account menu behind the [List detail page](https://swish.app/docs/guides/customize/views/list-detail-page.md)'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.

```js theme={null}
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`](https://swish.app/docs/references/sdk/configuration#initiatequickbuy) to `true` to open the dialog on a known variant too.

```js theme={null}
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](https://swish.app/docs/references/sdk/api-client.md#subscriptions).

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. |

```js theme={null}
// 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.

```js theme={null}
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. |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.