Mapping to Stripe

This document explains what specifically is created in Stripe based on various pricing.json options.

Quick Summary

Note: nothing is created in Stripe until tier push is run. Also, everything Tier does is in test mode until tier push --live is run, which requires an additional permission step, so this is all very safe to play around with.

Plans and Features -> Products and Prices

Each plan in the pricing.json file will be used to create a subscription in Stripe. To facilitate this, each unique combination of plan and feature results in a Product and Price being created in Stripe.

Tier handles all of the details of creating these objects appropriately, so that they match the intent expressed in your pricing.json model.

For example, consider this pricing.json file:

{
  "plans": {
    "plan:name@title0": {
      "title": "This is a plan with a title",
      "features": {
        "feature:empty": {
          "title": "feature title goes here"
        }
      }
    }
  }
}

This will create a single Product in Stripe with a single Price attached.

Additional metadata is attached to each Product and Price for Tier's usage later.

Usage Pricing vs Flat Rate

When a feature has a "base" price, and no "tiers", then Tier will create the Price in Stripe as a flat rate, rather than usage-based.

For example, this feature in pricing.json will produce the following Product and Price in Stripe:

{
  "plans": {
    "plan:example@1": {
      "title": "Just an example plan to show off features",
      "features": {
        "feature:base:only": {
          "base": 1000
        }
      }
    }
  }
}

However, if "tiers" are defined, then Tier will create the appropriate Product and Price in Stripe to reflect this. For example:

{
  "plans": {
    "plan:example@1": {
      "title": "Just an example plan to show off features",
      "features": {
        "feature:graduated": {
          "tiers": [
            {
              "upto": 10
            },
            {
              "upto": 20,
              "price": 100
            },
            {
              "price": 50
            }
          ],
          "mode": "graduated"
        }
      }
    }
  }
}

Feature Limits and Overages

In Stripe, every tier-based price must include a final tier with an "upto" value of Infinity. However, Tier allows you to set a maximum amount of usage in a pricing.json file.

In order to store this in Stripe's system, Tier creates the Price using the last feature tier as unbounded, and sets the tier.limit metadata.

{
  "plans": {
    "plan:example@1": {
      "title": "Just an example plan to show off features",
      "interval": "@daily",
      "features": {
        "feature:daily": {
          "tiers": [
            {
              "base": 1,
              "upto": 10
            }
          ]
        }
      }
    }
  }
}

Note the highlighted sections above. From Stripe's point of view, the feature is effectively free for any amount of usage (after a base price of $0.01). But, the tier.limit metadata tells us that we should only allow the user to consume 10 units before considering their account to be in an overage state.