Custom Redemptions

Record or process a partner-initiated redemption for any reward you define.

Use custom redemptions to record or process a partner-initiated redemption that you procure and fulfill yourself. You supply the cardholder, the point amount, and a reason, and Rain handles the redemption recording according to your program’s points mode.

Custom redemptions are available for Rain-Managed and Partner-Managed Offchain programs. Partner-Managed Onchain programs should not use this endpoint, but may orchestrate token burns for custom redemptions directly with their users.

How a custom redemption settles depends on your points mode: Rain-Managed: The points live onchain, so Rain reserves them as a pending CUSTOM redemption and fires the raindrop_redemption.created webhook so you can prompt the cardholder to authorize the burn. The redemption then settles onchain through the same withdrawal-signature and burn-event flow as travel redemptions, moving from PENDING to PROCESSING when the burn signature is issued and to COMPLETED once the onchain burn confirms. You fulfill the reward in your own system.

Partner-Managed Offchain: Rain checks the cardholder’s offchain points balance, debits the points, and records a completed CUSTOM redemption. There is no onchain burn and no webhook. You own fulfillment, funding, and any reversal logic outside Rain’s rewards redemption flow.

How It Works

Partner-Managed Offchain

1. Cardholder requests a reward

   The cardholder requests a custom reward in your app.

2. Call the endpoint

   Call POST /issuing/raindrops/custom-redemption with the user, the point amount, and a reason.

3. Rain records the redemption

   Rain checks the cardholder’s offchain points balance, debits the points, and records a completed CUSTOM redemption.

4. You fulfill the reward

   Fulfill the reward in your own system.

Rain-Managed

1. Cardholder requests a reward

   The cardholder requests a custom reward in your app.

2. Call the endpoint

   Call POST /issuing/raindrops/custom-redemption with the user, the point amount, and a reason.

3. Rain reserves the points

   Rain checks the cardholder’s available balance, reserves a PENDING CUSTOM redemption, and fires the raindrop_redemption.created webhook.

4. Cardholder authorizes the burn

   Prompt the cardholder to authorize the burn. The redemption moves to PROCESSING when the burn signature is issued and to COMPLETED once the onchain burn confirms.

5. You fulfill the reward

   Fulfill the reward in your own system.

Rain-Managed

1. Cardholder requests a reward

   The cardholder requests a custom reward in your app.

2. Call the endpoint

   Call POST /issuing/raindrops/custom-redemption with the user, the point amount, and a reason.

3. Rain reserves the points

   Rain checks the cardholder’s available balance, reserves a PENDING CUSTOM redemption, and fires the raindrop_redemption.created webhook.

4. Cardholder signs the burn

   Prompt the cardholder to sign the burn transaction, similarly to how travel portal redemptions are actioned. The redemption moves to PROCESSING when the burn signature is issued and to COMPLETED once the onchain burn confirms.

5. You fulfill the reward

   Fulfill the reward in your own system.

Partner-Managed Offchain

1. Cardholder requests a reward

   The cardholder requests a custom reward in your app.

2. Call the endpoint

   Call POST /issuing/raindrops/custom-redemption with the user, the point amount, and a reason.

3. Rain records the redemption

   Rain checks the cardholder’s offchain points balance, debits the points, and records a completed CUSTOM redemption.

4. You fulfill the reward

   Fulfill the reward in your own system.

Request

Send the user, the point amount as a positive integer string, and a reason. Include an idempotency-key header so that retries replay the same response.

curl -X POST https://api.rain.xyz/v1/issuing/raindrops/custom-redemption \
  -H "Api-Key: YOUR_API_KEY" \
  -H "idempotency-key: <UNIQUE_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "1f2e3d4c-5b6a-7980-1234-567890abcdef",
    "raindropAmount": "100",
    "reason": "goodwill credit"
  }'

Field	Type	Description
userId	string (UUID)	The cardholder redeeming points.
raindropAmount	string	The number of points to redeem, as a positive integer string.
reason	string	Why the redemption is being made, 1–255 characters. Recorded with the redemption.

Response

A successful request returns 201. The status reflects how the redemption settles for your points mode: Partner-Managed Offchain redemptions are recorded as COMPLETED, while Rain-Managed redemptions return PENDING and settle onchain.

{
  "redemptionId": "9a8b7c6d-5e4f-3210-fedc-ba0987654321",
  "redemptionType": "CUSTOM",
  "raindropAmount": "100",
  "status": "PENDING"
}

Reusing the same idempotency-key and body replays the cached 201 response, so a retried request never double-debits the balance. The key is limited to 64 characters.

Errors

Status	Meaning
400	Invalid request, a missing or invalid idempotency-key, or insufficient points balance.
403	Raindrops are not enabled for this tenant.
404	The user was not found in this tenant.
405	The tenant’s points mode does not support custom redemptions (Partner-Managed Onchain).
409	Another offchain redemption is already in progress for this user.
503	For Rain-Managed programs, the burn-request webhook could not be sent. The reservation is released and no points are debited. Retry the request.

Billing Impact

Custom redemptions do not create a charge at redemption time. Partner-Managed Offchain redemptions carry no charge from Rain and are excluded from charge reconciliation. You own any funding or accounting for the reward you fulfill.