Installing the Shopify app
Install via a direct link, register the orders/create webhook, write ?ref= into cart note attributes, and fire a self-test sale. No discount code.
What the app does
The Harmonia Shopify app does 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 small script that writes
?ref=into the cart note attribute. When a shopper arrives from an athlete's 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.
This is first-party, server-side attribution: no discount code for the customer to enter, and credit holds for the attribution window even if they buy a few days later. It survives ad blockers, Safari's tracking protection, and a shopper switching browsers.
No App Store listing
This is an unlisted custom app. You install it from a direct link we send you, not from the Shopify App Store. There is no review queue and no public listing, so you can install today.
Before you install
You need:
- Admin access to the Shopify store you want to connect (you must be able to approve app permissions).
- A published program, or one ready to publish. The self-test uses your program's tracking link. See setting up a program.
Install in four steps
- Open the direct-install link. From your brand dashboard, go to Settings, then Shopify, and select Install. This opens Shopify's permission screen for the unlisted app.
- Approve the permissions. Shopify lists what the app can access. Approve to continue. We request only what attribution needs: read access to orders and the ability to register the
orders/createwebhook and inject the cart-note script. - Confirm the connection. Shopify returns you to Harmonia. The Shopify panel now shows Connected, with the store domain and the registered webhook.
- Run the self-test (next section) to confirm a sale is credited end to end.
Run the self-test
The self-test fires one test conversion through the full path: tracking link, cart note attribute, webhook, attribution match. Run it once after installing.
- Open your program's tracking link from the dashboard. Your store loads with
?ref=in the URL. - Add any item to the cart. The injected script copies the
?ref=value into the cart note attribute at this step. - Complete a test order. Use Shopify's test mode (Bogus Gateway or a $0 test product) so no real charge is made.
- Check the result in Harmonia. Within a minute, the Shopify panel marks the self-test passed and shows the matched test conversion. If it does not appear, see the troubleshooting steps below.
What a pass confirms
A passed self-test means all three links in the chain work: the script wrote the ref value, Shopify fired the orders/create webhook, and our server matched the order to the athlete. Once it passes, real sales are credited automatically.
What gets credited, and what it costs
When a real attributed sale lands, the athlete earns the commission you set, in full. 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. See setting up a program for how to choose a flat dollar amount or a flat percentage.
If the self-test does not pass
Check these in order:
- The link opened with
?ref=. The tracking link must load your store with?ref=still in the URL. If your theme strips query parameters on the landing page, the script has nothing to copy. - The cart note attribute is set. Open the test order in Shopify Admin and look at its cart note attributes. The ref value should be there. If it is missing, the injected script did not run on that page; reinstall the app to re-add it.
- The
orders/createwebhook is registered. The Shopify panel shows the webhook and its last delivery status. A failed or missing delivery means the order never reached us.
If all three look right and the self-test still fails, reinstall the app to re-add the script and run the self-test again.
FAQ
Why no discount code?
First-party, server-side attribution credits the sale from the cart note attribute, matched on our server. The customer enters nothing, so you keep full price and never train buyers to wait for a code. See attribution without discount codes.
My test sale did not show. What now?
Check three things in order: the test link opened your store with ?ref= in the URL, the order's cart note attribute shows the ref value, and the orders/create webhook is registered and returning 200. If the attribute is missing, the injected script did not run on that page; reinstall the app to re-add it, then re-run the self-test.
Does this slow my store?
No. The injected 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 orders/create webhook fires after the sale on Shopify's servers, not in the shopper's browser.