Public preview
Defer credit prorations Public preview
Collect the debit payment before crediting the customer.
Public preview
Credit proration deferral is in public preview. Functionality might change during development.
Credit proration deferral prevents customers from receiving the benefit of proration credits before they pay their applicable debit. When enabled, Stripe holds credit proration invoice items in a pending state until the original debit invoice is paid. After it’s paid, the credit becomes eligible and is included on the customer’s next invoice.
How credit proration deferral works
When you enable credit proration deferral, any newly created credit proration invoice item is tagged with an invoicing rule with type: defer_until_credited_items_resolved. This rule prevents the credit from being included on an invoice until its corresponding debit invoice is in a resolved state.
| State of original debit invoice | What happens to the credit |
|---|---|
| Paid | Credit is included on the next invoice as normal |
| Not yet invoiced (still pending) | Debit and credit are swept onto the same invoice together |
| Invoiced but unpaid | Credit is deferred and not included on any invoice until the debit is paid |
After the original debit invoice is paid, the credit item becomes eligible and is included on the customer’s next invoice.
Enable credit proration deferral
Credit proration deferral is enabled through a Dashboard setting that applies to all subscriptions created on your account. You don’t need to make any API integration changes.
To enable the feature:
- Go to Settings > Billing > Subscriptions and emails in the Dashboard.
- Scroll to the Manage subscription credit prorations section.
- Select your preferred deferral behavior.
Test credit proration deferral
To test credit proration deferral, use a sandbox and enable the feature. Create and update subscriptions on this account to see how Stripe defers credit proration invoice items.
View deferred items with the API
When a credit invoice item is deferred, you can inspect its status through the API. Deferred pending invoice items include the invoicing rule defer_until_credited_items_resolved:
{
"object": "invoiceitem",
"id": "ii_123",
"proration_details": {
"credited_items": {
"type": "invoice_line_items",
"invoice_line_item_details": {
"invoice": "in_abc",
"invoice_line_items": ["ili_1"]
}
}
},
"invoicing_rules": [{"type": "defer_until_credited_items_resolved"}]
}
The invoicing_rules field indicates that ii_123 can’t be invoiced until in_abc is paid. The proration_details.credited_items field shows which specific debit items the credit is tied to.
Release a deferred invoice item
If you want to release a specific deferred credit before the original debit invoice is paid, clear the invoice item’s invoicing rules. You can only clear rules from pending invoice items that haven’t already been attached to an invoice.
After clearing, the invoice item returns invoicing_rules: [] and becomes eligible for being included on the next invoice.
Limitations
Consider the following limitations when using credit proration deferral.
Impact on customers with unpaid invoices
If a customer has an unpaid invoice for legitimate reasons (for example, an expired card they intend to update) and their subscription is updated while that invoice is unpaid:
- The new invoice generated by the update only contains the debit amount. The proration credit is deferred.
- The customer has two outstanding invoices: the original pre-update invoice and the new post-update invoice.
- They must pay the original invoice first to release the credit.
- The released credit will appear on their next invoice, not immediately.
Orphaned credits
If a subscription is canceled before the customer pays the original debit invoice, the deferred credits aren’t automatically invoiced and granted to the customer. You can manually create an invoice to pick up these released credit invoice items.
Disable credit proration deferral
Turning off credit proration deferral only prevents newly created credit invoice items from being deferred. Existing pending invoice items that were previously tagged by the invoicing rule continue to be deferred until the debit invoice is paid.