The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Decimal Pricing

Learn how to sell products and services that have prices up to 9 decimals

Summary

Decimal pricing is best for businesses that need to create pricing amounts that are not whole numbers. For example, a video streaming business has a service that charges $0.005 for each GB of data used per month. Based on the total usage at the end of the month, the usage is multiplied by $0.005 and rounded to the nearest whole cent.

Decimal Pricing on Plans and Subscriptions

To use decimal pricing, Create a usage add on via the Admin Console or V3 API (2021-02-25). When specifying pricing in the API, use unit_amount_decimal. Decimal pricing supports up to 9 decimal places for the fixed, tiered, volume, and stairstep pricing models. When unit_amount_decimal is provided, the unit_amount field is automatically set to null. When the subscription is created, the prices specified on the plan are used by default. You have the flexibility to override prices when creating a subscription if needed.

Setting up decimal pricing

Setting up decimal pricing

Logging Usage

Logging usage is done through the V3 API. Here is a guide on usage based billing and some additional developer documentation.

Invoices with Decimal Pricing

Each line item total will be rounded to the decimal values supported by the currency. Invoices will display the unit_amount_decimal value. For API responses, decimal pricing will be stored in the unit_amount_decimal field and unit_amount will be null.

Refunds for Decimal Pricing

Recurly will only enable you to refund up to the amount charged on the invoice and prevents you from refunding more than you charged the customer. Recurly recommends using line item refunds so you can clearly distinguish which product was refunded. For open amount refunds, Recurly splits the refund across all line items.

In the scenario of an open amount refund with decimal pricing, Recurly will round the amount and refundable quantity to be equal to the amount still able to be refunded. This can cause the price to be slightly different than what the customer paid, but will keep you from over-refunding a customer.

Emails

Emails will automatically populate the unit_amount_decimal values into the unit_amount parameter. If you display invoice line items in your emails, these will automatically work when you start using decimal pricing.

Exports

The Subscription Add-Ons, Subscription Add Ons History, and Subscription Add Ons Usage exports include a column called unit_amount_decimal which should be used when decimal pricing is used.

Webhooks

Subscription notifications will include a unit_amount_in_decimal_cents value when decimal pricing is used. unit_amount will be null when decimal pricing is used.

Some additional callouts for Decimal Pricing

  • Only available on the V3 API. Decimal pricing is not supported in V2
  • The Xero integration supports up to 4 decimal places for the unit_price. Some prices in Xero will round to two decimal places. The line item total charge will always be correct but the price is limited by the decimals Xero supports.
  • The Quickbooks integration supports up to 7 decimal places. The line item total charge will always be correct but the price is limited by the decimals Quickbooks supports.
  • Netsuite integration does not currently support decimal pricing. Reach out to [email protected] if this is a need for your business

Prerequisites

  • Credit Invoices and Only Bill What Changed must be enabled to utilize decimal pricing.
  • Supported on all Recurly Plans

Decimal Pricing for additional use cases

Our product team is tracking demand for decimal pricing for additional scenarios. Add Ons, Items, and One-Time charges do not support decimal pricing at this time. Reach out to [email protected] with your use case if this is something you'd like Recurly to support.

Updated 3 months ago

Decimal Pricing


Learn how to sell products and services that have prices up to 9 decimals

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.