Shopify cart-attribute attribution (?ref=) | Harmonia
How Harmonia tracks Shopify affiliate sales without a discount code: a custom app writes ?ref= into the cart note attribute and matches the order server-side.
The short answer
Harmonia tracks Shopify affiliate sales without a discount code by writing a ?ref= value into the order itself. A custom Shopify app injects a small script that copies ?ref= from an athlete's tracking link into the cart note attribute, a hidden field that rides along to checkout. When the order is placed, Shopify fires an orders/create webhook to Harmonia, and we match the order to the athlete server-side. The customer enters nothing. No discount code, no third-party pixel.
This is first-party, server-side attribution: the credit lives in your own store's order data, and the match runs on our server, not in the shopper's browser.
Why this matters
Discount-code programs train buyers to wait for a code and erode your pricing. This approach keeps full price and still credits the right athlete. See affiliate attribution without codes for the wider picture.
The path, step by step
Here is the full chain, from an athlete sharing a link to a credited sale:
- A shopper clicks the athlete's tracking link. The link is per-program, one per brand relationship. It carries a
?ref=value that identifies the athlete. - The link lands on your store with
?ref=in the URL. A QR code or an anchor tag points at the same destination, so they preserve the same?ref=attribution. - The injected script captures
?ref=. The small script the app adds reads the?ref=value from the URL. - The script writes
?ref=into the cart note attribute. When the shopper adds an item, the value is copied into the order's cart note attribute, a hidden field Shopify carries through checkout. - The shopper checks out at full price. They enter no code. Nothing for them to remember, nothing to push.
- Shopify fires the
orders/createwebhook. The moment the order is placed, Shopify notifies Harmonia and sends the order, including its cart note attributes. - Harmonia matches the order server-side. We read the
?ref=value from the attribute and credit the athlete who drove the sale. This is server-side attribution: the match runs on our server.
The credit holds for the attribution window even if the shopper comes back and buys a few days later. The attribution window is set per program and is distinct from the refund window, during which a refund can reverse a commission, pro-rated.
The two things the app does
The unlisted custom app does exactly two things on your store, and nothing else:
- Registers the
orders/createwebhook. Shopify notifies Harmonia the moment an order is placed, so the sale is matched on our server, not in the shopper's browser. - Injects a script that writes
?ref=into the cart note attribute. When a shopper arrives from a tracking link, the script copies the?ref=value into the order's cart note attribute. We read that attribute server-side and credit the right athlete.
Unlisted, not in the App Store
This is an unlisted custom app. You install it from a direct link, not from the Shopify App Store. There is no review queue and no public listing, so you can install today. See installing the Shopify app for the install and self-test flow.
Why no discount code and no pixel
Most affiliate setups lean on one of two things a brand pays for: a discount code the customer types in, or a third-party pixel that tries to follow the customer's browser. Harmonia uses neither.
| Method | What it needs | What breaks it |
|---|---|---|
| Discount code | The customer enters a code | Erodes full price, trains buyers to wait for a deal |
| Third-party pixel / cookie | A tracking script the browser keeps | Ad blockers, Safari ITP, switching browsers, cleared cookies |
| Cart-attribute (Harmonia) | A ?ref= value stored in your own order | Nothing on the customer side; the value lives in Shopify's order data |
Because the ?ref= value lives in your store's own order, not in a third-party cookie or pixel, the attribution survives ad blockers and Safari's tracking protection (ITP). A shopper can switch browsers or clear cookies between the click and the purchase; the credit still lands, because it is carried in the cart note attribute and matched on our server.
What the customer sees
Nothing different. They click a link, shop, and check out at full price. There is no code field to fill in and no banner about tracking. The whole mechanism is invisible to them and lives in your order data.
The money path this drives
When a real attributed sale lands, the athlete earns the commission you set, in full. You set the commission per program, either a flat dollar amount or a flat percentage. Here is the model, in plain numbers:
| Item | Amount |
|---|---|
| Commission you set (example) | $50 per sale |
| Athlete receives | $50athlete keeps, in full |
| 20% platform fee, on top, billed to you | $10 |
| Your total cost | $60 |
The 20% platform fee is added on top and billed to you, never deducted from the athlete. The fee is charged only when an athlete drives a real attributed sale. We invoice you monthly via Stripe Billing, net-30, on the 1st of the following month: the commission your athletes earned plus the 20% platform fee. Athletes are paid from the cleared commission once your invoice clears.
Confirm it works before you trust it
You do not have to take the mechanism on faith. The Shopify install includes a self-test that fires one test conversion through the full path: tracking link, cart note attribute, webhook, attribution match. A passed self-test confirms every step in the chain works, so real sales are credited automatically after that.
The full install and self-test steps are in installing the Shopify app, and the customer-side picture is in attribution without discount codes.
Related reading
- Affiliate attribution without codes: the wider model and why it beats discount-code programs.
- Affiliate tracking without coupon codes: how the no-code approach holds up against the alternatives.
- First-party vs cookie tracking: why first-party data survives ad blockers and ITP.
FAQ
How does Harmonia track Shopify sales without a discount code?
A custom Shopify app injects a small script that writes the ?ref= value from an athlete's tracking link into the order's cart note attribute. When the order is placed, Shopify fires an orders/create webhook to Harmonia, and we match the order to the athlete server-side. The customer never enters a code, so you keep full price.
What is a cart note attribute and how does ?ref= use it?
A cart note attribute is a hidden key-value field Shopify attaches to a cart and carries through to the finished order. The injected script reads ?ref= from the URL when a shopper arrives from a tracking link and copies that value into the cart note attribute. The value rides along to checkout, so the finished order carries the athlete's ref, which we read on our server.
Do I need to be on Shopify Plus to use this?
No. Cart note attributes and the orders/create webhook are standard Shopify features available on every paid plan, not just Shopify Plus. If you can install a custom app and approve its permissions, the attribution path works.
Does the tracking script slow down my store?
No. The script reads ?ref= from the URL and copies it into the cart note attribute. It does not block the page, load product data, or run on checkout. The match happens later, on our server, when Shopify fires the orders/create webhook after the sale, not in the shopper's browser.
What does the orders/create webhook do?
It notifies Harmonia the moment an order is placed and sends us the order, including its cart note attributes. We read the ?ref= value from that attribute and credit the athlete who drove the sale. The match runs on our server, so it does not depend on the shopper's browser, cookies, or any pixel.