Usage Transformation
Modifying usage before calculating total cost.
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.
Number of Users | Subscription Item Quantity Reported to Stripe | Total |
---|---|---|
1 | 1 | $10 |
3 | 1 | $10 |
5 | 1 | $10 |
6 | 2 | $20 |
7 | 2 | $20 |
With the usage_transformation
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.