01 Read this first — the one dependency
Three of the biggest remaining items — storefront pixel, webhooks, and knowing when a store installs — all need the same thing first: the app must become a public / embedded OAuth app, not the current custom app. Build that once; it unlocks all three.
Order matters: if you build the Trackier pixel or webhooks before the OAuth app exists, there's no install event to attach them to — you'd redo the wiring. So Phase 1 = public OAuth app.
02 The phase sequence
Do them in this order. Each phase is expandable — click to see the exact tasks. GET = get from client/vendor · BUILD = we code it · CONFIG = setup step.
0Phase 0 · Present the prototype (ready now)No dependencies — demo the working app to the client today›
✓App works end-to-end — signup → approve → coupon → order sync → commission → payout → invoice.
Attribution is coupon + Shopify-order based (matches GoAffPro day-to-day).
○BUILDDemo seed data — a few affiliates, sales, payouts so the demo looks full.
○CONFIGDemo delivery — screen-share live local, or record a Loom walkthrough.
1Phase 1 · Public OAuth app (the unlock)Convert custom app → public embedded app. Enables install, pixel, webhooks.›
○GETShopify Partner account + create the app in the Partner dashboard.
○BUILDOAuth endpoints —
GET /auth (start install) + GET /auth/callback (exchange code → access token).○BUILDOn callback: upsert Merchant (shop + token) — this row is your "new install" signal.
○BUILDMulti-tenant — change
getMerchant() to resolve by the request's shop (schema already has shop @unique).○CONFIGScopes —
read_orders, write_discounts, read_products, write_script_tags.2Phase 2 · Trackier integrationThe PRD's tracking backbone (§6.2). Needs Trackier creds — see section 03.›
○GETTrackier account, API key/secret, API docs, tracking domain, campaign ID.
○BUILDTrackierService —
createPublisher · createTrackingLink · postConversion · getStats.○BUILDWire approval → create publisher, save
trackierId, generate tracking link → referralLink.○BUILDConversions → on order, post conversion to Trackier · Stats → dashboard pulls from Trackier.
3Phase 3 · Storefront pixel (auto on install)Inject tracking on every page + capture checkout — see section 04.›
○BUILDOn install, call ScriptTag API → inject
track.js on all storefront pages.○BUILDtrack.js — capture
?ref=, set cookie, send click to Trackier/API.○BUILDWeb Pixel (Customer Events) → on
checkout_completed, fire conversion.4Phase 4 · Webhooks (replace manual sync)Real-time orders, refunds, uninstall — see section 05.›
○BUILDRegister webhooks on install:
orders/paid · refunds/create · app/uninstalled.○BUILDWebhook endpoints with HMAC verification → attribute/refund automatically.
5Phase 5 · Email · PayPal · polishExternal services + PRD polish items›
○GETSendGrid/Mailgun key · BUILD real email send (replace logging).
○GETPayPal Payouts credentials · BUILD auto-payout (PRD Phase 2).
○BUILDPolish: enforce cookie-duration & conflict-resolution, performance-bonus auto-eval, signup-page templates, secure JWT auth.
6Phase 6 · Shopify App Store listingOptional — to sell it to many brands›
○BUILDBilling API (subscription pricing) · CONFIG listing, privacy policy, review submission.
03 Trackier — get & build
PRD §6.2 is explicit: "Tracking engine = Trackier API. We will NOT build a new tracking system." So Trackier is required, not optional.
What to GET from the client / Trackier
| # | Item | Why |
|---|---|---|
| 1 | Trackier account access / login | the tracking backbone |
| 2 | API key + secret | server-to-server calls |
| 3 | API documentation (base URL, endpoints, auth) | PRD: "developer needs to review Trackier's API docs" |
| 4 | Tracking domain | the domain referral links point to (records clicks) |
| 5 | Campaign / Offer ID (if already created) | to attach affiliates as publishers |
What we BUILD once creds arrive
| The 4 PRD jobs | How we wire it | Schema field (already exists) |
|---|---|---|
| Create tracking links | on approve → Trackier createPublisher + createTrackingLink | Affiliate.trackierId · referralLink |
| Record clicks | referral link → Trackier domain records click; id captured | Click.trackierClickId |
| Record conversions | on order → postConversion to Trackier | ReferralOrder |
| Pull stats | dashboard reads clicks/conversions via getStats | dashboard / analytics |
The two
trackier* columns are already in the schema as placeholders — the wiring is a focused add, not a rebuild, once the API docs are in hand.04 Pixel / storefront tracking
Goal: track on every store page automatically, without the merchant editing their theme. Two Shopify mechanisms, added automatically on install.
| Mechanism | Covers | How it's added | Note |
|---|---|---|---|
| ScriptTag API | all storefront pages | on install, POST a script_tag → Shopify injects track.js everywhere | needs scope write_script_tags |
| Web Pixel (Customer Events) | checkout / conversion | register via webPixel API on install; runs in a sandbox | only way to catch checkout_completed |
What track.js does (we build it)
- Reads the referral param (
?ref=CODE) or Trackier click-id - Sets an attribution cookie (honours the admin's cookie-duration)
- Sends the click to Trackier / our API
- On checkout (via Web Pixel) → sends the conversion
Gotchas: ScriptTag does not run on the checkout page (use the Web Pixel there). Shopify is slowly deprecating ScriptTag in favour of Theme App Embed blocks — those work too but need the merchant to toggle them on once. For zero-touch, Web Pixel + ScriptTag is the pragmatic combo today.
05 Webhooks — real-time instead of manual
Today the admin clicks "Sync orders". Webhooks make orders, refunds and uninstalls flow in automatically. Requires the public app (Phase 1) + a public HTTPS URL.
| Webhook topic | On receive, we… | Replaces |
|---|---|---|
| orders/paid | match coupon → affiliate → run commission → write ReferralOrder + credit balance | manual "Sync orders" |
| refunds/create | reverse the commission, mark order REFUNDED | manual refund (PRD 4.4) |
| app/uninstalled | mark the Merchant inactive / clean up | — |
Build steps
- On install, register the webhooks (via Admin API) pointing to your API URL
- Build webhook endpoints in NestJS — verify the HMAC signature on every request (using the app's webhook secret) so they can't be spoofed
- Process the event → the same commission / refund logic you already have, now triggered automatically
Keep the manual sync too as a safety net / backfill — webhooks can occasionally miss, and the Admin-API order pull is a reliable reconcile.
06 Email · PayPal · polish
| Item | GET | BUILD | PRD |
|---|---|---|---|
| Real email sending | SendGrid / Mailgun API key | EmailService → replace the current logging with real sends (welcome, sale, payout) | 4.9 / §6.3 |
| PayPal auto-payout | PayPal business + Payouts API creds | PayoutService → pay affiliates from the app | 4.8 (Phase 2) |
| Tracking rules | — | actually enforce cookie-duration & first/last-click conflict resolution | 4.4 |
| Performance bonus | — | auto-evaluate targets & pay the bonus | 4.5 |
| Signup templates + secure auth | — | signup-page styles; move affiliate login to JWT | 4.10 / hardening |
07 One list to send the client
Everything to request, so nothing blocks the build. Trackier items are the top priority (they gate the tracking backbone).
Trackier (tracking backbone — PRD §6.2)
- Trackier account access / login
- API key + secret
- API documentation (base URL, endpoints, auth)
- Tracking domain for referral links
- Campaign / Offer ID (if set up)
- Shopify: permission to make/install a public app on the store (or a dev store), scopes read_orders, write_discounts, read_products, write_script_tags
- Email service (SendGrid / Mailgun) API key
- PayPal Payouts credentials (Phase 2)
- Final logo, brand colours (hex), Terms & Conditions text
- Commission structure (%, tiers, product-level) + payout policy (min amount, hold time, methods)
- MVP priority — which features are needed at launch vs later