Entitlement Events
These events fire when a customer’s entitlements change: when access to a resource is granted, approaches its expiration, expires, or is modified or voided. Entitlements are the ledger of the digital resources a customer can access. Digital Subscriptions explains how plans, resources, and entitlements fit together.
To receive these events, select them on a webhook route in RC3 under Developers > Webhooks, or select Entitlement events to receive every event in the family. Setting up a Webhook walks through creating a route.
Entitlement events are available only when digital subscriptions are enabled for your program. Until then, RC3 doesn’t list the Entitlement events group.
Event types
Each event is for one customer and can carry several of that customer’s entitlements.
Entitlement lifecycle
A time-based entitlement moves through the events above in this order:
entitlement.entitlements_granted— the customer has access until the expiration date.entitlement.entitlements_expiring— the expiration date is less than 7 days away.entitlement.entitlements_expired— the expiration date has passed, and the grace period, if any, has started.entitlement.entitlements_grace_period_expired— the grace period has ended, and the customer no longer has access.
Two actions make the entitlement active again, so steps 2 to 4 can repeat for its new expiration date:
- Granting more time, for example when a renewal order is placed, sends another
entitlement.entitlements_granted. - Changing the expiration date through the modify expiration endpoint sends
entitlement.entitlements_expiration_modified.
Voiding sends entitlement.entitlements_voided and ends access immediately, so steps 3 and 4 don’t follow. A voided entitlement starts the cycle again only if it’s later granted more time or given a new expiration date.
Ordergroove checks entitlement expiration dates every few minutes, so the expiring and expired events arrive shortly after the threshold passes, not at the exact second. An entitlement can also skip a step: if its expiration date passes before the next check, for example after a very short grant or a new expiration date only minutes away, entitlement.entitlements_expiring never fires and the next event is entitlement.entitlements_expired. Build your handler around live and expiration in the payload rather than assuming each event in the sequence arrives.
Payload
Unlike the other event families, one entitlement event can describe several entitlements. data.object.entitlements is an array, and each element carries the entitlement’s current state and the transaction that triggered the event.
All timestamps are Unix timestamps in seconds. All durations are in seconds.
Adding customer data
You can add the customer to an entitlement event’s payload under the route’s additional data settings in RC3. It arrives in data.snapshot.customer. Other entities aren’t available for entitlement events. Event Payloads describes the snapshot field.