> ## 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 /referrer-claim

> Claim available rewards

# Claim Rewards

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

## Request

<ParamField body="uid" type="string" required>
  Unique identifier for the referrer (same as used in `/referrer`)
</ParamField>

### Example Request

```bash theme={null}
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

<ResponseField name="message" type="string">
  Success message indicating number of rewards claimed
</ResponseField>

<ResponseField name="claimed_rewards" type="array">
  Array of claimed reward codes

  <Expandable title="properties">
    <ResponseField name="reward_id" type="string">
      Unique identifier for the reward
    </ResponseField>

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

    <ResponseField name="code" type="string">
      The promo code to redeem
    </ResponseField>

    <ResponseField name="reward_number" type="number">
      Sequential reward number (1st reward, 2nd reward, etc.)
    </ResponseField>

    <ResponseField name="instructions" type="string">
      How to redeem the code
    </ResponseField>

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

### Example Response

```json theme={null}
{
  "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

<CodeGroup>
  ```swift iOS theme={null}
  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)
  }
  ```

  ```kotlin Android theme={null}
  suspend fun claimRewards(userId: String): ClaimResponse {
      val client = OkHttpClient()
      val json = JSONObject().put("uid", userId)
      
      val request = Request.Builder()
          .url("https://yejzycmzbcwjsapmkwrq.supabase.co/functions/v1/referrer-claim")
          .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(), ClaimResponse::class.java)
  }

  // Display claimed rewards
  fun showClaimedRewards(response: ClaimResponse) {
      val dialog = AlertDialog.Builder(context)
          .setTitle("🎉 Rewards Claimed!")
          .setMessage(response.message)
      
      response.claimed_rewards.forEach { reward ->
          dialog.setPositiveButton("Copy ${reward.code}") { _, _ ->
              val clipboard = getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
              clipboard.setPrimaryClip(ClipData.newPlainText("Reward Code", reward.code))
              startActivity(Intent(Intent.ACTION_VIEW, Uri.parse(reward.store_url)))
          }
      }
      
      dialog.show()
  }
  ```
</CodeGroup>

## Error Responses

<ResponseExample>
  ```json 404 No Rewards Available theme={null}
  {
    "error": {
      "code": "NO_REWARDS_AVAILABLE",
      "message": "No rewards available to claim"
    }
  }
  ```

  ```json 404 Referrer Not Found theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Referrer not found"
    }
  }
  ```
</ResponseExample>

## When to Call This Endpoint

<Steps>
  <Step title="Check Progress First">
    Call `/referrer` to see if rewards are available
  </Step>

  <Step title="Show Claim Button">
    If `rewards_earned > 0`, show a "Claim Rewards" button
  </Step>

  <Step title="Claim on User Action">
    Call `/referrer-claim` when user taps the button
  </Step>

  <Step title="Display Codes">
    Show all claimed codes with copy buttons
  </Step>
</Steps>

## Best Practices

<Check>
  Only show "Claim Rewards" button when rewards are actually available
</Check>

<Check>
  Display all claimed codes clearly with copy buttons
</Check>

<Check>
  Provide direct links to App Store/Play Store redemption pages
</Check>

<Check>
  Show celebration UI (confetti, animation) when rewards are claimed
</Check>

<Warning>
  Don't auto-claim rewards - let users explicitly claim them for better UX
</Warning>

## Multiple Rewards

If a referrer has earned multiple rewards (e.g., reached 5 referrals twice), the response will include multiple codes:

```json theme={null}
{
  "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.