Connect Shopify

A Shopify store can send its paid orders and refunds to Clear Saga. Each order is counted as revenue and credited to the visit, source, campaign and landing page behind it. Nothing is installed in Shopify, and you hand over no password. Shopify is the one store that connects today. Other payment providers are not available yet: see what works today.

What you need #

• The Owner or Admin role in the site's workspace.
• A Shopify admin login that may open Settings and edit the theme. Any Shopify plan works.

Connect, step by step #

Open the site, then Settings, Integrations, and click Connect on the Shopify card. The dialog ticks each step off by itself.

1. Address ready. The dialog shows the address your store will send to, with a button that copies it. Until the secret is saved, Remove on the card takes it back.
2. Create two webhooks in Shopify. In your Shopify admin open Settings, Notifications, then Webhooks. Click Create webhook once per row below, pick the newest API version offered, and save:

3. Save the signing secret. The Webhooks page shows the secret your webhooks are signed with: a string of letters and numbers unique to your store. Paste it into the dialog and save. It is stored encrypted and never shown again. Until it is saved, the address refuses every delivery. This step may also come first.
4. Send a test. Open the menu of a webhook row in Shopify and choose Send test. Within seconds the dialog says it arrived. A test stores no order.
5. Put the tag with the revenue attributes on your theme. In layout/theme.liquid, replace your tag with the one the dialog prints, which carries your site key:

<script
  defer
  data-site-key="YOUR_SITE_KEY"
  data-revenue="true"
  data-shopify-cart="{{ cart.item_count }}"
  src="https://clearsaga.com/js/script.full.js"
></script>

What happens after that #

A paid order arrives within seconds of the payment. The Revenue screen shows your money, the Overview gets its revenue tiles, and campaigns show orders and revenue.

Revenue is the order's total in your store's currency, tax and shipping included, as Shopify's order total has them. An order paid in another currency is stored in the store's currency too, as in your Shopify admin.

Orders arrive and are kept while your dashboards are locked. They are not counted as events.

What is kept, and what is dropped #

Kept from an order: Shopify's id for the order, when Shopify processed it, the total and its currency, the first product's id and name, how many items there were when there is more than one, whether it is a subscription order, and the random id that links it to a visit, as a scrambled value only. Kept from a refund: its id, the order it belongs to, when, and the amount.

Dropped before anything is stored or logged: the customer's name, email, phone and addresses, the IP address and browser details, the order note, every other cart attribute, discount codes, payment details, tags, the checkout and cart tokens, and the message itself.

Only deliveries signed with your secret are accepted, and a secret can only write to the site it was saved on.

How an order finds its visit #

Once a shopper has added a first item to the cart, the tag writes a short random id into the Shopify cart, and Shopify puts it on the order. The revenue attributes set no cookie of their own. The id lives in the cart, which Shopify keeps in its own cart cookie as on every store. A shopper who only browses gets no cart from the tag. The id shows on each order in the Shopify admin under Additional details, as clearsaga_attribution_id, and names nobody.

An order's journey is the shopper's pages on the day they bought, from the page they entered on to the last page before checkout. With Remember returning visitors on and the shopper's consent, the journey also reaches earlier visits inside the lookback window. Without it, a visit from the day before is not part of the journey.

Orders that cannot be linked #

These count as revenue without credit to a page, source or campaign. The Attribution coverage card shows how many.

• Buy it now and express buttons on product pages. They skip the cart, so no id reaches the order. On a store that shows them, a fifth to a half of the orders can be unlinked. To link more, hide the dynamic checkout buttons on the product page in the theme editor, so buyers go through the cart.
• Point of sale, draft orders, subscription renewals, and orders from other sales channels or apps.
• A browser that blocked the script, or a checkout from a cart drawer right after the first add on a theme that sends no cart event.

Tests, refunds and limits to know #

• Test orders. Shopify's test delivery and orders paid through a test gateway are received and left out. To see the whole path, place a small real order and refund it.
• Refunds. A refund shows on the Refunds tile as soon as it is made, and several partial refunds add up. One that only restocks items is left out.
• Older orders. Refunds of orders placed before connecting are not shown, and older orders are not imported.
• Cancellations. A paid order that is cancelled arrives as its refund.
• Edits. An order edited after payment keeps its first total.
• Subscriptions. Renewals arrive without a visit.
• Missed deliveries. Shopify retries a failed delivery for 4 hours and then gives up. That order is not fetched later.
• One store per site. A second store needs a second site.
• Volume. A store may send 600 deliveries a minute. Beyond that Shopify is asked to retry.

If a delivery is refused #

Owners and Admins see a notice on the Shopify card and the Revenue screen until the next good delivery.

The dashboard then shows "The last delivery was refused" with one of these sentences:

• The secret does not match. A delivery at (time) did not match the signing secret. Check that the secret saved here is the one shown under Settings, Notifications, Webhooks in your Shopify admin, and replace it if it changed. Shopify stops sending after repeated failures and deletes the webhook without telling you, so after fixing the secret check that both webhooks still exist and create them again if not.
• The delivery could not be read. A delivery at (time) could not be read as an order or a refund. The connection works and nothing was lost on Shopify's side. If it keeps happening, tell us the event and the API version of the webhook.
• The order could not be stored. A delivery at (time) could not be stored and Shopify was asked to retry. If this line stays for more than 4 hours, that order was lost and Shopify may have removed the webhook: check under Settings, Notifications, Webhooks and create it again if it is gone.

If no order arrives #

Check these in order:

1. The Shopify card says Connected, not "Needs the secret".
2. Both webhooks exist in Shopify, with the address from the dialog. Shopify removes a webhook after repeated failures without telling you.
3. Send test is received. If it is refused, paste the secret again.
4. The order was paid, and was not a test order.

When the tag still sends visits and nothing has arrived for 7 days, counted from the last delivery or from the day the secret was saved, the Revenue screen says so:

Replace the secret, or disconnect #

Manage on the Shopify card shows the store, the address and the last delivery. Paste a new secret there to replace the old one: the address stays the same.

Before you disconnect, delete both webhooks in Shopify. The address stops accepting deliveries at once, and orders already recorded stay in your reports. Connecting again makes a new address.

More ways to connect are planned.

Next: Revenue, Campaigns and UTM tags, Privacy: cookieless by default