Overview
Itâs common for developers to offer subscriptions that unlock entitlements for more than one user at a time. This is usually seen in B2B business models where one person (an administrator) can purchase multiple licenses for a product and then distribute those licenses to workers within their company.
While the app stores donât support this behavior out of the box, this article explores how developers can implement such a subscription model with RevenueCat.
Â
 Definitions
-
One-to-Many Subscription: A subscription purchased by one user that unlocks entitlements for one or more distinct users.
-
Managing User: The user who purchases and manages a one-to-many subscription.
-
Receiving User: A user who receives an entitlement from a one-to-many subscription.
![](https://uploads-us-west-2.insided.com/revenuecat-en/attachment/e4228139-8774-494c-9913-d6c91495970b.png)
Â
 Prerequisites
- You have non-anonymous user IDs for all users involved in a one-to-many subscription (i.e., the managing and receiving users).
- You are using RevenueCat as the source of truth for entitlements in your apps.
- You have a backend capable of receiving webhooks and storing the relationships between managing and receiving users.
Â
â
 Technical Details
  Purchasing a One-to-Many Subscription
For the first half of this implementation, weâll treat our one-to-many subscription as we would any other subscription in RevenueCat.
First, configure the subscriptionâs product in the RevenueCat dashboard. When you create the productâs entitlement, name the entitlement in a way that marks that it allows the user to manage the subscription, like b2b_pro_product_manager
. This will be our management entitlement, which helps us identify which users can edit the list of receiving users for our one-to-many subscription.
Next, we need to allow the managing user to purchase our subscription. Proceed with the standard implementation path for purchasing subscriptions with RevenueCat through mobile IAPs or web. Be sure to identify your users when they sign in!
Â
 Unlocking Entitlements for Receiving Users
Â
This section discusses items that will need to be done in your backend. We wonât dig into exactly how to accomplish these items since the exact details will vary for each implementation, but the ideas are the same regardless of your tech stack.
Â
When a managing user purchases a one-to-many subscription, your backend will receive an INITIAL_PURCHASE
 webhook from RevenueCat. This webhook will contain both the managing userâs ID and the product ID of the product they purchased. When you receive an INITIAL_PURCHASE
 webhook for a one-to-many subscriptionâs product ID, youâll want to update your database to show that the managing user can grant entitlements to the number of users the product unlocks.
When the managing user decides to add a receiving user to their subscription, youâll want to check the following before granting access:
- Is the number of receiving users associated with this one-to-many subscription less than the number of allowed users for this subscription?
- Is this new user already granted entitlements from this subscription?
If the answer to both of these questions is no, youâll grant this user a promotional entitlement using our Grant a Promotional Entitlement REST API for the features unlocked by the subscription.
If you donât need your receiving users to be able to see when their subscription will renew/expire next, the most straightforward approach is to grant a lifetime promotional entitlement that doesnât expire. Suppose you need to show the renewal/expiration date to the receiving user. In that case, youâll set the promotional entitlementâs duration equal to the duration of the one-to-many subscription. Then, grant the promotional entitlement again each time you receive a RENEWAL webhook for the one-to-many subscription.
Â
Receiving Users Need to See Renewal/Expiration Date? | Promotional Entitlement Duration | Notes |
---|---|---|
No | Lifetime | Most straight-forward approach |
Yes | Equal to One-to-Many Subscription Duration | Requires your backend to re-grant the promotional entitlement each time the one-to-many subscription renews |
Â
Once your backend grants the user the entitlement, add the receiving user to a list in your database for the managing userâs subscription.
Â
 Revoking Entitlements
There are two scenarios where youâd want to revoke a receiving userâs entitlements:
- The managing user cancels their one-to-many subscription.
- Either the managing or receiving user removes a receiving user from the subscription.
RevenueCat will notify your backend of a managing user canceling their subscription by an EXPIRATION
 webhook. In the second case, where only one user is removed, your app will need to send that event to your backend.
In either case, when this happens, your backend will need to reach out to our Revoke Promotional Entitlements endpoint to revoke the entitlements from the appropriate users. If you chain these calls to revoke entitlements from multiple users, we recommend placing a 0.5-second delay between API calls to avoid rate limiting. Once the entitlements have been revoked from the appropriate users, your backend should remove those users from the list of users associated with the subscription in your database.
Â
 End to End Flows
Purchasing a One-to-Many Subscription
- A managing user purchases a one-to-many subscription with RevenueCat in your mobile apps or website.
- RevenueCat processes the purchase, assigns the managing user an entitlement, and dispatches anÂ
INITIAL_PURCHASE
 webhook to your backend. - Your backend receives theÂ
INITIAL_PURCHASE
 webhook and designates a set number of receiving users to which the managing user can assign entitlements in your database.
Granting Entitlements to Receiving Users
- A managing user decides to add a receiving user to their subscription through your app or website.
- Your backend grants the receiving user a lifetime promotional entitlement in RevenueCat with the Grant a Promotional Entitlement endpoint.
- Your backend adds the receiving user to your database's list of users associated with the managing userâs subscription.
Revoking Entitlements for a Single Receiving User
- A managing user decides to remove a receiving user from their subscription through your app or website.
-
Your backend revokes the receiving userâs lifetime promotional entitlement in RevenueCat with the Revoke Promotional Entitlements endpoint.
- Your backend removes the receiving user from your database's list of users associated with the managing userâs subscription.
Handling an Expired One-to-Many Subscription
- A managing user cancels their one-to-many subscription.
- Some time passes and the subscription expires (depending on whether you have a grace period configured). RevenueCat processes the cancellation and expiration and:
- Removes the entitlement from the managing user
- Dispatches anÂ
EXPIRATION
 webhook to your backend
- Your backend receives theÂ
EXPIRATION
 webhook and:- Revokes the entitlements for all receiving users in RevenueCat using the Revoke Promotional Entitlements endpoint.
- Removes all receiving users from the managing userâs subscription in your database.
- Sets the number of receiving users that a managing user can grant access to to 0 in your database.
Â
 Considerations
- Since RevenueCat does not count users with only promotional entitlements as âactive subscribersâ, the receiving users will not be accounted for in the âActive Subscribersâ chart.
- Since RevenueCat will be tracking a one-to-many subscription as a single subscription, events will only be dispatched to third-party integrations for the managing user.
- The receiving users will appear in your ETL exports each time a promotional entitlement is granted. TheÂ
store
 field will be set toÂpromotional
 and no revenue will be associated with those users. - Any integrations will only fire for the one âownerâ subscription renewals, and come through as non-subscription purchases for the promotional purchases.
- If the INITIAL_PURCHASE webhook is missed for some reason things will get out-of-sync.