> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promostack.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Metacode Flow

> How PromoStack ensures reliable attribution between referees and referrers

# 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

<Steps>
  <Step title="Referrer Gets Link">
    User A opens referral program in your app

    ```bash theme={null}
    POST /referrer
    {
      "uid": "userA"
    }
    ```

    Returns:

    ```json theme={null}
    {
      "referral_link": "promostack.app/r/abc123",
      "metacode": "abc123"
    }
    ```
  </Step>

  <Step title="Referee Clicks Link">
    User B clicks `promostack.app/r/abc123`

    Landing page shows:

    * "Download \[App Name]"
    * "Enter code: **ABC123** in the app"
    * Store links (iOS/Android)

    **No code assigned yet** (key difference)
  </Step>

  <Step title="Referee Redeems Metacode">
    User B installs app → enters metacode "ABC123"

    ```bash theme={null}
    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
  </Step>

  <Step title="App Store Redemption">
    User B copies code → redeems in App Store → subscribes

    RevenueCat webhook fires with `app_user_id: "userB"`

    Backend matches `codes.redeemed_by_uid = "userB"` → confirms redemption
  </Step>
</Steps>

## Key Benefits

<CardGroup cols={2}>
  <Card title="Reliable Attribution" icon="link">
    Know referee → referrer mapping **before** RevenueCat webhook
  </Card>

  <Card title="RevenueCat Independence" icon="shield">
    Webhook only confirms, doesn't create attribution
  </Card>

  <Card title="Anti-Fraud" icon="ban">
    One code per referee per campaign (checked in `/referee-redeem`)
  </Card>

  <Card title="Future-Proof" icon="rocket">
    Works with Stripe, Paddle, any payment provider
  </Card>
</CardGroup>

## Database Fields

| Field                     | Purpose                                                                  |
| ------------------------- | ------------------------------------------------------------------------ |
| `referrers.referrer_slug` | Metacode (globally unique, shown on landing page)                        |
| `codes.redeemed_by_uid`   | Referee UID (set during `/referee-redeem`, used for RevenueCat matching) |
| `codes.referrer_id`       | Referrer who gets credit                                                 |
| `referral_events`         | Tracks 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