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

# Grantees

A grantee is someone or something that receives access through a customer's plan subscription: a child, a pet, a device, or a location. The customer pays for and manages the subscription, and the grantees are who the access is for. Each grantee has an `external_id`, its ID in your system, and a `name`.

Use grantees when one customer account manages access for several distinct entities. The Account Hierarchy examples in [Digital Subscriptions](/advanced/digital-subscriptions) show which setups need them.

---

## Turning on grantees for a plan

In RC3, open the plan and turn on **Grantees**, then set **Max grantees per subscription**. Every subscription to the plan must then include at least one grantee and no more than that maximum. A plan can allow up to 50 grantees per subscription.

Decide before you launch the plan. RC3 doesn't let you turn grantees off again, and the setting becomes read-only once the plan has subscriptions.

A plan that doesn't have grantees turned on rejects subscriptions that include them.

---

## Sending grantees

Grantees are set when a subscription is created:

* **[Purchase POST](/reference/payment-api/payment-requests/purchase-post-api):** send them in each product's `purchase_info.grantees` array, as objects with `external_id` and `name`. If one product's grantees are invalid, for example missing or more than the plan allows, Ordergroove doesn't create that product's subscription and returns the reason under `errors.grantees` in the response. The other products in the request are still processed. If the same `external_id` appears twice in one product's list, the last entry is used.
* **Migration:** add a `grantees` array to each subscription. See [Migrating Digital Subscriptions](/advanced/migrating-digital).

A grantee belongs to one customer. Sending an `external_id` that another customer already uses is rejected. Sending one that this customer already has reuses the existing grantee and keeps its current name. To change a name, [rename the grantee](#renaming-a-grantee).

---

## One subscription and one entitlement per grantee set

Ordergroove tells a customer's subscriptions to the same plan apart by their grantees. By default, when a new subscription arrives with exactly the same grantees as an existing subscription to that plan, Ordergroove updates the existing subscription, and reactivates it if needed, instead of creating a second one. A different set of grantees creates a separate subscription. Grantees are matched by `external_id`; their order and names don't matter.

Entitlements follow the same rule. A customer has one entitlement per resource and set of grantees, and each renewal extends only the entitlement for its own subscription's grantees. For example, if a parent has one subscription for each of two children, each child has a separate entitlement to the same resource, with its own expiration date.

---

## Renaming a grantee

Change a grantee's name with the [rename grantee endpoint](/reference/rest-rpc-api/customers/rename-grantee). The new name reaches the customer's entitlements shortly afterward. Renaming doesn't trigger an [entitlement webhook event](/data/entitlement-events). A grantee's `external_id` can't be changed.

---

## Finding grantees and their entitlements

* The [subscription endpoints](/reference/rest-rpc-api/subscriptions/retrieve) return a `grantees` array for subscriptions that have grantees.
* [List entitlements](/reference/entitlements-service-api/entitlements/list) filters by grantees with `has_grantees` and `grantee_external_ids_exact`.
* [Entitlement webhook events](/data/entitlement-events) include each entitlement's `grantees`.
* In RC3, a customer's details page shows the grantees on each plan subscription, and you can search the customer's entitlements by grantee name or ID.

---

## Voiding entitlements

The [void subscription entitlements endpoint](/reference/rest-rpc-api/subscriptions/void-entitlements) voids only the entitlements for the subscription's own grantees. By default it skips one when another of the customer's live subscriptions grants the same resource to exactly the same grantees. A live subscription for different grantees doesn't count as sharing, because its grantees hold a separate entitlement.