Skip to content

Metered levers

Metered levers (Also known as usage-based, consumption-based, or pay-as-you-go pricing) track usage and set limits on the metered resources of your product according to customers' subscription plans. In Planship, metered levers define the usage that's tracked and how it's aggregated, and entitlements limit that usage on specific plans.

Example

Imagine a product that offers subscription plans priced according to monthly API call volume. It offers up to 1, 2, and 5 million API calls per month on "Free," "Personal," and "Business" plans respectively. To accomplish this with Planship, you'd define a metered lever named api-call that aggregates the total reported usage over a subscription period of one month, and then create entitlements on each plan that specifies the desired api-call limit (1 million on Free, 2 million on Personal, and 5 million on Business).

Pay-as-you-go

If you simply want to meter usage and don't need to enforce any sort of limiting on the usage, you can do so by defining a metered lever with a default limit of -1 (infinite) and reporting usage without defining explicit entitlements.

Usage reporting

In order for usage to be tracked and aggregated, it has to be reported to Planship via the API. A single usage-report API call carries information about the customer, the amount of usage, and the metering ID that identifies the product resource being consumed. It results in the creation of a single, traceable metering record.

Usage buckets

Usage buckets allow grouping of usage within a single metering ID. Bucket names are specified when reporting usage to Planship via the API, and bucket-name tracking enables more complex usage aggregation scenarios.

Example

Suppose you have a product that allows customers to create projects. Within these projects, they can make API calls, which are limited by their plan. While API calls are aggregated across all projects, it may be useful to also track these API calls by the project that generated them. In this case, you'd report usage along with a bucket name corresponding to the project that generated it.

Creating a lever

When creating a metered lever you choose a name unique within the product, define a default value, specify one or more metering IDs, and define how raw usage is to be aggregated.

Name and slug

When lever related data (E.g. entitlements or usage stats) is retrieved from Planship via the API, the lever is identified by its slug. Lever slugs are unique within a product, and like all slugs in Planship they're autogenerated from their name.

Default limit

The default limit is the usage limit used for implicit entitlements of a lever across all plans.

Special values

  • 0 - no access
  • -1 - infinite/no-limit (useful for metered pay-as-you-go scenarios)

Example

Imagine a metered lever named hourly-api-calls that aggregates the number of API calls made by a customer in a one-hour period. Specifying 0 as the default value for the lever would make it unavailable across all plans without explicit entitlements with a different, non-zero value.

Metering ID

A metering ID is a string that identifies raw, metered usage reported by the product. Every Planship metered lever has one or more metering IDs. If a metered lever has multiple metering IDs, it will aggregate all usage reported for the IDs for a given customer.

Example

Imagine a product priced by monthly API call volume where the number of GETs and POSTs are tracked individually in addition to the total volume. To accomplish this with Planship, you could define a get-api-calls lever that tracks usage reported with a get-call metering ID, a post-api-calls lever that tracks usage reported with a post-call metering ID, and a total-api-calls lever that tracks both get-call and post-call metering IDs.

In addition, a metering ID can be used by multiple metered levers. This allows for aggregation of the same raw usage in different ways (E.g. different aggregation periods).

Example

Imagine an accounting product that offers different pricing tiers based on the volume of invoices issued per month with additional daily caps. To accomplish this with Planship, you could define two metered levers, monthly-invoices and daily-invoices, that track the same metering ID, invoice, with monthly-invoices configured to aggregate monthly while daily-invoices aggregates daily. With the two levers defined, separate entitlements for monthly and daily limits can be defined on individual plans.

Aggregation options

Planship supports multiple usage-aggregation scenarios through the configuration of formula, period, and scope.

Formula

The aggregation formula defines how usage is aggregated. It should be set to the default value (Aggregate all usage) unless you're using unique buckets and wish to aggregate them in some way.

  • Total usage - aggregate all usage, ignore bucket name (default)
  • Usage per bucket - aggregate usage per bucket
  • Unique buckets - count unique bucket names across metering records

Example

Imagine a product where pricing is based on monthly active API users. To accomplish this with Planship, you could define a monthly-active-users metered lever that uses the unique buckets formula and tracks a metering ID called api-call. The product would then report API calls to Planship along with a unique user identifier (E.g. ID or email address) passed as bucket.

Period

The aggregation period defines the time boundary for aggregation of metering records. The following options are available:

  • Per subscription period - aggregate usage reported in the current subscription period (default)
  • All time - aggregate all usage ever reported
  • Custom - aggregate usage reported in the rolling time period expressed in seconds

Scope

Scope defines whether usage should be aggregated per customer or per subscription, which can include multiple customers. By default, the aggregation scope is set to the subscription level. Changing the aggregation scope is meaningful only in team subscriptions.

Example

Imagine a file processing service with pricing tiers that limit the number of files uploaded by individual team members (I.e. subscription customers) per day as well as the number of seats per subscription. To implement this in Planship, you could define a files-per-customer metered lever that tracks a file-upload metering ID, and aggregate it using the total usage per day (custom period) formula with a per-customer aggregation scope. The seat limit would be defined in the plan configuration.