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>"
}
'

import requests

url = "https://api.promostack.app/referee-redeem"

payload = {
    "referee_uid": "<string>",
    "metacode": "<string>",
    "platform": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({referee_uid: '<string>', metacode: '<string>', platform: '<string>'})
};

fetch('https://api.promostack.app/referee-redeem', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.promostack.app/referee-redeem",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'referee_uid' => '<string>',
    'metacode' => '<string>',
    'platform' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.promostack.app/referee-redeem"

	payload := strings.NewReader("{\n  \"referee_uid\": \"<string>\",\n  \"metacode\": \"<string>\",\n  \"platform\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.promostack.app/referee-redeem")
  .header("Content-Type", "application/json")
  .body("{\n  \"referee_uid\": \"<string>\",\n  \"metacode\": \"<string>\",\n  \"platform\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.promostack.app/referee-redeem")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"referee_uid\": \"<string>\",\n  \"metacode\": \"<string>\",\n  \"platform\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "METACODE_NOT_FOUND",
    "message": "Invalid or expired referral code. Please check and try again."
  }
}

{
  "error": {
    "code": "ALREADY_REDEEMED",
    "message": "You have already redeemed a code for this campaign"
  }
}

{
  "error": {
    "code": "CAMPAIGN_INACTIVE",
    "message": "This referral campaign is no longer active"
  }
}

{
  "error": {
    "code": "NO_CODES_AVAILABLE",
    "message": "No codes available at the moment. Please try again later."
  }
}

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>"
}
'

import requests

url = "https://api.promostack.app/referee-redeem"

payload = {
    "referee_uid": "<string>",
    "metacode": "<string>",
    "platform": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({referee_uid: '<string>', metacode: '<string>', platform: '<string>'})
};

fetch('https://api.promostack.app/referee-redeem', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.promostack.app/referee-redeem",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'referee_uid' => '<string>',
    'metacode' => '<string>',
    'platform' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.promostack.app/referee-redeem"

	payload := strings.NewReader("{\n  \"referee_uid\": \"<string>\",\n  \"metacode\": \"<string>\",\n  \"platform\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.promostack.app/referee-redeem")
  .header("Content-Type", "application/json")
  .body("{\n  \"referee_uid\": \"<string>\",\n  \"metacode\": \"<string>\",\n  \"platform\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.promostack.app/referee-redeem")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"referee_uid\": \"<string>\",\n  \"metacode\": \"<string>\",\n  \"platform\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

{
  "error": {
    "code": "METACODE_NOT_FOUND",
    "message": "Invalid or expired referral code. Please check and try again."
  }
}

{
  "error": {
    "code": "ALREADY_REDEEMED",
    "message": "You have already redeemed a code for this campaign"
  }
}

{
  "error": {
    "code": "CAMPAIGN_INACTIVE",
    "message": "This referral campaign is no longer active"
  }
}

{
  "error": {
    "code": "NO_CODES_AVAILABLE",
    "message": "No codes available at the moment. Please try again later."
  }
}

Redeem Metacode

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

Request

string

required

Unique identifier for the referee in your app (must match RevenueCat app_user_id)

string

required

The metacode entered by the user (case-insensitive)

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

string

The platform-specific promo code to redeem in App Store or Google Play

string

Platform the code is for: ios or android

string

Human-readable instructions for redeeming the code

string

Direct URL to the store redemption page

object

Information about the referrer

Show properties

string

Message to display (e.g., “Referred by John”)

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

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

Error Responses

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

{
  "error": {
    "code": "METACODE_NOT_FOUND",
    "message": "Invalid or expired referral code. Please check and try again."
  }
}

{
  "error": {
    "code": "ALREADY_REDEEMED",
    "message": "You have already redeemed a code for this campaign"
  }
}

{
  "error": {
    "code": "CAMPAIGN_INACTIVE",
    "message": "This referral campaign is no longer active"
  }
}

{
  "error": {
    "code": "NO_CODES_AVAILABLE",
    "message": "No codes available at the moment. Please try again later."
  }
}

What Happens Behind the Scenes

Validate Metacode

System finds referrer by referrer_slug matching the metacode

Anti-Fraud Check

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

Assign Code

Atomically assigns code from referee pool for specified platform

Map Attribution

Sets codes.redeemed_by_uid = referee_uid for RevenueCat matching

Create Event

Creates referral event with status code_assigned

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.

Mobile SDK

Referrer Endpoints

Referee Endpoints

Webhooks

POST /referee-redeem

Redeem Metacode

Request

Example Request

Response

Example Response

Usage in Mobile App

Error Responses

What Happens Behind the Scenes

Best Practices

Testing

​Redeem Metacode

​Request

​Example Request

​Response

​Example Response

​Usage in Mobile App

​Error Responses

​What Happens Behind the Scenes

​Best Practices

​Testing

Redeem Metacode

Request

Example Request

Response

Example Response

Usage in Mobile App

Error Responses

What Happens Behind the Scenes

Best Practices

Testing