Take a Shopify app referral from click to commission.

1. 01Connect Shopify Partner data and select the app
2. 02Create an origin-restricted tracking source
3. 03Generate a private team API key from MCP
4. 04Choose an app-owned HTTPS landing or install page
5. 05Decide the attribution window and commission percentage
6. 06Choose a test merchant that is not controlled by the affiliate

Open Affiliates, choose the tracking source for the Shopify app, name the programme, enter an approved destination URL, then set the window and percentage. The URL origin must already be approved on the tracking source.

Enter the affiliate's name and email. Marlo blocks duplicate emails within a programme. A CSV import is not required for the initial version; add the affiliates you are actively migrating, and retain a separate export of historical records.

Create a link for the affiliate. It uses https://app.withmarlo.app/r/…, redirects only to the stored approved destination, and appends marlo_ref plus non-overriding affiliate UTMs. Do not hand-edit the destination into the public URL.

Install the script on the approved app-owned page. It stores an opaque acquisition ID and captures the referral code. Explicit browser events such as signup_started can update the visible pre-install lifecycle.

<script async src="https://withmarlo.app/v1/marlo.js" data-key="marlo_pk_REPLACE_WITH_YOUR_PUBLIC_KEY"></script>
<script>
  // Call this on your own install button before leaving your app-owned page.
  const acquisitionId = window.marlo.getAcquisitionId()
  await fetch('/start-shopify-install', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ acquisitionId })
  })
</script>

Write the acquisition ID to your own signed server session before redirecting to Shopify. After the authenticated app opens, associate that session record with the verified *.myshopify.com shop.

1. 01Do not assume the marlo_ref query parameter survives Shopify or App Store hops
2. 02Do not put the private API key in the browser or a URL
3. 03Do not replace Shopify OAuth state with the acquisition ID
4. 04Continue validating Shopify HMAC and the state/nonce cookie
5. 05Expire or consume your handoff record according to your own security policy

From your server, send an install event with the same acquisition ID and the verified shop domain as customerRef. A retry must reuse the same event ID. Marlo keeps the first attribution for the acquisition and flags repeated customer attribution rather than silently moving credit.

Send trial_started, trial_converted, paid, canceled, churned and refunded only after authoritative verification. For paid and refunded, include positive integer amountCents and a three-letter currency. Marlo applies the programme rate and writes a pending earning or signed reversal.

curl --request POST 'https://app.withmarlo.app/api/tracking/server-events' \
  --header 'Authorization: Bearer marlo_sk_REPLACE_WITH_YOUR_PRIVATE_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "teamSlug":"acme",
    "publicKey":"marlo_pk_REPLACE_WITH_YOUR_PUBLIC_KEY",
    "eventId":"payment_01J123456789",
    "acquisitionId":"01J123456789ABCDEFGHJKMNPQ",
    "name":"paid",
    "customerRef":"example-shop.myshopify.com",
    "amountCents":4900,
    "currency":"USD",
    "occurredAt":"2026-07-22T12:00:00Z"
  }'

Maintained Shopify Remix, Next.js and direct HTTP examples live under examples/tracking in the Marlo repository.

1. 01Create a test affiliate with an email unrelated to the test shop
2. 02Open its referral link in a clean browser profile
3. 03Confirm the destination contains marlo_ref
4. 04Trigger signup_started if your app exposes that step
5. 05Persist the acquisition ID in the signed install session
6. 06Complete the test install and send install
7. 07Send a paid event with a small test amount and unique event ID
8. 08Repeat the same event ID and confirm no duplicate commission appears

Open Affiliates. The merchant should show the affiliate, programme, lifecycle, original attribution time and eligibility. The paid event should create a pending commission in the correct currency. Approving it records a ledger decision and audit event; it does not send money.

Use the programme CSV action to export every earning, reversal and adjustment. Manual adjustments accept positive or negative amounts and require a reason. Approve each ledger row only after applying your own fraud, refund and payout policy.

1. 01Rotate the public key from Tracking and replace the hosted-script key
2. 02Rotate or revoke the private key from MCP
3. 03Disable a referral link to stop its redirect
4. 04Disable an affiliate or programme to stop new referrals
5. 05Keep historical attribution and ledger exports after disabling

1. 01Link returns 404: check that the link, affiliate, programme, tracking source and workspace are active
2. 02No click count: confirm traffic used the generated /r/ URL
3. 03No attribution: confirm the destination loads the script and its origin matches exactly
4. 04No merchant: inspect the signed acquisition handoff before and after Shopify authentication
5. 05Expired: confirm the first authoritative install, trial or paid event arrived inside the programme window
6. 06Possible self-referral: compare affiliate email, customer email context and shop domain
7. 07Duplicate customer: find the earlier first-touch attribution for that programme
8. 08No commission: include amountCents and currency on a server-confirmed paid event

Shopify Partner data can support downstream merchant, subscription, transaction and revenue reporting after a successful connection and sync. It does not reliably supply the original app-owned referral click or preserve an opaque ID through every installation route. Marlo therefore requires browser capture plus the app's signed handoff for attribution, and an app-server event for the exact commissionable payment amount.

1. 01First touch wins for one acquisition ID
2. 02The default recommended window is 30 days; each programme documents its actual value
3. 03An install, trial or paid event inside the window establishes eligibility
4. 04Later payment can earn commission after eligibility even if the original window has ended
5. 05An affiliate email matching customer email or shop domain is flagged as possible self-referral
6. 06A second attribution for the same merchant in one programme is blocked as a duplicate
7. 07Browser events never create commission
8. 08No automated payout occurs