> For the complete documentation index, see [llms.txt](https://docs.billingjs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.billingjs.com/guides/shared-subscriptions.md).

# Shared subscriptions

Shared subscription are supported using metadata on Stripe products and customers

{% hint style="warning" %}
For your app to support shared subscriptions **you will have to implement the customer and subscriptions webhooks**. [**Configure them here**](/getting-started/configure-webhooks-and-triggers.md)**.**
{% endhint %}

{% content-ref url="/pages/AMxQZEqJkydjbqNI4HP4" %}
[Configure Webhooks and Triggers](/getting-started/configure-webhooks-and-triggers.md)
{% endcontent-ref %}

### Shared subscription products

To make a product support shared subscription add on the product page the following metadata:

`billing_supports_shared_subscriptions` = `true`

You can see your list of active products on the [Stripe dashboard](https://dashboard.stripe.com/products?active=true).

This will ensure that users who subscribed to this product will be able to add/remove users to their subscriptions from their customer portal. They will be able to set users as managers of the shared subscription too.

{% hint style="info" %}
Check that the metadata `billing_supports_shared_subscriptions`does not contain any trailing whitespace as Stripe does not sanitize the metadata
{% endhint %}

### Shared subscription owners

{% hint style="info" %}
This is automatically set when the customer is using the [Customer Portal](/components/customer-portal.md)

These instructions are only here to help you set up a shared subscription **manually** from the [Stripe dashboard](https://dashboard.stripe.com/dashboard)
{% endhint %}

A shared subscription always has an owner that can manage it from his customer portal

To **manually** set a Stripe customer as the owner of the subscription, add the following metadata to the **subscription** from the Stripe Dashboard 

`billing_shared_subscription_owner` = `cus_***`

where `cus_***` is the customer id of the owner

The UI will look like this in the Customer Portal for subscripiton owners

<figure><img src="/files/kX9lIfQtt7KYKP0ytRQl" alt=""><figcaption></figcaption></figure>

With the ability to manage the users in their shared subscription by assigning and removing licenses

<figure><img src="/files/uABKitvwzvxdO1zge3Bo" alt="" width="563"><figcaption></figcaption></figure>

### Shared subscription user/manager

{% hint style="info" %}
This is automatically set when the customer is using the [Customer Portal](/components/customer-portal.md)

These instructions are only here to help you add a user to an existing shared subscription **manually** from the [Stripe dashboard](https://dashboard.stripe.com/dashboard)

The owner of the shared subscription doesn't need this metadata
{% endhint %}

To **manually** set a Stripe customer as a user/manager of a shared subscription, add the following metadata to the **customer who is sharing the subscription** (not the owner) from the Stripe Dashboard&#x20;

`billing_shared_subscription_role` = `user` or `manager`

{% hint style="info" %}
A `manager` can add/remove users from the shared subscription just like the owner. There can be only one owner for a shared subscription.

A `user` can't edit the subscription
{% endhint %}

`billing_shared_subscription_id` = `sub_***`

Where `sub_***` is the subscription id of the shared subscription.

This will ensure that the customer is on the shared subscription and this will consume one license from the shared subscription plan.

{% hint style="warning" %}
Please note that if you add more users to a shared subscription than the number of licenses on the subscription, the subscription won't be updated accordingly and the owner won't be charged more. You will have to update the shared subscription manually.
{% endhint %}

Shared subscription users will see their current subscription as well as a button to contact their plan's owner

<figure><img src="/files/UpGLH8LeKHCashl8GXKJ" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.billingjs.com/guides/shared-subscriptions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.