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 plan 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 plans with decimal amounts, specify amount_decimal instead of amount. amount_decimal allows you to set the amount in the minor unit of the currency you are charging in. For example, you can set amount_decimal = 105.5 in USD to represent 105.5 cents, or $1.055. amount_decimal accepts decimals up to 12 decimal places.

If you want a plan with 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 amount field is not populated if the object is created with a decimal value. For example, if you create a plan with amount_decimal = 0.05, the response contains amount = null and amount_decimal = 0.05. You can still pass integer values into amount_decimal, in which case amount is populated in the response. For instance, if you create a plan with amount_decimal = 5, the response contains amount = 5 and amount_decimal = 5.0.

Rounding

Rounding occurs on the line item level of your invoices. For example, if you create a plan with amount_decimal = 0.05 and a monthly subscription for that plan 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.