Quickstart

To start building with Swish, we recommend using the Swish SDK, Components and Intents.

Install Swish from the Shopify App Store
Before continuing with this quickstart, make sure Swish is installed in your Shopify store.

The Swish SDK delivers a consistent, high-performance experience across different JavaScript environments. Whether you’re building within a Shopify theme, using Hydrogen, or integrating custom storefronts, Swish makes it simple to add powerful shopping tools to your store.

Liquid
React

Enable the app embed

Open the Shopify theme editor and enable the Swish embed block. The embed loads the SDK automatically and handles storefront credentials, customer context, and localization for you - no code required.

Go to Online Store > Themes > Customize.
Open App embeds (in the left sidebar).
Toggle Swish embed on and click Save.

Install the Swish snippet

Copy the swish.liquid snippet into snippets/ and the matching swish-theme.css starter into assets/. Then render the snippet’s init block in theme.liquid before {{ content_for_header }} - it sets window.SwishOptions and loads the stylesheet so the embed picks them up.

theme.liquid

{%- render 'swish' -%}
{{ content_for_header }}

Add a save button on a product detail page

Let customers save and unsave products from any product detail page.

Snippet
Placement

Render the save component anywhere on a product page. The snippet defaults to context="pdp" - the SDK reads the product from the current URL and reacts to SPA navigation.

{%- render 'swish', component: 'save', context: 'pdp' -%}

For product cards in a collection grid, pass context: 'product-card' and the SDK walks to the nearest product link instead.

{%- render 'swish', component: 'save', context: 'product-card' -%}

See the elements reference for the full attribute set.

Declare a placement in SwishOptions to target your product form and mount a save button automatically. Swish resolves the product from the page URL.

window.SwishOptions = {
  placements: [
    {
      id: "pdp-save-button",
      target: { selector: ".product-form" },
      mount: { mode: "after" },
      element: { name: "save-button" },
      layout: { type: "inline" },
    },
  ],
};

See Product detail placement for styling and layout options.

Add a home button

Give customers a way to access their saved items, notifications, and other Swish features.

Snippet
Placement

Render the drawer component in your header. The default view is home; pass view: to open saves, lists, orders, notifications, or profile instead.

{%- render 'swish', component: 'drawer' -%}

See the elements reference for the full attribute set.

Declare a placement in SwishOptions to mount the home button in your store header. The button includes a built-in count badge.

window.SwishOptions = {
  placements: [
    {
      id: "header-header-button",
      target: { selector: ".header__icons" },
      mount: { mode: "prepend" },
      element: { name: "header-button" },
    },
  ],
};

See Header placement for styling and customization options.

Customize (optional)

Two surfaces, two scopes:SwishOptions configures the Swish app. This is everything the SDK runs - the drawer UI, design tokens, intent options, translations, and so on. Edit it inside the swish_init capture in snippets/swish.liquid:

snippets/swish.liquid

{% capture swish_init %}
  <script>
    window.SwishOptions = {
      ui: {
        design: {
          colors: {
            primaryButtonBackgroundRgb: "0 0 0",
          },
        },
      },
    }
  </script>
  {{ 'swish-theme.css' | asset_url | stylesheet_tag: preload: true }}
{% endcapture %}

See the configuration reference for the full set of options.assets/swish-theme.css styles the Liquid-rendered elements only. Paste merchant button styles into the empty rule bodies - they target <swish-save> and <swish-drawer> and their children. This stylesheet does not affect the SDK-injected drawer UI; that’s controlled by SwishOptions.ui.design (and ui.css if you need a full custom stylesheet for the app).

Loading without the app embed

If you cannot use the app embed, load the SDK manually in theme.liquid. You need to provide storefront credentials and customer context yourself.

theme.liquid

<script>
  window.SwishOptions = {
    storefront: {
      storeDomain: {{ shop.permanent_domain | json }},
      accessToken: "YOUR_STOREFRONT_API_TOKEN",
    },
    context: {
      newCustomerAccounts: true,
      myshopifyDomain: {{ shop.permanent_domain | json }},
      shopName: {{ shop.name | replace: '&amp;', '&' | json }},
      moneyFormat: {{ shop.money_format | json }},
      customer: {
        id: {{ customer.id | json }},
        email: {{ customer.email | json }},
        firstName: {{ customer.first_name | json }},
        lastName: {{ customer.last_name | json }},
        b2b: {{ customer.b2b | json }},
      },
      localization: {
        country: {{ localization.country.iso_code | json }},
        language: {{ localization.language.iso_code | json }},
        market: {{ localization.market.id | json }},
      },
      routes: {
        accountUrl: {{ routes.account_url | json }},
        rootUrl: {{ routes.root_url | json }},
      },
    },
  };
</script>

<script type="module">
  import { createSwish } from "https://swish.app/cdn/sdk@latest/swish.js";

  await createSwish(window.SwishOptions);
</script>

Replace YOUR_STOREFRONT_API_TOKEN with your Shopify Storefront API access token. See the configuration reference for instructions on obtaining one.

Install packages

npm install @swishapp/react

pnpm add @swishapp/react

yarn add @swishapp/react

Add SwishProvider

Wrap your app in SwishProvider so all child components can use Swish hooks.

import { SwishProvider } from "@swishapp/react";

function App() {
  return (
    <SwishProvider
      options={{
        storefront: {
          storeDomain: "my-store.myshopify.com",
          accessToken: "your-storefront-access-token",
        },
        context: {
          customer: { id: customerId, email, firstName, lastName },
          localization: { country: "US", language: "EN", market: "us" },
          myshopifyDomain: "my-store.myshopify.com",
          shopName: "My Store",
          newCustomerAccounts: true,
          routes: { accountUrl: "/account" },
        },
      }}
    >
      {/* Your app */}
    </SwishProvider>
  );
}

See the Next.js or Hydrogen guide for a complete headless setup.

Add a save button

Use useSwishItem on a product detail page to let customers save and unsave products.

import { useSwishItem } from "@swishapp/react";

function SaveButton({ productId }: { productId: string }) {
  const { saved, toggle, loading } = useSwishItem({ productId });

  return (
    <button type="button" onClick={toggle} disabled={loading}>
      {saved ? "Saved" : "Save"}
    </button>
  );
}

Add a home button

Give customers a way to access their saved items, notifications, and other Swish features. The swish-intent attribute works in React too - no hook needed.

function SwishHomeButton() {
  return (
    <button type="button" swish-intent="view:home">
      Swish Home
    </button>
  );
}

Direct API access

Swish provides a Rest API for advanced use cases where direct server-side or third-party integration is required.

Use the direct API only when your project cannot run the SDK (e.g. on backend servers or native apps).

This API is primarily intended for:

Third-party integrations - connecting Swish data to other systems or services.
Server-side operations - running custom business logic or syncing data securely.
Native mobile apps - integrating Swish features directly into iOS or Android applications.

Whenever possible, we recommend using the Swish SDK, which handles authentication, performance optimizations, and UI integration automatically. The SDK abstracts much of the complexity involved in communicating with the API, ensuring a faster and more reliable development experience.

Get started

Features

Customize

Headless

AI tools

Direct API access

​Direct API access

Direct API access