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 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: send them in each product’s
purchase_info.granteesarray, as objects withexternal_idandname. 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 undererrors.granteesin the response. The other products in the request are still processed. If the sameexternal_idappears twice in one product’s list, the last entry is used. - Migration: add a
granteesarray to each subscription. See Migrating Digital Subscriptions.
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.
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. The new name reaches the customer’s entitlements shortly afterward. Renaming doesn’t trigger an entitlement webhook event. A grantee’s external_id can’t be changed.
Finding grantees and their entitlements
- The subscription endpoints return a
granteesarray for subscriptions that have grantees. - List entitlements filters by grantees with
has_granteesandgrantee_external_ids_exact. - Entitlement webhook 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 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.