Improvements to how proration is processed

What's new?

We've improved the way that we process prorated changes to a subscription, like adding or removing items or upgrading or downgrading mid-cycle. Changes to items are now reflected on a transaction, making it easier to understand what changed on a subscription.

As a result, quantity fields against transactions may now return negative values. This was previously permitted, but never occurred in practice.

We also added a new credit_to_balance field to transaction totals and transaction payout totals.

How it works

When you make a change to a subscription and choose to prorate, Paddle calculates what a customer should be billed or credited. For example, if a customer adds a product midway through their billing cycle, you can charge them for just the time they used rather than the entire period.

How it worked before

Previously, prorated changes worked using adjustments. When a prorated change was made to a subscription:

1. Paddle created an adjustment against the initial transaction for the prorated changes.

2. Where a credit was created, Paddle added this to a customer credit balance.

3. Paddle created a new transaction for the changes and uses the credit from the adjustment to reduce the amount due.

We understand that this was confusing for both you as sellers and for your customers as emails were not clear and the way adjustments were created was sometimes unexpected.

How it works now

With this update, prorated changes are reflected on a transaction:

• When adding items to a subscription, Paddle charges for the delta. This is the difference between the initial amount and the added amount. For example when changing the quantity of an item from 7 to 10 Paddle now simply charges for 3x that item.
• When removing items from a subscription, Paddle now uses negative line items on a transaction instead of adjustments. For example, transactions for a mid-cycle price upgrade will show a negative line item for the initial price that reduces the amount due.

This means that it's much clearer to see what changed on a subscription and how the changes impact the amount due.

In cases where negative line items on a transaction completely pay a transaction, the remaining amount is added to a customer credit balance for future transactions. Emails and invoices show the amount added to balance, and there's a new credit_to_balance field in the transaction totals object in the API for this.

Summary of changes to fields

This is a summary of the changes to fields in the Paddle API and webhooks:

Example

Summary of subscription items

How it worked before

1. Adjustment created

   Paddle creates an adjustment against the initial transaction for the prorated amount for the removed items. The customer receives an email to say that they've been issued a prorated credit.

   Item	Quantity	Starts at	Ends at	Proration	Total
   Starter plan	10	Jul 15 00:00	Aug 1 00:00	0.5	$50
   TOTAL					$50

2. Amount added to customer balance

   Paddle adds the amount adjusted to the credit balance for a customer. It is reserved for the new transaction that's created for the subscription changes.

3. New transaction created

   Paddle creates a new transaction for the subscription changes. It includes the reserved amount from the customer credit balance. The customer receives an email receipt with their invoice.

   Item	Quantity	Starts at	Ends at	Proration	Total
   Pro plan	10	Jul 15 00:00	Aug 1 00:00	0.5	$150
   Subtotal					$150
   Credit					-$50
   TOTAL					$100

How it works now

1. New transaction created

   Paddle creates a new transaction for the subscription changes. The customer receives an email receipt with their invoice.

   Item	Quantity	Starts at	Ends at	Proration	Total
   Pro plan	10	Jul 15 00:00	Aug 1 00:00	0.5	$150
   Starter plan	-10	Jul 1 00:00	Jul 15 00:00	0.5	-$50
   TOTAL					$100

Next steps

This change is available in version 1 of the Paddle API.

It's considered a non-breaking change, but you should check that your integration supports negative values for quantities and amounts for transaction totals and line items. This was previously permitted, but never occurred in practice.

When is this feature rolling out?

We're rolling this feature in stages to give existing Paddle Billing customers time to review:

If you're an existing Paddle Billing customer, we'll start rolling out the change on your sandbox account on March, 11th 2024. This means you can demo and test the change before it goes live to your customers.

We'll start rolling out the change for all Paddle Billing accounts — including live accounts — on March 25th, 2024. We'll email you before to let you know, but you don't need to do anything.

What happens when this feature is released?

All subscriptions are scheduled to use the new proration processing changes by April 25th, 2024.

For all accounts, once released:

• Newly created subscriptions will use the new proration processing changes.
• Subscriptions with a billing interval of one month or less will use the new proration processing changes on renewal.
• Subscriptions with a billing interval greater than one month will use the new proration processing changes by April 25th.

For sandbox accounts, we've identified a small number of subscriptions that are incompatible with the new proration processing changes. If your account is impacted, we'll email to let you know and talk to you about your options.

Subscriptions for live accounts are fully compatible with the new proration processing changes. Only a small number of subscriptions for sandbox accounts are incompatible. Sandbox is a test environment, and there is no impact on live data or your revenue.

Learn more