Measure the journey you can actually observe.

This workflow is for Shopify app teams with an app-owned marketing, installation or embedded page and server access to authoritative install and billing events.

1. 01A connected Marlo workspace and selected Shopify app
2. 02Owner or admin access to create a tracking source
3. 03An app-owned HTTPS origin
4. 04A signed first-party session or database record for the opaque acquisition ID
5. 05Server-side install and billing evidence
6. 06Consent and privacy disclosures appropriate to the acquisition data you collect

1. 01Open Tracking in Marlo and create an origin-restricted source for the Shopify app
2. 02Add the hosted script to the app-owned landing or installation page
3. 03Load the page and confirm a browser page_view appears in Tracking
4. 04Read window.marlo.getAcquisitionId() before redirecting to Shopify
5. 05Preserve that ID in your own signed session without changing Shopify OAuth state
6. 06After authenticated installation, send an install event with the same ID and merchant reference
7. 07Send trial_started, trial_converted or paid only after the server verifies that milestone
8. 08Open Distribution and confirm the journey links the expected stages and merchant

<script async src="https://withmarlo.app/v1/marlo.js" data-key="marlo_pk_REPLACE_WITH_YOUR_PUBLIC_KEY"></script>

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":"install_01J123456789","acquisitionId":"01J123456789ABCDEFGHJKMNPQ","name":"install","customerRef":"example-shop.myshopify.com","occurredAt":"2026-07-22T12:00:00Z"}'

The maintained generic JavaScript, Shopify Remix, Next.js and HTTP examples live under examples/tracking. The full credential and event reference is in the acquisition tracking setup guide.

1. 01Acquired: a unique opaque ID first appeared in a browser event during the 30-day cohort window
2. 02Installed: the same ID later reached an authoritative install event
3. 03Trial / paid intent: after install, the ID reached trial_started, trial_converted or paid
4. 04Paid: after install, the ID reached trial_converted or paid
5. 05Direct-paid apps use paid as both intent and paid, so a free trial is not required
6. 06Each later stage is sequential; an isolated paid event cannot inflate the funnel
7. 07Source and app tables use the same cohort rather than unrelated event totals
8. 08Country and current plan appear only after the merchant reference resolves to synced Shopify Partner data

The latest stage table links resolved journeys to the merchant profile. Current plan is not a historical claim about the plan at acquisition time. Conversion percentages describe this observed cohort, not an industry benchmark.

Marlo reads campaign evidence in a fixed order: affiliate referral ID, UTM source and medium, supported Google click identifier, external referrer, then direct or untagged. A UTM campaign is shown beside its source. These labels come from retained first-party evidence; Marlo does not guess a missing source.

1. 01Use campaign-specific UTMs on app-owned landing pages
2. 02Keep the same opaque ID across the Shopify installation handoff
3. 03Use an affiliate link when an affiliate should receive attribution
4. 04Treat direct / untagged as missing or unavailable evidence—not a channel conclusion
5. 05Compare paid outcomes and linked merchants, not visitor volume alone

1. 01Open Tracking and find the authoritative install or billing event
2. 02Copy its acquisition ID and check whether a browser event exists under the same source
3. 03Inspect your signed first-party session immediately before the Shopify redirect
4. 04Inspect the same session after the authenticated app opens
5. 05Confirm that your server event uses the browser public key and exact acquisition ID
6. 06Do not place the private key in a browser, query string or Shopify OAuth state
7. 07Retry with the same event ID if delivery failed; Marlo deduplicates it

Distribution reports lifecycle IDs without matching browser evidence as a coverage gap. They remain visible in Tracking but do not enter the cohorted funnel.

1. 01Confirm the destination matches the promise and intent of the campaign
2. 02Verify that the Install or app-opening route preserves the signed first-party acquisition record
3. 03Check Shopify authentication completion separately from an Install button click
4. 04Compare linked source cohorts without assuming a small sample is stable
5. 05Use Shopify’s own listing analytics for listing views and Install button clicks

1. 01Open the linked installed merchant profiles
2. 02Check whether onboarding reached the first useful workflow
3. 03Confirm trial_started is emitted from verified billing state
4. 04For no-trial apps, confirm paid is emitted after the charge is accepted or verified
5. 05Segment by app, country and current plan before changing onboarding for everyone

1. 01Inspect the linked merchants that have not reached paid
2. 02Confirm trial_converted or paid is emitted from authoritative billing evidence
3. 03Review plan fit, trial completion and billing friction
4. 04Keep currencies and amounts separate in payment reporting
5. 05Do not claim an acquisition source caused conversion without an experiment designed to support that inference

Marlo’s initial funnel begins on a page the app business owns. It does not see Shopify App Store listing views. Shopify documents a separate GA4 integration for listing view_item, Install-button add_to_cart, shopify_app_install and App Store ad-click events. Configure that in Partner Dashboard → Apps → your app → Distribution → Manage listing → Tracking information.

See Shopify’s current listing traffic documentation. Marlo does not ingest this GA4 stream in the initial version, and it does not claim cross-domain attribution when the app-owned handoff is missing.

1. 01No acquired visitors: verify the exact allowed origin, public key, script request and consent state
2. 02Browser event but no install: inspect the signed handoff and authoritative install trigger
3. 03Lifecycle without browser: confirm source key and acquisition ID are copied from the first-party session
4. 04Install without merchant details: use the synced myshopify.com domain, Shopify shop ID or another resolvable reference
5. 05No trial or paid intent: verify the event name and billing trigger
6. 06Event rejected: use a unique 8–100-character event ID, valid ISO time within seven days and supported event name
7. 07Report incomplete: the 5,000-event read cap was reached; use Tracking evidence and contact Marlo before making a cohort decision

1. 01The browser public key grants no read access and accepts events only from configured origins
2. 02The private marlo_sk_ key stays in a server secret manager
3. 03Landing URLs, referrers, UTMs and click IDs can be personal data; collect only what you are entitled to process
4. 04Raw tracking events are automatically deleted after 180 days
5. 05Rotate a public key after exposure and replace it on every approved origin
6. 06Rotate the private team key from MCP after exposure
7. 07Disable a tracking source to stop new browser and server events while retained history ages out
8. 08Remove the script and server calls to disconnect the integration
9. 09Manually excluded and non-commercial merchants are removed after their references resolve; anonymous visitors cannot be classified before install

1. 01The default report is a fixed 30-day acquisition cohort observed through the current day
2. 02Raw tracking evidence is limited to 180 days
3. 03Ad blockers, browser privacy controls and missing consent can reduce browser coverage
4. 04App Store listing views require Shopify’s separate GA4 stream
5. 05Cross-domain attribution depends on the app business preserving the opaque ID
6. 06Current plan is not the historical plan selected at acquisition
7. 07Country depends on a resolved synced merchant
8. 08The report is deterministic and does not estimate incrementality or causation
9. 09No email, ad, bid, budget or campaign is created from this report