Skip to navigation

Entitlement Events

Entitlement event types, what triggers each one, and the fields its payload carries
View as Markdown

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.

Availability

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.

EventDescription
entitlement.entitlements_grantedTriggered when a customer receives access time to one or more resources: when a subscription is created at checkout, when a recurring order is placed, or when a subscription is migrated. entitlement_transaction.transaction_type is initialize_credit for a new entitlement and grant_credit for an existing one.
entitlement.entitlements_expiringTriggered when an active entitlement’s expiration date is less than 7 days away. Fires again only after a grant or an expiration change makes the entitlement active again.
entitlement.entitlements_expiredTriggered when an entitlement’s expiration date passes and its grace period, if any, begins. If the entitlement has a grace period, live stays true until it ends, so don’t revoke access on this event. Without a grace period, live is already false.
entitlement.entitlements_grace_period_expiredTriggered when an entitlement’s grace period ends and the customer loses access. live is false. Also fires for entitlements without a grace period, shortly after entitlement.entitlements_expired. Revoke access on this event.
entitlement.entitlements_expiration_modifiedTriggered when an entitlement’s expiration date is changed to a future date, through the modify expiration endpoint or in RC3. The expiring and expired events then follow the new date, even if they already fired for the old one. Always carries one entitlement.
entitlement.entitlements_voidedTriggered when entitlements are voided through the void entitlements endpoint, the void subscription entitlements endpoint, or in RC3. Access ends immediately and live is false. The expired events don’t follow unless the entitlement later receives a grant or a new expiration date.
entitlement.*Matches every event in this family.

Entitlement lifecycle

A time-based entitlement moves through the events above in this order:

  1. entitlement.entitlements_granted — the customer has access until the expiration date.
  2. entitlement.entitlements_expiring — the expiration date is less than 7 days away.
  3. entitlement.entitlements_expired — the expiration date has passed, and the grace period, if any, has started.
  4. 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.

