Getting started

Create tenant

UserHub tenants are a logically isolated sets of users, organizations, and plans.

The first step in getting started with UserHub is to create a new tenant.

For this guide, we recommend creating a Development mode tenant under your individual account. This will give you a low-risk place to get acquainted with UserHub and experiment.

Connect your Stripe account

UserHub enhances Stripe Billing to support advanced plan features including seat management and plan versioning.

You'll need to connect a new or existing Stripe account enable these features.

For this guide, we recommend you create a dedicated test Stripe account:

Sign up for a Stripe account if you don't already have one (you don't need to do any of the activation steps, you only need a test account)
Navigate to Stripe Dashboard
Click the account switcher in the upper left corner and click New account
Enter an account name and click Create account
You only need Test mode for this guide, so you can safely ignore the activation and other onboarding messaging

Next, connect Stripe to your tenant:

Open the UserHub Admin console and navigate to Connections via Developers dropdown or Tenant settings
Click Setup for Stripe
Select Test mode and click Connect
You'll be redirected to the Stripe connect page
Select the account you just created
Click Skip this form at the top of the page

Your Stripe account should now be connected to your tenant.

Enable user syncing

UserHub uses the users in your app or third-party identity provider to identify your individual customers. Once connected, users will automatically be kept in sync using a webhook or directly through a supported identity provider API.

Follow the instructions below to connect a user provider and return to this guide when done.

Custom users (webhook-based)
Auth0
Firebase Authentication (Identity Platform)

Implement Portal callback

The UserHub Portal is a customer-facing billing page which allows users to manage their plan, invite teammates, view invoices, and pay their bill. The Portal callback allows users to sign in to the Portal using a custom redirect in your app.

Follow the instructions on callback handler page to implement the redirect in your app and return to this guide when done.

Finish onboarding

Complete any remaining steps in the onboarding checklist (removed once completed).

Listen for account changes

In order to keep your app in sync with your customer's accounts, you'll need to set up webhooks to handle events from UserHub.

The two most important events to handle are:

organizations.changed: is triggered when an organization changes, including when an organization is created, updated, or deleted. It is also triggered when the subscription associated with the organization state changes (trialing, active, past due, canceled, etc.) or when the subscription plan changes.
users.changed: is triggered when a user changes, including when a user is created, updated, or deleted. It is also triggered when a user's individual subscription changes or when the user's memberships change.

Follow the instructions in the Webhooks Getting Started guide to start handling events. You should also set up your app with the ability to make requests to the Admin API.

How you handle these events will depend on how your user and organization data is modeled in your database, but we'll list some best practices and hints below:

Get the latest data: the webhook payload is always a snapshot of the objects at the time the event was created. We recommend always getting the latest version from the Admin API before updating your database.
Make your handlers idempotent: you should make your webhook handlers idempotent. After getting the latest data from the API, compare it against what's in your database. Merge data as needed and lazily create missing dependencies.
Get the subscription state from the account object: the organization and user objects will include the subscription property if they have an active subscription. Use its presence to update the state of the account in your database.
Use a product's unique ID to map entitlements: you can save a product's unique ID (e.g. pro-plan) to your database and use it to determine which features the account is entitled to use.

members.changed specific handling:

Handle membership changes: the member event will be triggered whenever a user is added or removed from an organization, or when their role changes. Compare the member object to the state of your database and update as needed.
Handle seat changes: similar to account-level subscription changes, the member event will also be triggered when a subscription associated with a user's membership changes or when the seat assigned to the member changes.

Important organization properties:

organization.subscription: present when the organization has an active subscription
organization.subscription.state: the current state of the organization subscription (trialing, active, past due, etc.)
organization.subscription.plan.product.uniqueId: a developer-defined identifier which can be used to map organization-level entitlements

Important user properties:

user.subscription: present when the user has an active individual subscription
user.subscription.state: the current state of the individual subscription (trialing, active, past due, etc.)
user.subscription.plan.product.uniqueId: a developer-defined identifier which can be used to map user-level entitlements
user.memberships: list of the user's memberships
user.memberships[*].role: the user's role within the organization (e.g. owner, admin, etc.)
user.memberships[*].seat: present when the user has a seat assigned in the organization
user.memberships[*].seat.product.uniqueId: developer-defined identifier which can be used to map seat-level entitlements
user.memberships[*].organization.subscription: present when the organization has an active subscription