recipient.expired

Triggered when the recipient's entitlement passed its expires_at deadline with balance still unspent. Terminal, so no further events fire for this recipient.

🚧
This is the event you cannot afford to drop
remaining_amount was never spent and the entitlement is now gone. If you debited your end user when the payout was created, this is your only signal to credit them back.
Before this event existed, a lapsed entitlement notified nobody. Merchants were never told, and their end users were quietly owed.

Body

The GIFQ envelope plus the wallet balance. subject_type is "recipient" and status is "expired".

remaining_amount is the amount that lapsed. It can be less than initial_amount if the recipient partially redeemed first.

Example

£50 of £75 lapsed:

{
  "event": "recipient.expired",
  "payout_order_uuid": "11111111-2222-3333-4444-555555555555",
  "recipient_email": "[email protected]",
  "recipient_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "recipient_name": "Alice Doe",
  "subject_type": "recipient",
  "status": "expired",
  "updated_at": "2026-08-20T09:00:01Z",
  "payout_type": "gift_cards",
  "initial_amount": 75.0,
  "remaining_amount": 50.0,
  "currency": "GBP",
  "sent_at": "2026-05-20T09:00:00Z",
  "viewed_at": "2026-05-21T10:00:00Z",
  "expires_at": "2026-08-20T09:00:00Z"
}

A recipient who never opened their link has viewed_at: null and remaining_amount equal to initial_amount.

What to do on receipt

Credit remaining_amount back to your end user if you debited them up front. Nothing else will tell you to.
Close the recipient out. No further events fire, and the balance cannot be recovered.
Do not confuse this with payout.expired, which is one crypto send lapsing while the recipient stays redeemable. This event is the entitlement itself ending.

📘
Expiry arrives in bursts
Recipients on one order usually share an expiry window, so a single sweep can enqueue a delivery for every recipient at once, up to the per-order recipient limit.
We cap deliveries at 5 per second per account and delay rather than drop the excess, so a large burst arrives spread over time and out of order. Sort on updated_at, and size this handler for the burst rather than the average.