Decimal amounts for pricing
Decimal pricing is useful if you need to create pricing amounts that are not whole numbers. For example, if you are running a cloud storage SaaS business, you can create a price that charges 0.05 cents for each MB used per month. Based on usage, the quantity of MB is then multiplied by 0.05 cents and rounded to the nearest whole cent.
Creating objects with decimal amounts
To create prices with decimal amounts, specify unit_amount_decimal
instead of unit_amount
. unit_amount_decimal
allows you to set the amount in the minor unit of the currency you are charging in. For example, you can set unit_amount_decimal = 105.5
in USD to represent 105.5 cents, or $1.055. unit_amount_decimal
accepts decimals up to 12 decimal places.
If you plan to use tiers, you can specify unit_amount_decimal
instead of unit_amount
. You can also create invoice items with unit_amount_decimal
instead of unit_amount
.
In API responses, the integer unit_amount
field is not populated if the object is created with a decimal value. For example, if you create a price with unit_amount_decimal = 0.05
, the response contains unit_amount = null
and unit_amount_decimal = 0.05
. You can still pass integer values into unit_amount_decimal
, in which case unit_amount
is populated in the response. For instance, if you create a price with unit_amount_decimal = 5
, the response contains unit_amount = 5
and unit_amount_decimal = 5.0
.
If your integration has event handling that uses unit_amount
values and you begin using decimal amounts, you need to use unit_amount_decimal
instead. This is important because unit_amount
will be returned as null
if the decimal amounts cannot be converted into integers, which could cause errors in your integration.
Rounding
Rounding occurs on the line item level of your invoices. For example, if you create a price with unit_amount_decimal = 0.05
and a monthly subscription for that [price] with quantity = 30
, rounding occurs after the quantity is multiplied by the decimal amount. In this case, the calculated amount for the line item would be 0.05 * 30 = 1.5
, which is then rounded up to 2 cents. If you have multiple line items, each will be rounded before summing up the total amount for the invoice. This ensures that customers are still charged an integer minor unit amount, as decimal amounts only apply for pricing.