Bulk sending

POST /v1/rewards/bulk takes an array of the same objects you'd send to POST /v1/rewards:

curl -X POST https://paybilt-rewards-api.fly.dev/v1/rewards/bulk \
  -H "Authorization: Bearer $REWARDLY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rewards": [
      { "type": "CHOICE", "valueCents": 2500, "recipient": { "email": "a@example.com", "firstName": "Ada" } },
      { "type": "CHOICE", "valueCents": 2500, "recipient": { "email": "b@example.com", "firstName": "Ben" } }
    ]
  }'

Partial-failure semantics

The response is always 207 Multi-Status with one result per input, in order:

{
  "sent": 1,
  "failed": 1,
  "results": [
    { "index": 0, "ok": true, "rewardId": "rw_abc" },
    { "index": 1, "ok": false, "error": "Insufficient wallet balance" }
  ]
}

• Items are processed in order. A validation failure on one item doesn't stop the others.
• The moment your wallet can't cover an item, processing stops: that item fails with Insufficient wallet balance and every later item is marked Skipped: insufficient balance. Nothing is rolled back — rewards already sent stay sent.

Tips

• Pre-check your balance: valueCents total vs GET /v1/wallet availableCents.
• Set externalId on every item so you can reconcile results with your own records — it's also your dedupe handle if you need to retry failures.
• The whole request validates up front: if any item is malformed (bad email, missing utid, value out of range) the entire request fails with 400 before anything is sent.