When you bill your customers, you may wish to track usage at a different granularity than you bill. For example, consider a productivity software suite that charges $10 for every 5 users (or portion thereof) using the product. Without usage transformation, they would need to increase the quantity of the subscription item by 1 for every 5 users.

With the transform_usage parameter, you can instruct Stripe to transform the quantity before applying the per unit cost. The following plan allows you to naturally report the current number of users as the subscription item quantity—Stripe’s billing system divides the quantity by 5 and rounds up before calculating by the unit cost.

  curl https://api.stripe.com/v1/plans \
-u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
-d nickname="Standard Cost Per 5 Users" \
-d "transform_usage[divide_by]=5" \
-d "transform_usage[round]=up" \
-d amount=1000 \
-d currency=usd \
-d interval=month \
-d product="{{PRODUCTIVITY_SUITE_ID}}" \
-d usage_type=licensed

Currently, the only available transformation is division, using the divide_by parameter in conjunction with the round parameter.

Note that transform_usage only works with billing_scheme=per_unit. It is incompatible with tiered pricing and returns an error if you attempt to create a tiered Plan with a transformation.

Rounding

The previous example showed a plan that charges for every 5 users rounding up, i.e. 6 divided by 5 results in a quantity of 2. For use cases where you do not want to charge for a portion of usage, like charging for every full gigabyte of usage of a broadband plan, you can also pass down as the value of round.

Metered usage

You can also apply transform_usage in conjunction with metered plans. This transformation applies to plans with usage_type=metered at the end of a billing period in the same way it applies to quantity for plans with usage_type=licensed.

A marketing email service that creates a metered Plan to charge $0.10 for every full 1000 emails sent might look something like this:

  curl https://api.stripe.com/v1/plans \
-u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
-d nickname="Metered Emails" \
-d "transform_usage[divide_by]=1000" \
-d "transform_usage[round]=down" \
-d amount=10 \
-d currency=usd \
-d interval=month \
-d product="{{MARKETING_EMAILS_ID}}" \
-d usage_type=metered

With this plan, usage can be reported per email and the customer is billed $0.10 for every 1000 emails they send.