Billing
Additional features
Quantity transformation

Quantity 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 quantity 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 transform_quantity parameter, you can instruct Stripe to transform the quantity before applying the per unit cost. The following subscription 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.

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

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

Note that transform_quantity only works with billing_scheme=per_unit. It is incompatible with tiered pricing.

Rounding

The previous example showed a subscription 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 internet service, you can also pass down as the value of round.

Metered usage

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

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

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

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

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.