NameTypeDescriptionExample
idstrIdentifier of the event”a3f1c9e27b6d4e0f8c5a2b1d9e7f6a40”
typestrThe type of event that occurred”entitlement.entitlements_granted”
createdintUnix timestamp when the event occurred1762876800
datajsonEvent data objectSee JSON below
data.object.typestrResource type of event. Always entitlement”entitlement”
data.object.merchantstrIdentifier of the merchant”aaaa1111bbbb2222cccc”
data.object.customerstrThe merchant_user_id, the customer’s ID in the merchant’s system”h183738”
data.object.entitlementsarrayThe entitlements affected by the event. Each element has the fields belowSee JSON below
entitlements[].public_idstrPublic ID of the entitlement”5d0e2c4b8a1f4b7e9c3d6a2f1e8b7c90”
entitlements[].resource.public_idstrPublic ID of the resource the entitlement grants access to”9b8a7c6d5e4f4a3b2c1d0e9f8a7b6c5d”
entitlements[].resource.namestrName of the resource”Premium video library”
entitlements[].resource.descriptionstr or nullDescription of the resource”Unlimited 4K streaming”
entitlements[].resource.image_urlstr or nullImage URL of the resource”https://cdn.example.com/premium.png”
entitlements[].resource.external_idstr or nullThe resource’s ID in the merchant’s system”PREMIUM-VIDEO”
entitlements[].access_typestrHow access is measured. Currently always time_based”time_based”
entitlements[].livebooltrue if the customer has access when the event is created: the current time is before expiration plus grace_periodtrue
entitlements[].expirationint or nullUnix timestamp when the entitlement expires, not counting the grace period1765468800
entitlements[].grace_periodint or nullSeconds of access the customer keeps after expiration. Set by the most recent grant. Voiding sets it to 0259200
entitlements[].createdintUnix timestamp when the entitlement was created1762876800
entitlements[].last_updatedintUnix timestamp when the entitlement was last updated1762876800
entitlements[].granteesarray or nullThe grantees the entitlement belongs to, for plans that have grantees turned on. null when the entitlement has noneSee JSON below
entitlements[].grantees[].external_idstrThe grantee’s ID in the merchant’s system”member-01”
entitlements[].grantees[].namestrThe grantee’s name”Alex Smith”
entitlements[].grantees[].createdintUnix timestamp when the grantee was added to the entitlement, which is when the entitlement was created1762876800
entitlements[].grantees[].updatedintUnix timestamp when the grantee was last renamed, or when it was added if it was never renamed1762876800
entitlements[].entitlement_transaction.public_idstrPublic ID of the transaction that triggered the event”c4b3a2918f7e4d6c5b4a39281f0e7d6c”
entitlements[].entitlement_transaction.transaction_typestrWhat changed. One of initialize_credit, grant_credit, entitlement_expiring, entitlement_expired, entitlement_expired_grace_period, modify_expiration, entitlement_voided”initialize_credit”
entitlements[].entitlement_transaction.source_actionstrWhat caused the transaction. One of checkout, order-placement, subscription-migration, api-call, periodic-task”order-placement”
entitlements[].entitlement_transaction.source_objectstr or nullType of the object that caused the transaction: order, subscription, checkout_order, item, user, or subscription_migration_node. Expiration events use expiring_entitlement_event, expired_entitlement_event, or expired_grace_period_entitlement_event”order”
entitlements[].entitlement_transaction.source_object_idstr or nullID of the object that caused the transaction. For example, the order’s public ID when source_object is order”1234e74444dd115555d8bc7cccc043b0”
entitlements[].entitlement_transaction.transaction_initiation_timeintUnix timestamp when the transaction started1762876800
entitlements[].entitlement_transaction.transaction_execution_timeint or nullUnix timestamp when the transaction was applied1762876800
entitlements[].entitlement_transaction.time_amountint or nullSeconds of access the transaction granted. Set only on initialize_credit and grant_credit transactions2592000
entitlements[].entitlement_transaction.grace_periodint or nullGrace period, in seconds, that the transaction applied. null on expiration events259200
entitlements[].entitlement_transaction.grace_period_expirationint or nullUnix timestamp when the grace period ends. null on initialize_credit and grant_credit transactions; add grace_period to expiration insteadnull
Example Data
{
"id": "a3f1c9e27b6d4e0f8c5a2b1d9e7f6a40",
"type": "entitlement.entitlements_granted",
"created": 1762876800,
"data": {
"object": {
"type": "entitlement",
"merchant": "aaaa1111bbbb2222cccc",
"customer": "h183738",
"entitlements": [
{
"public_id": "5d0e2c4b8a1f4b7e9c3d6a2f1e8b7c90",
"resource": {
"public_id": "9b8a7c6d5e4f4a3b2c1d0e9f8a7b6c5d",
"name": "Premium video library",
"description": "Unlimited 4K streaming",
"image_url": "https://cdn.example.com/premium.png",
"external_id": "PREMIUM-VIDEO"
},
"grace_period": 259200,
"live": true,
"access_type": "time_based",
"expiration": 1765468800,
"created": 1762876800,
"last_updated": 1762876800,
"entitlement_transaction": {
"transaction_type": "initialize_credit",
"public_id": "c4b3a2918f7e4d6c5b4a39281f0e7d6c",
"transaction_initiation_time": 1762876800,
"transaction_execution_time": 1762876800,
"source_action": "order-placement",
"source_object": "order",
"source_object_id": "1234e74444dd115555d8bc7cccc043b0",
"time_amount": 2592000,
"grace_period": 259200,
"grace_period_expiration": null
},
"grantees": [
{
"external_id": "member-01",
"name": "Alex Smith",
"created": 1762876800,
"updated": 1762876800
},
{
"external_id": "member-02",
"name": "Jordan Smith",
"created": 1762876800,
"updated": 1762876800
}
]
}
]
}
}
}

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.