Paddle Billing
Search

Improvements to how proration is processed

Prorated changes to a subscription are now reflected on a transaction, rather than separate adjustments. Item quantities, item amounts, and totals against a transaction may be negative, and there's a new field in transaction totals.

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.

credit_to_balancestring

Additional credit generated from negative details.line_items. This credit is added to the customer balance.

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 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:

FieldChangeNotes
transaction.details.totals.credit_to_balanceNew field
transaction.details.payout_totals.credit_to_balanceNew field
transaction.items[].quantityBehavior changeMay return a negative value.
transaction.details.line_items[].quantityBehavior changeMay return a negative value.
transaction.details.line_items[].totalsBehavior changeFields may return negative values.
transaction.details.totalsBehavior changeFields may return negative values.
transaction.details.payout_totalsBehavior changeFields may return negative values.

Example

In this example, a customer upgrades their subscription. They move from Starter to Pro.

In Paddle, this means replacing items on a subscription:

  • Starter plan item is removed from the subscription.
  • Pro plan item is added to the subscription.

For simplicity, the customer upgrades at exactly half-way through the billing cycle (Jul 15 12:00). This means the proration rate is 0.5.

When making changes, we choose to prorate and bill immediately, which means Paddle creates a transaction immediately for prorated changes.

Initial billing dateJul 1 00:00
Billing periodmonthly
Next billing dateAug 1 00:00
Change dateJul 15 12:00
Proration rate0.5
Proration billing modeprorated_immediately

Summary of subscription items

ItemQuantityUnit priceTotal
Starter plan10$10$100
Reporting module1$100$100
TOTAL$200

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.

    ItemQuantityStarts atEnds atProrationTotal
    Starter plan10Jul 15 00:00Aug 1 00:000.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.

    ItemQuantityStarts atEnds atProrationTotal
    Pro plan10Jul 15 00:00Aug 1 00:000.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.

    ItemQuantityStarts atEnds atProrationTotal
    Pro plan10Jul 15 00:00Aug 1 00:000.5$150
    Starter plan-10Jul 1 00:00Jul 15 00:000.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:

Account typeRelease date
New signups for PaddleAllJanuary, 29th 2024
Existing Paddle customersSandboxMarch 11th, 2024
Existing Paddle customersLiveMarch 25th, 2024

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 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