# Shopify: legacy setup

**Coming soon:** the twelvebit app is in review at the Shopify App Store. Until it is live, this page is the way to connect a store.

This page is for stores that connected before the twelvebit app: with a tag in the theme and a custom app. These stores keep working. New stores install the [twelvebit app](/docs/install#shopify): there is no code to paste, no id to copy and no theme file to edit.

To move to the app, install it, then remove the theme tag and uninstall the custom app in Shopify. If the tag and the app embed both run, the script runs once on each page, so visits do not count twice.

## The theme tag

1. **Add the tag to the theme.** Online Store → Themes → … → Edit code → `layout/theme.liquid`. Paste this tag before `</head>` and save. `?shopify=1` turns on Shopify mode: the script puts the visitor on the cart, so each order joins the visit that led to it, and it sends the `add_to_cart` and `initiate_checkout` goals.

~~~html
<script defer data-website-id="tb_YOUR_SITE_ID" data-domain="example.com" src="https://twelvebit.app/js/script.js?shopify=1"></script>
~~~

2. **[Connect the store](#connect-the-store-with-a-custom-app)** with a custom app, so that twelvebit records each paid order. Checkout pages on Shopify do not load theme code, so the orders come from the connection, not from the script.

Shopify refuses new script tags since 1 October 2026 and stops running all script tags on 1 March 2027. The connection keeps a script tag that works and never fails because of one; the theme tag is the copy that counts. On Shopify, cookieless mode goes on the theme tag: add `data-cookieless="true"`.

## Connect the store with a custom app

In the Shopify admin, open **Settings → Apps → Develop apps**. What you see there tells you which steps to do.

### Build apps in Dev Dashboard (most stores)

Since January 2026, Shopify creates new custom apps in the **Dev Dashboard**.

1. Click **Build apps in Dev Dashboard**, then **Create app**.
2. Fill in only two fields: **App name** "twelvebit" and **Scopes** `read_orders,write_script_tags,read_customers`. Keep the default values in all the other fields (App URL, embed, redirection URLs, install flow, webhooks API version). twelvebit does not use them. Click **Create app**.
3. In the Dev Dashboard, open **Apps** and click the name "twelvebit". The **Overview** page opens. In the **Installs** box, click **Install app**, choose the store and approve.
4. Come back to **Overview**. In the **Credentials** box, copy the **Client ID** and the **Client secret**.
5. In twelvebit, open the site's revenue settings, choose **Shopify**, and paste the shop domain (`acme.myshopify.com` or the store's own domain), the client ID and the client secret.

Shopify releases the first version by itself, so you do not need to create a version. The app also shows in the store admin under **Apps**. It opens the example.com page there. This is correct: the app has no page of its own.

### Create an app (some older stores)

1. Click **Create an app** and name it "twelvebit".
2. Open **Configuration → Admin API integration → Configure**. Select \`read_orders\`, \`write_script_tags\`, \`read_customers\`. Click **Save**, then **Install app**.
3. Open **API credentials**. Copy the **Admin API access token** (`shpat_…`, shown once) and the **API secret key**.
4. In twelvebit, open the site's revenue settings, choose **Shopify**, and paste the shop domain, the token (in place of the client ID) and the API secret key.

When you connect, twelvebit:

- registers the webhooks `orders/paid` and `refunds/create` first. Shopify signs them with the client secret (or the API secret key).
- keeps a ScriptTag (`https://twelvebit.app/js/script.js?id=tb_YOUR_SITE_ID&shopify=1`) that works, and never deletes it before a new one exists. Shopify refuses new script tags since 1 October 2026 and stops running them on 1 March 2027, so paste the tag with `?shopify=1` into `theme.liquid` ([The theme tag](#the-theme-tag)). When Shopify refuses the tag, the connection still works and twelvebit shows a warning.

In Shopify mode the script also:

- writes the visitor and session ids into the cart as the attributes `_tb_vid` and `_tb_sid`. Each order carries them in `note_attributes`, so the order goes to the visit that led to it.
- sends the goal `add_to_cart` when a product goes into the cart (form or AJAX) and `initiate_checkout` when the visitor clicks the checkout button.

Each paid order becomes a payment (the order total in the store currency, the first product as the plan) and a `payment` goal. Refunds subtract. Disconnect in twelvebit removes the ScriptTag and the webhooks.

---

Source: https://twelvebit.app/docs/shopify-legacy · All docs: https://twelvebit.app/llms.txt