Entitlement Event Object
| Name | Type | Description | Example | |
|---|---|---|---|---|
| id | str | Identifier of the event | "zzzz1111yyyy2222xxxx" | |
| type | str | The type of event that occurred | "entitlement.entitlements_granted"" | |
| created | int | Unix timestamp when the event occurred | 1758652772 | |
| data | object | Event payload | See JSON below | |
| data.object.type | str | Resource type of event object | "entitlement" | |
| data.object.merchant | str | Identifier of merchant | "519f1f120e3411ef984b1e8a267ce85a" | |
| data.object.entitlements | array | List of entitlement objects | [{...}, {...}] | |
| data.object.entitlements[].public_id | str | Public identifier of the entitlement | "dee489eb3c6f419dbd65fb99f33c60f5" | |
| data.object.entitlements[].access_type | str | Access type for the entitlement \nOptions: "time_based" | "time_based" | |
| data.object.entitlements[].created | int | Unix timestamp when the entitlement was created | 1755841156 | |
| data.object.entitlements[].last_updated | int | Unix timestamp when the entitlement was last updated | 1758652772 | |
| data.object.entitlements[].expiration | int | Unix timestamp when the entitlement expires | 1763701794 | |
| data.object.entitlements[].grace_period | int | Grace period (seconds) after expiration during which access may continue | 345600 | |
| data.object.entitlements[].live | bool | Indicates whether the resource associated with this entitlement can be accessed. If the expiration date has passed but the grace period is still in effect, this field will be true. | true | |
| data.object.entitlements[].entitlement_transaction | object | Details of the transaction that granted or modified the entitlement | { ... } | |
| data.object.entitlements[].entitlement_transaction.public_id | str | Public identifier of the transaction | "1f3650bb2d75463e8b71b61f38289c9c" | |
| data.object.entitlements[].entitlement_transaction.transaction_type | str | Transaction type \nOptions: "grant_credit" | "grant_credit" | |
| data.object.entitlements[].entitlement_transaction.source_action | str | Originating action in merchant workflow | "order-placement" | |
| data.object.entitlements[].entitlement_transaction.source_object | str | Type of object that initiated the transaction | "item" | |
| data.object.entitlements[].entitlement_transaction.source_object_id | str | Identifier of the source object | "169719f6110d40b2b157381924f95bf9" | |
| data.object.entitlements[].entitlement_transaction.transaction_initiation_time | int | Unix timestamp when the transaction was initiated | 1758652772 | |
| data.object.entitlements[].entitlement_transaction.transaction_execution_time | int | Unix timestamp when the transaction executed | 1758652772 | |
| data.object.entitlements[].entitlement_transaction.time_amount | int | Amount of time credited (seconds) | 1296000 | |
| data.object.entitlements[].entitlement_transaction.grace_period | int | Transaction-level grace period (seconds), if applicable | 345600 | |
| data.object.entitlements[].resource | object | Resource to which the entitlement applies | { ... } | |
| data.object.entitlements[].resource.public_id | str | Public identifier of the resource | "8bc97390ff944451a8e4bee89bf18473" | |
| data.object.entitlements[].resource.name | str | Resource display name | "Test Resource 2" | |
| data.object.entitlements[].resource.description | str | Resource description | "Test Description 2" | |
| data.object.entitlements[].resource.external_id | str | External identifier of the resource in merchant system | "654321" | |
| data.object.entitlements[].resource.image_url | str \ | null | Image URL for the resource, if any | null |
| data.object.context | object \ | null | Optional context specific to the event | null |
| data.object.snapshot | object | Arbitrary snapshot data at time of event | {} |
- Example data:
{
"id":"5dcc6524c8b3491aba893dbc33282fe9",
"type":"entitlement.entitlements_granted",
"created":1758652772,
"data":{
"object":{
"customer":"9621785248035",
"entitlements":[
{
"access_type":"time_based",
"created":1753215926,
"entitlement_transaction":{
"grace_period":86400,
"public_id":"a6ac2b763b4c45db9b3cb4f2e43fa2bb",
"source_action":"order-placement",
"source_object":"item",
"source_object_id":"169719f6110d40b2b157381924f95bf9",
"time_amount":2592000,
"transaction_execution_time":1758652772,
"transaction_initiation_time":1758652772,
"transaction_type":"grant_credit"
},
"expiration":4098185509,
"grace_period":86400,
"live": true,
"last_updated":1758652772,
"public_id":"36a82fb6bb9549e0877058b2eb8644ad",
"resource":{
"description":"Test Description 1",
"external_id":"123456",
"image_url":"http://example.com/resource1.jpg",
"name":"Test Resource 1",
"public_id":"c84a13fc8e904e0f80e6377b15f0464a"
}
},
{
"access_type":"time_based",
"created":1755841156,
"entitlement_transaction":{
"grace_period":345600,
"public_id":"1f3650bb2d75463e8b71b61f38289c9c",
"source_action":"order-placement",
"source_object":"item",
"source_object_id":"169719f6110d40b2b157381924f95bf9",
"time_amount":1296000,
"transaction_execution_time":1758652772,
"transaction_initiation_time":1758652772,
"transaction_type":"grant_credit"
},
"expiration":1759942309,
"grace_period":345600,
"live": false,
"last_updated":1758652772,
"public_id":"dee489eb3c6f419dbd65fb99f33c60f5",
"resource":{
"description":"Test Description 2",
"external_id":"654321",
"image_url":null,
"name":"Test Resource 2",
"public_id":"8bc97390ff944451a8e4bee89bf18473"
}
}
],
"merchant":"519f1f120e3411ef984b1e8a267ce85a",
"type":"entitlement"
},
"context":null,
"snapshot":{
}
}
}Entitlement Event Types
-
entitlement.entitlements_expiring
-
entitlement.entitlements_expired
-
entitlement.entitlements_granted
-
entitlement.entitlements_grace_period_expired
Triggered when an entitlement is approaching expiration. These events fire one week prior to the expiration date whenever possible. If the entitlement lifetime is shorter than one week, the event fires as late as possible (for example: created with 6 days of access → event fires 6 days before expiration). Multiple entitlements with matching conditions are clustered together in a single event.
Triggered when an entitlement has reached its expiration time. If an entitlement includes a grace period, the customer continues to have access until that grace period ends, at which point the entitlement.entitlements_grace_period_expired event will be triggered. Multiple entitlements that expire at the same time are clustered together in a single event.
Triggered when a customer has been granted one or more entitlements. If multiple entitlements are granted for a customer at the same time, they are clustered together in a single event.
Triggered when an entitlement has reached the end of its configured grace period. Multiple entitlements whose grace period expire at the same time are clustered together in a single event.