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 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 \ -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.


    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 \ -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.

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page