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.

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

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