> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.ordergroove.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.ordergroove.com/_mcp/server.

# 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](/advanced/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](/data/setting-up-webhooks) 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.

| Event                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entitlement.entitlements_granted`              | Triggered 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_expiring`             | Triggered 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_expired`              | Triggered 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_expired` | Triggered 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_modified`  | Triggered when an entitlement's expiration date is changed to a future date, through the [modify expiration endpoint](/reference/entitlements-service-api/entitlements/post-entitlements-modify-expiration) 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_voided`               | Triggered when entitlements are voided through the [void entitlements endpoint](/reference/entitlements-service-api/entitlements/post-entitlements-void), the [void subscription entitlements endpoint](/reference/rest-rpc-api/subscriptions/void-entitlements), 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](/reference/entitlements-service-api/entitlements/post-entitlements-modify-expiration) 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.

| Name                                                                 | Type          | Description                                                                                                                                                                                                                                                               | Example                                                                      |
| :------------------------------------------------------------------- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------- |
| `id`                                                                 | str           | Identifier of the event                                                                                                                                                                                                                                                   | "a3f1c9e27b6d4e0f8c5a2b1d9e7f6a40"                                           |
| `type`                                                               | str           | The type of event that occurred                                                                                                                                                                                                                                           | "entitlement.entitlements_granted"                                           |
| `created`                                                            | int           | Unix timestamp when the event occurred                                                                                                                                                                                                                                    | 1762876800                                                                   |
| `data`                                                               | json          | Event data object                                                                                                                                                                                                                                                         | See JSON below                                                               |
| `data.object.type`                                                   | str           | Resource type of event. Always `entitlement`                                                                                                                                                                                                                              | "entitlement"                                                                |
| `data.object.merchant`                                               | str           | Identifier of the merchant                                                                                                                                                                                                                                                | "aaaa1111bbbb2222cccc"                                                       |
| `data.object.customer`                                               | str           | The `merchant_user_id`, the customer's ID in the merchant's system                                                                                                                                                                                                        | "h183738"                                                                    |
| `data.object.entitlements`                                           | array         | The entitlements affected by the event. Each element has the fields below                                                                                                                                                                                                 | See JSON below                                                               |
| `entitlements[].public_id`                                           | str           | Public ID of the entitlement                                                                                                                                                                                                                                              | "5d0e2c4b8a1f4b7e9c3d6a2f1e8b7c90"                                           |
| `entitlements[].resource.public_id`                                  | str           | Public ID of the resource the entitlement grants access to                                                                                                                                                                                                                | "9b8a7c6d5e4f4a3b2c1d0e9f8a7b6c5d"                                           |
| `entitlements[].resource.name`                                       | str           | Name of the resource                                                                                                                                                                                                                                                      | "Premium video library"                                                      |
| `entitlements[].resource.description`                                | str or null   | Description of the resource                                                                                                                                                                                                                                               | "Unlimited 4K streaming"                                                     |
| `entitlements[].resource.image_url`                                  | str or null   | Image URL of the resource                                                                                                                                                                                                                                                 | "[https://cdn.example.com/premium.png](https://cdn.example.com/premium.png)" |
| `entitlements[].resource.external_id`                                | str or null   | The resource's ID in the merchant's system                                                                                                                                                                                                                                | "PREMIUM-VIDEO"                                                              |
| `entitlements[].access_type`                                         | str           | How access is measured. Currently always `time_based`                                                                                                                                                                                                                     | "time_based"                                                                 |
| `entitlements[].live`                                                | bool          | `true` if the customer has access when the event is created: the current time is before `expiration` plus `grace_period`                                                                                                                                                  | true                                                                         |
| `entitlements[].expiration`                                          | int or null   | Unix timestamp when the entitlement expires, not counting the grace period                                                                                                                                                                                                | 1765468800                                                                   |
| `entitlements[].grace_period`                                        | int or null   | Seconds of access the customer keeps after `expiration`. Set by the most recent grant. Voiding sets it to `0`                                                                                                                                                             | 259200                                                                       |
| `entitlements[].created`                                             | int           | Unix timestamp when the entitlement was created                                                                                                                                                                                                                           | 1762876800                                                                   |
| `entitlements[].last_updated`                                        | int           | Unix timestamp when the entitlement was last updated                                                                                                                                                                                                                      | 1762876800                                                                   |
| `entitlements[].grantees`                                            | array or null | The [grantees](/advanced/grantees) the entitlement belongs to, for plans that have grantees turned on. `null` when the entitlement has none                                                                                                                               | See JSON below                                                               |
| `entitlements[].grantees[].external_id`                              | str           | The grantee's ID in the merchant's system                                                                                                                                                                                                                                 | "member-01"                                                                  |
| `entitlements[].grantees[].name`                                     | str           | The grantee's name                                                                                                                                                                                                                                                        | "Alex Smith"                                                                 |
| `entitlements[].grantees[].created`                                  | int           | Unix timestamp when the grantee was added to the entitlement, which is when the entitlement was created                                                                                                                                                                   | 1762876800                                                                   |
| `entitlements[].grantees[].updated`                                  | int           | Unix timestamp when the grantee was last renamed, or when it was added if it was never renamed                                                                                                                                                                            | 1762876800                                                                   |
| `entitlements[].entitlement_transaction.public_id`                   | str           | Public ID of the transaction that triggered the event                                                                                                                                                                                                                     | "c4b3a2918f7e4d6c5b4a39281f0e7d6c"                                           |
| `entitlements[].entitlement_transaction.transaction_type`            | str           | What 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_action`               | str           | What caused the transaction. One of `checkout`, `order-placement`, `subscription-migration`, `api-call`, `periodic-task`                                                                                                                                                  | "order-placement"                                                            |
| `entitlements[].entitlement_transaction.source_object`               | str or null   | Type 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_id`            | str or null   | ID 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_time` | int           | Unix timestamp when the transaction started                                                                                                                                                                                                                               | 1762876800                                                                   |
| `entitlements[].entitlement_transaction.transaction_execution_time`  | int or null   | Unix timestamp when the transaction was applied                                                                                                                                                                                                                           | 1762876800                                                                   |
| `entitlements[].entitlement_transaction.time_amount`                 | int or null   | Seconds of access the transaction granted. Set only on `initialize_credit` and `grant_credit` transactions                                                                                                                                                                | 2592000                                                                      |
| `entitlements[].entitlement_transaction.grace_period`                | int or null   | Grace period, in seconds, that the transaction applied. `null` on expiration events                                                                                                                                                                                       | 259200                                                                       |
| `entitlements[].entitlement_transaction.grace_period_expiration`     | int or null   | Unix timestamp when the grace period ends. `null` on `initialize_credit` and `grant_credit` transactions; add `grace_period` to `expiration` instead                                                                                                                      | null                                                                         |

**`Example Data`**

```json title="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](/data/event-payloads) describes the `snapshot` field.