Decimal amounts for pricing

Learn how to create prices and invoice items with decimal amounts.

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.