Documentation

The calculation of charges during a billing period is affected by the settings of the following fields in Create Plan.

The calculation of amounts billed is also affected by the length of the billing period.

Licensed Usage

When the user is charged for a service regardless of whether it is actually used during the billing period, this is licensed usage. In this case, the usage_type field of the 'plan' object is set to licensed.

Metered Usage

When the customer is charged only for the services that are actually used, this is metered usage, and the usage_type field of the 'plan' object is set to metered.

Aggregate Usage

When the usage_type field of the 'plan' object is metered, the customer is billed for one of the following values:

Straight pricing is used for services where the price never varies according to quantity or usage. The billing_scheme field is set to per_unit.

Your plan can define tiered pricing, where the per-unit cost changes depending on the number of units sold during the billing period. There are two different ways to calculate the total cost during the billing period:

Volume Pricing

Volume pricing calculates the total cost as the number of units multiplied by the applicable tier price. The price for all the units ordered is determined by the total volume in the billing period. The formula for the total price is as follows:

InvoiceTOTAL = (P x Qtier achieved)

where:

Consider the following examples:

If the customer uses 10 units in the billing period, the total cost is $95.00.

If the customer uses 20 units, the total cost is $180.00.

To create a plan for volume pricing, define the prices for each tier and set the following fields:

billing_scheme = tiered tiers_mode = volume

Volume pricing example

{
    "billing_scheme": "tiered",
    "tiers_mode": "volume",
    "tiers": [
        {
            "up_to": 5,
            "amount": 10
        }, 
        {
            "up_to": 10,
            "amount": 9.5
        }, 
        {
            "up_to": 20,
            "amount": 9
        }
    ]
}

Graduated Pricing

Graduated pricing calculates the total cost at each price tier separately (number of items in the tier multiplied by the tier price), then combines all tier charges together.

The formula for a two-tier pricing structure is as follows:

InvoiceTOTAL = (P x Qfirst tier) + (P x Qsecond tier)

where:

Using the same tier structure as the volume pricing example, we get a different total cost.

If the customer orders 10 units in the billing period, the total is $97.50, calculated as follows:

To create a plan for graduated pricing, define the prices for each tier and set the following fields:

billing_scheme = tiered tiers_mode = graduated

Graduated Pricing Example

{
    "billing_scheme": "tiered",
    "tiers_mode": "graduated",
    "tiers": [
        {
            "up_to": 5,
            "amount": 10
        }, 
        {
            "up_to": 10,
            "amount": 9.5
        }, 
        {
            "up_to": 20,
            "amount": 9
        }
    ]
}

Transformation pricing changes the quantity to fit it into a predefined billing structure. The quantity might be rounded up or down to the next whole billing unit.

Licensed Transformation Pricing

Licensed transformation pricing applies where the customer reserves a service for a specified time, and charges apply whether the service is actually used or not.

The merchant might offer a batch pricing structure. Consider the following example:

A batch of up to five software licenses costs $1,500.00 regardless of the actual usage. The quantity is rounded up to the next five. 4 licenses are rounded up to 5, and 9 licenses are rounded up to 10.

To create a plan for licensed transformation pricing, set the following fields:

billing_scheme = per_unit usage_type = licensed

For this example, in the 'transform_usage' object, set the following fields:

divide_by = 5 round = up

Licensed Transformation Pricing Example

{
    {
    "amount": 1500,
    "currency": "USD",
    "product": "product_88fde8f1365082b50e8f4b37127edd99",
    "nickname": "Licenses",
    "usage_type": "licensed",
    "trial_period_days": "0",
    "billing_scheme": "per_unit",
    "transform_usage": {
        "divide_by": 5,
        "round": "up"
    },
    "interval": "month",
    "interval_count": "2"
}

Metered Transformation Pricing

Metered transformation pricing applies where the usage is reported in smaller units than the billing units, and some rounding is necessary for purposes of billing. A parking lot might charge $10.00 per hour, however, if the customer does not use the parking lot, there is no charge at all.

To create a plan for metered transformation pricing, set the following fields:

billing_scheme = per_unit usage_type = metered

For this example, in the 'transform_usage' object, set the following fields:

divide_by = 60 round = up

Metered Transformation Pricing Example

{
   "amount": 10.00,
   "currency": "USD",
   "product": "product_5a3e46804b01c4999cd061f032a02aea",
   "nickname": "Hourly Metered Parking",
   "trial_period_days": "0",
   "billing_scheme": "per_unit",
   "usage_type": "metered",
   "aggregate_usage": "sum",
   "transform_usage": {
       "divide_by": 60,
       "round": "up"
   },
   "interval": "day",
   "interval_count": "1"

}