Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
Customers
Products and Prices
Tax Rates
Customer portal
Quotes
Start with a use case
Subscriptions with Checkout
Fixed-price subscriptions with Elements
Metered billing with Elements
Per-seat billing with Elements
Manage subscriptions
How subscriptions work
Subscription webhooks
Change subscriptions
Strong Customer Authentication (SCA)
Improved tax support
Invoices API updates
Migrating to Prices
Additional features
Adding taxes
Applying discounts
Backdating subscriptions
Decimal amounts
Metered billing
Multiple subscriptions
Prorations
Setting quantities
Subscriptions with Connect
Subscriptions with multiple products
Subscription schedules
Tiered pricing
Quantity transformation
Using trial periods
Testing
Add payment methods
Bacs Direct Debit in the UK
BECS Direct Debit in Australia
SEPA Direct Debit in the EU
Invoice customers
How invoices work
Create an invoice
Customize invoices
Hosted invoice page
Additional features
Revenue recognition
Overview
Reports
Methodology
Examples
Overrides
Testing
billing
·
HomePaymentsSubscriptions and invoicesAdditional features

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.

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.
You can unsubscribe at any time. Read our privacy policy.
On this page
Creating objects with decimal amounts
Rounding