Skip to main content
POST
/
referee-redeem
POST /referee-redeem
curl --request POST \
  --url https://api.promostack.app/referee-redeem \
  --header 'Content-Type: application/json' \
  --data '
{
  "referee_uid": "<string>",
  "metacode": "<string>",
  "platform": "<string>"
}
'
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid platform. Must be 'ios' or 'android'"
  }
}

​
Redeem Metacode

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

​
Request

​
referee_uid
string
required
Unique identifier for the referee in your app (must match RevenueCat app_user_id)
​
metacode
string
required
The metacode entered by the user (case-insensitive)
​
platform
string
required
Platform for the promo code: ios or android

​
Example Request

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

​
Response

​
code
string
The platform-specific promo code to redeem in App Store or Google Play
​
platform
string
Platform the code is for: ios or android
​
instructions
string
Human-readable instructions for redeeming the code
​
store_url
string
Direct URL to the store redemption page
​
referrer_info
object
Information about the referrer

​
Example Response

{
  "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

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)
}

​
Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid platform. Must be 'ios' or 'android'"
  }
}

​
What Happens Behind the Scenes

1

Validate Metacode

System finds referrer by referrer_slug matching the metacode
2

Anti-Fraud Check

Verifies referee hasn’t already redeemed a code for this campaign
3

Assign Code

Atomically assigns code from referee pool for specified platform
4

Map Attribution

Sets codes.redeemed_by_uid = referee_uid for RevenueCat matching
5

Create Event

Creates referral event with status code_assigned
6

Return Code

Returns platform-specific promo code with redemption instructions

​
Best Practices

Always use the same referee_uid that you use with RevenueCat (app_user_id)
Convert metacode to lowercase before sending to handle user input variations
Show clear instructions and a “Copy Code” button in your UI
Handle all error codes gracefully with user-friendly messages
Don’t allow users to redeem multiple codes for the same campaign - the API will reject it

​
Testing

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