Docsllms.txtSign inGo to your sites

Updated

View as Markdown

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: 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>
  1. Connect the store 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). 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.