> ## 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.

# POST /referee-redeem

> Redeem a metacode and get a platform-specific promo code

# Redeem Metacode

Validates a metacode and issues a platform-specific promo code to the referee. This is the core of the metacode flow.

## Request

<ParamField body="referee_uid" type="string" required>
  Unique identifier for the referee in your app (must match RevenueCat app\_user\_id)
</ParamField>

<ParamField body="metacode" type="string" required>
  The metacode entered by the user (case-insensitive)
</ParamField>

<ParamField body="platform" type="string" required>
  Platform for the promo code: `ios` or `android`
</ParamField>

### Example Request

```bash theme={null}
curl -X POST https://api.promostack.app/referee-redeem \
  -H "Content-Type: application/json" \
  -d '{
    "referee_uid": "user_456",
    "metacode": "abc123",
    "platform": "ios"
  }'
```

## Response

<ResponseField name="code" type="string">
  The platform-specific promo code to redeem in App Store or Google Play
</ResponseField>

<ResponseField name="platform" type="string">
  Platform the code is for: `ios` or `android`
</ResponseField>

<ResponseField name="instructions" type="string">
  Human-readable instructions for redeeming the code
</ResponseField>

<ResponseField name="store_url" type="string">
  Direct URL to the store redemption page
</ResponseField>

<ResponseField name="referrer_info" type="object">
  Information about the referrer

  <Expandable title="properties">
    <ResponseField name="message" type="string">
      Message to display (e.g., "Referred by John")
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "code": "LOGI-IOS-XYZ789",
  "platform": "ios",
  "instructions": "Copy this code and redeem it in the App Store under your account settings",
  "store_url": "https://apps.apple.com/account/redeem",
  "referrer_info": {
    "message": "Referred by abc123"
  }
}
```

## Usage in Mobile App

<CodeGroup>
  ```swift iOS theme={null}
  func redeemMetacode(userId: String, metacode: String) async throws -> RedeemResponse {
      let url = URL(string: "https://yejzycmzbcwjsapmkwrq.supabase.co/functions/v1/referee-redeem")!
      var request = URLRequest(url: url)
      request.httpMethod = "POST"
      request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
      request.setValue("application/json", forHTTPHeaderField: "Content-Type")
      
      let body = [
          "referee_uid": userId,
          "metacode": metacode.lowercased(),
          "platform": "ios"
      ]
      request.httpBody = try JSONEncoder().encode(body)
      
      let (data, _) = try await URLSession.shared.data(for: request)
      return try JSONDecoder().decode(RedeemResponse.self, from: data)
  }

  // Show code with copy button
  func showPromoCode(_ response: RedeemResponse) {
      let alert = UIAlertController(
          title: "Your Promo Code",
          message: "\(response.code)\n\n\(response.instructions)",
          preferredStyle: .alert
      )
      
      alert.addAction(UIAlertAction(title: "Copy Code", style: .default) { _ in
          UIPasteboard.general.string = response.code
          // Open store URL
          UIApplication.shared.open(URL(string: response.store_url)!)
      })
      
      present(alert, animated: true)
  }
  ```

  ```kotlin Android theme={null}
  suspend fun redeemMetacode(userId: String, metacode: String): RedeemResponse {
      val client = OkHttpClient()
      val json = JSONObject()
          .put("referee_uid", userId)
          .put("metacode", metacode.lowercase())
          .put("platform", "android")
      
      val request = Request.Builder()
          .url("https://yejzycmzbcwjsapmkwrq.supabase.co/functions/v1/referee-redeem")
          .post(json.toString().toRequestBody("application/json".toMediaType()))
          .addHeader("x-api-key", apiKey)
          .build()
      
      val response = client.newCall(request).execute()
      return Gson().fromJson(response.body?.string(), RedeemResponse::class.java)
  }

  // Show code with copy button
  fun showPromoCode(response: RedeemResponse) {
      AlertDialog.Builder(context)
          .setTitle("Your Promo Code")
          .setMessage("${response.code}\n\n${response.instructions}")
          .setPositiveButton("Copy & Redeem") { _, _ ->
              val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
              clipboard.setPrimaryClip(ClipData.newPlainText("Promo Code", response.code))
              
              // Open Play Store
              startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(response.store_url)))
          }
          .show()
  }
  ```
</CodeGroup>

## Error Responses

<ResponseExample>
  ```json 400 Validation Error theme={null}
  {
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Invalid platform. Must be 'ios' or 'android'"
    }
  }
  ```

  ```json 404 Metacode Not Found theme={null}
  {
    "error": {
      "code": "METACODE_NOT_FOUND",
      "message": "Invalid or expired referral code. Please check and try again."
    }
  }
  ```

  ```json 409 Already Redeemed theme={null}
  {
    "error": {
      "code": "ALREADY_REDEEMED",
      "message": "You have already redeemed a code for this campaign"
    }
  }
  ```

  ```json 409 Campaign Inactive theme={null}
  {
    "error": {
      "code": "CAMPAIGN_INACTIVE",
      "message": "This referral campaign is no longer active"
    }
  }
  ```

  ```json 503 No Codes Available theme={null}
  {
    "error": {
      "code": "NO_CODES_AVAILABLE",
      "message": "No codes available at the moment. Please try again later."
    }
  }
  ```
</ResponseExample>

## What Happens Behind the Scenes

<Steps>
  <Step title="Validate Metacode">
    System finds referrer by `referrer_slug` matching the metacode
  </Step>

  <Step title="Anti-Fraud Check">
    Verifies referee hasn't already redeemed a code for this campaign
  </Step>

  <Step title="Assign Code">
    Atomically assigns code from referee pool for specified platform
  </Step>

  <Step title="Map Attribution">
    Sets `codes.redeemed_by_uid = referee_uid` for RevenueCat matching
  </Step>

  <Step title="Create Event">
    Creates referral event with status `code_assigned`
  </Step>

  <Step title="Return Code">
    Returns platform-specific promo code with redemption instructions
  </Step>
</Steps>

## Best Practices

<Check>
  Always use the same `referee_uid` that you use with RevenueCat (app\_user\_id)
</Check>

<Check>
  Convert metacode to lowercase before sending to handle user input variations
</Check>

<Check>
  Show clear instructions and a "Copy Code" button in your UI
</Check>

<Check>
  Handle all error codes gracefully with user-friendly messages
</Check>

<Warning>
  Don't allow users to redeem multiple codes for the same campaign - the API will reject it
</Warning>

## Testing

Use the test metacode `test123` in development to verify your integration without consuming real codes.