Enabling Team Subscriptions with RevenueCat

  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.

  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.

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

1. A managing user purchases a one-to-many subscription with RevenueCat in your mobile apps or website.
2. RevenueCat processes the purchase, assigns the managing user an entitlement, and dispatches an INITIAL_PURCHASE webhook to your backend.
3. 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

1. A managing user decides to add a receiving user to their subscription through your app or website.
2. Your backend grants the receiving user a lifetime promotional entitlement in RevenueCat with the Grant a Promotional Entitlement endpoint.
3. 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

1. A managing user decides to remove a receiving user from their subscription through your app or website.

2. Your backend revokes the receiving user’s lifetime promotional entitlement in RevenueCat with the Revoke Promotional Entitlements endpoint.

3. 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

1. A managing user cancels their one-to-many subscription.
2. Some time passes and the subscription expires (depending on whether you have a grace period configured). RevenueCat processes the cancellation and expiration and:
   1. Removes the entitlement from the managing user
   2. Dispatches an EXPIRATION webhook to your backend
3. Your backend receives the EXPIRATION webhook and:
   1. Revokes the entitlements for all receiving users in RevenueCat using the Revoke Promotional Entitlements endpoint.
   2. Removes all receiving users from the managing user’s subscription in your database.
   3. 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.

• iOS
• Stripe
• REST API
• Webhooks