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:

1. 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)
2. Navigate to Stripe Dashboard
3. Click the account switcher in the upper left corner and click New account
4. Enter an account name and click Create account
5. 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

:

1. Open the UserHub Admin console
   Admin console

   A management interface for your UserHub tenants.
   
   This is where your team can provision, manage, and monitor accounts, seats, subscriptions, plans, and more.
   and navigate to Connections via Developers dropdown or Tenant settings
2. Click Setup for Stripe
3. Select Test mode and click Connect
4. You'll be redirected to the Stripe connect page
5. Select the account you just created
6. 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.

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
  Organization

  A group account which can activate subscriptions and have members.
  changes, including when an organization is created, updated, or deleted. It is also triggered when the subscription
  Subscription

  An activated plan which is associated with an account.
  associated with the organization state changes (trialing, active, past due, canceled, etc.) or when the subscription plan
  Plan

  A set of billing rules for a subscription, including products, prices, currency, and billing cycle.
  changes.
• users.changed: is triggered when a user
  User

  An individual account which can activate subscriptions and be a member of an organization.
  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
  Event

  A representation of some type of interesting occurrence in UserHub (e.g. user.changed).
  was created. We recommend always getting the latest version from the Admin API
  Admin API

  A management API that allows admins of a tenant to manage accounts, subscriptions, and other tenant resources. You can think of this as the API version of the Admin console.
  
  See also the User 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
  Product

  A packaged collection of entitlements you offer your customers (e.g. Basic plan or Pro seat).
  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
  Member

  A user that is part of an organization with a given role.
  event
  Event

  A representation of some type of interesting occurrence in UserHub (e.g. user.changed).
  will be triggered whenever a user is added or removed from an organization, or when their role
  Role

  A named collection of permissions that specify what a user is allowed to do within an organization.
  
  You can think of UserHub roles as a billing role. There is no expectation that you use them in your application.
  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
  Member

  A user that is part of an organization with a given role.
  event
  Event

  A representation of some type of interesting occurrence in UserHub (e.g. user.changed).
  will also be triggered when a subscription associated with a user's membership changes or when the seat
  Seat

  A license that can be assigned to members of an organization. It is represented as a product in UserHub.
  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