™2 min read
When it fires
loyalty.tier_changed is emitted when a customer moves loyalty tier. It is a change event, so data.previous carries the prior values of the changed fields.
If your endpoint does not return a 2xx within the timeout, delivery is retried on an exponential backoff schedule — see Webhook delivery and retries. Design your handler to be idempotent so a redelivered event is safe to process twice.
Example delivery
{
"id": "evt_LOYA9Z",
"type": "loyalty.tier_changed",
"created": "2026-07-05T12:00:00Z",
"livemode": true,
"api_version": "2026-07-01",
"data": {
"object": {
"id": "acct_4B8N2",
"tier": "silver",
"previous": {
"tier": "bronze"
}
}
}
}Handling it
A common handler will refresh any tier-dependent pricing or perks you show. Verify the signature, acknowledge with 200 within 10 seconds, then work asynchronously. Guard against out-of-order delivery using the created timestamp, and re-fetch the resource from the API if you need its live state.
Frequently asked questions
Can loyalty.tier_changed arrive out of order?
Yes. Webhook delivery is unordered — a retried event can arrive after a newer one. Reconcile with the created timestamp. See Handle out-of-order webhooks.
Should I act on loyalty.tier_changed alone?
Treat it as a nudge. For anything that changes money or state on your side, re-read the loyalty from the API to confirm current state before acting.
What is in data.previous?
The changed fields with their values before this event — a ready-made diff.
Funding for UK limited companies
Credicorp lends to your company, not to you personally — short-term working capital with no personal guarantee. See what your business could access.