Skip to main content
POST
https://api.promostack.app
/
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.