Subscription

Subscription documents contains information that states what features/products are available for a specific facility. Only one Subscription can be associated to a facility.

Statuses

The status of the subscription.

• trialing. when on trial
• active. subscription is active
• incomplete. the initial payment attempt fails
• incomplete_expired. terminal state, the open invoice will be voided and no further invoices will be generated
• canceled. cancelled by user
• past_due. when payment to renew it fails
• unpaid. when payment to renew it fails and has exhausted all payment retry attempts
• paused. when a trial subscription expires and no payment method is available

Notes

• if no status or status is incomplete, all features are on the base mode/value
• if status is past_due and unpaid, all features will be read-only
• if status is canceled or incomplete_expired, subscription cannot be reactivated and must be recreated again

Packages

SubscriptionPackage documents are a set of templates/overrides that can be applied/used/associated in a Subscription so as to modify the base behavior/allowed toggles

Usage Examples

# fetch list of packages for a particular facility
# and display them as choices to the user
GET /subscription/packages?type=facility&types=doctor

# signup user with a particular package
POST /accounts
{
  email: 'test@domain.com',
  password: 'strongpassword',
  // ...other details
  organization: {
    name: 'My facility',
    type: 'facility',
    types: ['doctor'],
    // ...other details
    subscription: {
      package: '<selected-package-id>',
      // ...other details
    }
  }
}

# fetch list of packages for a particular facility
# and display them as choices to the user
GET /subscription/packages?type=facility&types=doctor

# signup user with a particular package
POST /accounts
{
  email: 'test@domain.com',
  password: 'strongpassword',
  // ...other details
  organization: {
    name: 'My facility',
    type: 'facility',
    types: ['doctor'],
    // ...other details
    subscription: {
      package: '<selected-package-id>',
      // ...other details
    }
  }
}

Creation Examples/Use-cases

# fetch list of packages for a particular facility
# and display them as choices to the user
GET /subscription/packages?type=facility&types=doctor

# create a facility with a subscription with a specific
# package while creating an account
POST /accounts
{
  email: 'test@domain.com',
  password: 'strongpassword',
  // ...other details
  organization: {
    name: 'My facility',
    type: 'facility',
    types: ['doctor'],
    // ...other details
    subscription: {
      package: '<selected-package-id>',
      // ...other details
    }
  }
}

# when the package used in the subscription requires payment,
# it will initially have the status of `pending` that will only
# be active after a successful checkout w/c can be done by
# following the stripe checkout flow using the returned
# `Subscription.checkoutSession`

# fetch list of packages for a particular facility
# and display them as choices to the user
GET /subscription/packages?type=facility&types=doctor

# create a facility with a subscription with a specific
# package while creating an account
POST /accounts
{
  email: 'test@domain.com',
  password: 'strongpassword',
  // ...other details
  organization: {
    name: 'My facility',
    type: 'facility',
    types: ['doctor'],
    // ...other details
    subscription: {
      package: '<selected-package-id>',
      // ...other details
    }
  }
}

# when the package used in the subscription requires payment,
# it will initially have the status of `pending` that will only
# be active after a successful checkout w/c can be done by
# following the stripe checkout flow using the returned
# `Subscription.checkoutSession`

Activating a subscription

Newly created subscriptions will have the status pending which should be checked by apps before allowing users to access the majority of features. In order to "activate" the subscription, either the application admins will manually update the status of subscription or the user must follow the checkout flow.

Checkout flow

When subscriptions have the pending status, the system will generate a Subscription.checkoutSession.url where the user should be redirected. After the checkout process is finished (which will vary depending on the configured provider but will mostly involve inputing payment method) the subscription will be updated with the new requested updates.

Changing Subscription Packages

# fetch list of packages for a particular facility
# and display them as choices to the user
GET /subscription/packages?type=facility&types=doctor

# update an existing subscription's package
PATCH /subscriptions/<subscription-id>
{
  package: <SubscriptionPackage.id>
}

# if there is an existing subscription, it will be
# used thus no checkout session is needed, else
# same as in creating a subscription with a paid
# package, it will contain a `Subscription.checkoutSession`
# field that can be used to continue the checkout flow

# fetch list of packages for a particular facility
# and display them as choices to the user
GET /subscription/packages?type=facility&types=doctor

# update an existing subscription's package
PATCH /subscriptions/<subscription-id>
{
  package: <SubscriptionPackage.id>
}

# if there is an existing subscription, it will be
# used thus no checkout session is needed, else
# same as in creating a subscription with a paid
# package, it will contain a `Subscription.checkoutSession`
# field that can be used to continue the checkout flow

Upgrading subscription items/modules

In order to upgrade individual items (instead of upgrading the package), one can patch the subscription directly (if the current package permits it) which would trigger another checkout flow before the changes applies.

# enable LIS feature
PATCH /subscriptions/<subscription-id>
{
  lis: true
}

# enable LIS feature
PATCH /subscriptions/<subscription-id>
{
  lis: true
}

The changes requested will be collected under the Subscription.updatesPending object and will not directly enable them (Subscription.lis will still be false). This will also populate Subscription.checkoutSession where the checkout flow should be followed.