Every customer of your application is identified to tier by a string starting with 'org:'. The rest of the string can contain any arbitrary identifier that you use internally to reference the customer.

These are all valid OrgName values:

The important thing is that you can link the org to an actual user within your app, so that you always send the same OrgName for the same actual customer.

Table of Contents

Org Schedule

Each org in the system has a schedule which determines the plan that covers that org's usage, in the past and future.

For example:

$ tier fetch /api/v1/schedule?org=org:acme

  "phases": [
      "org": "org:acme",
      "plan": "plan:start@0",
      "scheduled": "2022-06-15T10:36:38.979021-07:00",
      "effective": "2022-06-15T10:36:38.958-07:00"
      "org": "org:acme",
      "plan": "plan:paid@24",
      "scheduled": "2022-06-19T10:36:38.979021-07:00",
      "effective": "2022-06-19T10:36:38.958-07:00"

Here we see two phases. The first, plan:start@0 started on 2022-06-15. Then, 4 days later, they upgrade to plan:paid@24.

You can do this programmatically in the SDK by using tier.lookupSchedule(org).

Appending Phases to Org Schedule

To append a phase to an org's schedule, use the tier.appendPhase(org:OrgName, plan:PlanName, effective?:Date) method.

To make the new phase effective immediately, simply omit the effective parameter.

The org parameter needs to be a valid org name (ie, a string starting with "org:") which you will use throughout the application to report usage for this org.

The plan parameter needs to be a valid plan identifier with both name and version, as defined in your pricing model.

You will typically want to create an initial "free" or "start" plan on user sign-up just to record that the org exists. When and if the user upgrades or changes their plan, call tier.appendPhase() again to note the change.

Example: Trials

You can use the effective date to set a user on a trial for some period of time, and then transition them to a paid plan when their trial expires. For example:

const 1day = 1000 * 60 * 60 * 24
const trialLength = 1day * 14 // 2 weeks

// here "account" is an object that we got from our
// database representing the account.  The "id" field is
// the unique identifier we use for the tier org.
// the trialPlan and paidPlan arguments come in from our
// pricing page definition.
export function paidTrial (account, trialPlan, paidPlan) {
  // put them on the free trial plan right away
  await tier.appendPhase(`org:${}`, trialPlan)
  // transition to paid plan after the trial ends
  const trialEnd = new Date( + trialLength)
  await tier.appendPhase(`org:${}`, paidPlan, trialEnd)
  // however you schedule emails is up to you.
  scheduleYourTrialIsEndingEmail(account, trialEnd)

Look Up Org Details

You can get the details about an org using the SDK by calling tier.lookupOrg(org). This will give you information about the org's billing details, if they have been set.

For example:

  "id": "org:asdf1234foobar",
  "name": "org:asdf1234foobar",
  "default_payment_method": {
    "billing_details": {
      "address": {
        "country": "US",
        "postal_code": "42424"
    "card": {
      "brand": "visa",
      "exp_month": 4,
      "exp_year": 2024,
      "last4": "4242"
  "live_mode": true,
  "url": "https:/"

Included fields: