Shopify attribution
Connect a Shopify store so paid orders can credit the affiliates who drove them. Start with discount codes because that released path needs no theme edit.
Connect your store
Open Shopify in the dashboard. Enter the canonical lowercase `.myshopify.com` address, meaning Shopify's official permanent store address written in lowercase. Select Connect Shopify, then complete Shopify OAuth, the permission screen where the merchant authorizes Attribloom to read the store events it needs.
Shopify sends signed `ORDERS_PAID` and `REFUNDS_CREATE` webhooks. These are paid-order and refund notifications with an HMAC signature, a cryptographic check that lets Attribloom reject tampered messages.
Path 1 (no code): affiliate discount codes
Approve an affiliate, open their detail page in Attribloom, and copy their referral code. Create a Shopify discount with that exact code and give it to the affiliate. This requires zero storefront code and no `theme.liquid` edit.
When a shopper uses the code, Shopify includes it in the paid order. Attribloom treats it as a validated discount code: a Shopify checkout code that exactly matches an affiliate referral code already recorded in Attribloom. Shopify's paid-order webhook carries the code, so the theme does not need to record anything.
Path 2 (optional, more reach): link attribution
Use this path to credit visits when the shopper does not enter a discount code. This needs a developer or an AI assistant. The storefront landing URL must already contain `?ref=<affiliate referral code>`, and the theme must write that value to the cart attribute named `ref`.
Add the copyable recipe at `/guides/shopify.md` to `theme.liquid`, Shopify's main theme layout file, before `</body>`. The recipe writes a Cart AJAX attribute, extra cart metadata set through Shopify's cart API. Shopify copies it to a note attribute, an extra key-value field saved on the paid order.
The Attribloom `/r/<code>` redirect does not append `?ref=`. Do not assume the signed tracking link alone activates this path. Use a landing URL that already contains the parameter.
Conflicting signals and refunds
If a validated discount code and a `ref` note attribute identify different affiliates, Attribloom fails closed: it leaves the order unattributed instead of risking credit to the wrong person.
When a credited order is refunded, the matching commission is reversed automatically on the double-entry ledger, a balanced accounting record where every money movement has an equal opposite entry.
Confirm each path
For Path 1, place a paid test order using the affiliate's exact Shopify discount code. No theme change is part of this test. For Path 2, visit a store URL containing `?ref=<affiliate referral code>`, confirm the cart has the `ref` attribute, and place a paid test order. Check that Attribloom Conversions credits the expected affiliate, then refund the order and confirm the matching commission reversal.