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.

This change is available for customers who signed up for Paddle Billing on or after January 29th, 2024.

If you signed up for Paddle Billing before this date, it's scheduled to be released on your sandbox account on March 11th, 2024 and on your live account on March 25th, 2024.

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

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 we're releasing in stages to give existing Paddle Billing customers time to review:

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

If you're an existing Paddle Billing customer, we'll release 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 make the change generally available for all Paddle Billing accounts — including live accounts — on March 25th, 2024. We'll email you before it's released to let you know, but you don't need to do anything.

Learn more