Skip to main content

​
Metacode Flow Architecture

PromoStack uses a metacode system to enable reliable referee → referrer attribution without depending on RevenueCat webhook accuracy.

​
The Problem

Traditional referral systems face attribution challenges:
  • RevenueCat webhooks don’t always include full promo code details
  • Direct code assignment on landing pages creates attribution gaps
  • No way to verify who referred whom before payment confirmation

​
The Solution: Metacodes

A metacode is a PromoStack-generated identifier (the referrer_slug) that a referee enters in your app to receive a platform-specific promo code.

​
Complete Flow

1

Referrer Gets Link

User A opens referral program in your app
POST /referrer
{
  "uid": "userA"
}
Returns:
{
  "referral_link": "promostack.app/r/abc123",
  "metacode": "abc123"
}
2

Referee Clicks Link

User B clicks promostack.app/r/abc123Landing page shows:
  • “Download [App Name]”
  • “Enter code: ABC123 in the app”
  • Store links (iOS/Android)
No code assigned yet (key difference)
3

Referee Redeems Metacode

User B installs app → enters metacode “ABC123”
POST /referee-redeem
{
  "referee_uid": "userB",
  "metacode": "abc123",
  "platform": "ios"
}
Backend:
  • Validates metacode
  • Checks anti-fraud (userB hasn’t redeemed already)
  • Assigns code from referee pool
  • Sets codes.redeemed_by_uid = "userB" (critical!)
Returns iOS/Android code
4

App Store Redemption

User B copies code → redeems in App Store → subscribesRevenueCat webhook fires with app_user_id: "userB"Backend matches codes.redeemed_by_uid = "userB" → confirms redemption

​
Key Benefits

Reliable Attribution

Know referee → referrer mapping before RevenueCat webhook

RevenueCat Independence

Webhook only confirms, doesn’t create attribution

Anti-Fraud

One code per referee per campaign (checked in /referee-redeem)

Future-Proof

Works with Stripe, Paddle, any payment provider

​
Database Fields

FieldPurpose
referrers.referrer_slugMetacode (globally unique, shown on landing page)
codes.redeemed_by_uidReferee UID (set during /referee-redeem, used for RevenueCat matching)
codes.referrer_idReferrer who gets credit
referral_eventsTracks full lifecycle (clicked → code_assigned → redeemed)

​
Why This Works

  1. Attribution happens early - We know who referred whom when they redeem the metacode
  2. RevenueCat is just confirmation - The webhook confirms what we already know
  3. No dependency on webhook accuracy - Even if RevenueCat doesn’t send full code details, we match by app_user_id
  4. Universal - Same flow works for iOS, Android, web subscriptions, any payment provider