Skip to main content
POST
/
referrer-claim
POST /referrer-claim
curl --request POST \
  --url https://api.promostack.app/referrer-claim \
  --header 'Content-Type: application/json' \
  --data '
{
  "uid": "<string>"
}
'
{
  "error": {
    "code": "NO_REWARDS_AVAILABLE",
    "message": "No rewards available to claim"
  }
}

​
Claim Rewards

Claims all available rewards for a referrer. Returns platform-specific promo codes that the referrer can redeem.

​
Request

​
uid
string
required
Unique identifier for the referrer (same as used in /referrer)

​
Example Request

curl -X POST https://api.promostack.app/referrer-claim \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "user_123"
  }'

​
Response

​
message
string
Success message indicating number of rewards claimed
​
claimed_rewards
array
Array of claimed reward codes

​
Example Response

{
  "message": "Successfully claimed 1 reward",
  "claimed_rewards": [
    {
      "reward_id": "660e8400-e29b-41d4-a716-446655440000",
      "platform": "ios",
      "code": "LOGI-REWARD-ABC123",
      "reward_number": 1,
      "instructions": "Copy this code and redeem in App Store",
      "store_url": "https://apps.apple.com/account/redeem"
    }
  ]
}

​
Usage in Mobile App

func claimRewards(userId: String) async throws -> ClaimResponse {
    let url = URL(string: "https://yejzycmzbcwjsapmkwrq.supabase.co/functions/v1/referrer-claim")!
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    request.setValue(apiKey, forHTTPHeaderField: "x-api-key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    
    let body = ["uid": userId]
    request.httpBody = try JSONEncoder().encode(body)
    
    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONDecoder().decode(ClaimResponse.self, from: data)
}

// Display claimed rewards
func showClaimedRewards(_ response: ClaimResponse) {
    let alert = UIAlertController(
        title: "🎉 Rewards Claimed!",
        message: response.message,
        preferredStyle: .alert
    )
    
    for reward in response.claimed_rewards {
        alert.addAction(UIAlertAction(title: "Copy \(reward.code)", style: .default) { _ in
            UIPasteboard.general.string = reward.code
            UIApplication.shared.open(URL(string: reward.store_url)!)
        })
    }
    
    alert.addAction(UIAlertAction(title: "Done", style: .cancel))
    present(alert, animated: true)
}

​
Error Responses

{
  "error": {
    "code": "NO_REWARDS_AVAILABLE",
    "message": "No rewards available to claim"
  }
}

​
When to Call This Endpoint

1

Check Progress First

Call /referrer to see if rewards are available
2

Show Claim Button

If rewards_earned > 0, show a “Claim Rewards” button
3

Claim on User Action

Call /referrer-claim when user taps the button
4

Display Codes

Show all claimed codes with copy buttons

​
Best Practices

Only show “Claim Rewards” button when rewards are actually available
Display all claimed codes clearly with copy buttons
Provide direct links to App Store/Play Store redemption pages
Show celebration UI (confetti, animation) when rewards are claimed
Don’t auto-claim rewards - let users explicitly claim them for better UX

​
Multiple Rewards

If a referrer has earned multiple rewards (e.g., reached 5 referrals twice), the response will include multiple codes: 
{
  "message": "Successfully claimed 2 rewards",
  "claimed_rewards": [
    {
      "reward_id": "...",
      "platform": "ios",
      "code": "LOGI-REWARD-ABC123",
      "reward_number": 1,
      ...
    },
    {
      "reward_id": "...",
      "platform": "ios",
      "code": "LOGI-REWARD-XYZ789",
      "reward_number": 2,
      ...
    }
  ]
}
Display all codes and allow users to copy each one individually.