Connect acquisition context to Shopify app lifecycle evidence.

This integration is for Shopify app teams that own a marketing, installation or app frontend and need one acquisition ID across referral, campaign and lifecycle reporting.

1. 01A connected Marlo workspace and selected Shopify app
2. 02Owner or admin access to create credentials
3. 03An app-owned HTTPS origin
4. 04A server-side session or database record that can retain an opaque acquisition ID
5. 05A server route that runs after authoritative Shopify or billing verification

1. 01Open Tracking in Marlo
2. 02Choose the Shopify app
3. 03Enter every exact app-owned origin that will load the script
4. 04Create the source
5. 05Copy the browser-safe marlo_pk_ public key
6. 06Open MCP and generate the private marlo_sk_ server key
7. 07Store the private key only in your server secret manager

Rotate either key if it is exposed. Rotating invalidates the previous key. Disabling a tracking source stops new events while preserving existing raw events until the retention window ends.

Add this to the Shopify app's own frontend or an app-owned marketing or installation landing page. Do not add it to merchant storefront themes.

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

The script creates a first-party opaque ID in local storage, records a page_view, and captures supported parameters: marlo_ref, UTMs, gclid, gbraid and wbraid, plus landing URL and referrer. It exposes window.marlo.track(name, properties) and window.marlo.getAcquisitionId().

Before sending a visitor into Shopify installation, copy window.marlo.getAcquisitionId() into your own signed, first-party server session. Associate it with the shop only after Shopify authentication succeeds.

1. 01Do not assume App Store or cross-domain redirects preserve query parameters
2. 02Do not put a private Marlo key in a URL or browser bundle
3. 03Do not replace Shopify OAuth state with the acquisition ID
4. 04Continue to validate Shopify HMAC plus the signed state/nonce cookie
5. 05For Shopify-managed installation, retain the ID in your app-owned session and attach it after the authenticated app opens

Shopify's authorization-code guidance requires the callback state/nonce and signed cookie to match. Marlo attribution is an adjacent application record, never a substitute for that CSRF control.

Send install, trial_started, trial_converted, paid, qualified, canceled, churned or refunded only after your server verifies the corresponding Shopify, qualification or billing event. Reuse the same event ID when retrying; Marlo deduplicates it. Commissionable paid and refunded events also include positive integer amountCents and a three-letter currency.

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

Maintained generic HTML, Shopify Remix, Next.js and direct HTTP examples live in Marlo's public repository under examples/tracking.

1. 01Load the instrumented page on an allowed origin
2. 02Open Tracking and confirm a browser page_view appears
3. 03Confirm the evidence badge says Browser
4. 04Send a test install with the same acquisition ID and a unique event ID
5. 05Refresh and confirm the event says Server and shows the expected customer reference
6. 06Open Distribution and confirm the sequential journey appears
7. 07Repeat the same event ID and confirm only one recent event remains

Use the distribution funnel methodology to interpret stage loss, source breakdowns and missing handoffs.

1. 01Origin not allowed: match scheme, host and port exactly
2. 02Tracking source unavailable: replace a rotated key or enable a new source
3. 03No page view: verify the script URL, public key and browser network request
4. 04No lifecycle event: verify team slug, private key, event name and ISO timestamp
5. 05Missing handoff: inspect your own signed session before Shopify redirect and after authenticated return
6. 06429 response: wait 60 seconds and remove accidental loops

1. 01The public key identifies one source but grants no read access
2. 02The private key can read MCP data and write ingestion events; keep it server-side
3. 03Raw tracking events are automatically deleted after 180 days
4. 04Marlo does not treat browser events as proof of payment
5. 05The script does not read merchant storefront data
6. 06Landing URLs and referrers can contain personal data; disclose the integration and avoid placing sensitive values in URLs
7. 07Browser storage, consent and advertising-click collection must match your jurisdiction and privacy policy
8. 08Cross-domain attribution is not deterministic without an app-owned handoff