Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
    Overview
    How subscriptions work
    Get started
    Quickstart
    Plan an integration
    Build an integration
    Use cases
    About subscriptions
    Enable billing mode
    Subscription event definitions
    Entitlements
    Subscription invoices
    Subscription schedules
    Recurring pricing models
    Strong Customer Authentication (SCA)
    Set up subscriptions
    Configure collection methods
    Embed a pricing table
    Set quantities
    Set billing cycles
    Manage subscriptions
    Migrate subscriptions to Stripe
    Subscribe to multiple items
    Backdate subscriptions
    Set trial periods
    Handle subscriptions with deferred payment
    Apply coupons
    Modify subscriptions
      Change prices
      Cancel subscriptions
      Pause payment collection
      Manage prorations
      Manage pending updates
    Manage subscription payment methods
    Analytics
Invoicing
Usage-based billing
Quotes
Customer management
Billing with other products
Revenue recovery
Automations
Test your integration
Tax
Overview
Use Stripe tax
Manage compliance
Reporting
Overview
Select a report
Configure reports
Reports API
Reports for multiple accounts
Revenue recognition
Data
OverviewSchema
Custom reports
Data Pipeline
Data management
HomeRevenueSubscriptionsModify subscriptions

Pending updates

Learn how to handle payment failures when updating subscriptions.

Updating a subscription generates a new invoice when:

  • The subscription requires payment for the first time, such as the end of a trial period.
  • The billing period changes.
  • Changing the subscription causes a proration and proration_behavior=always_invoice.

By default, Stripe applies updates regardless of whether payment on the new invoice succeeds. If payment fails, rolling back the updates is a manual process. You need to create a new invoice, prorate items on the invoice, and then initiate payment again. However, with the pending updates feature, you can make changes to subscriptions only if payment succeeds on the new invoice.

Before you begin

You can use pending updates if the subscription’s collection_method is charge_automatically or when the subscription’s payment method is either a card or Link.

Update the subscription
Server-side

You can use pending updates with the update subscription, create subscription item, and update subscription item calls. When you make the update, set payment_behavior=pending_if_incomplete. The example below adds a new price to a subscription. Because proration_behavior=always_invoice, an invoice is created and payment is attempted when the update is made.

Command Line
curl
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:
\ -d "payment_behavior"="pending_if_incomplete" \ -d "proration_behavior"="always_invoice" \ -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f"

If payment succeeds, the subscription is updated. If payment fails, the Subscription object that’s returned contains a pending_update hash with the changes:

{ "id": "sub_49ty4767H20z6a", "object": "subscription", "application_fee_percent": null, "pending_update": { "expires_at": 1571194285, "subscription_items": [ { "id": "si_09IkI4u3ZypJUk5onGUZpe8O", "price": "price_CBb6IXqvTLXp3f" } ] }, }

Handle failed payments
Client-side

After making the update, check the pending_update hash on the subscription or listen for the customer.subscription.updated event in your webhook. A populated pending_update hash means the payment failed and your subscription update isn’t applied.

Build logic to handle payment failures due to card declines and customer authentication requests:

  • For card declines, attach a new payment method to the customer. Then use the pay endpoint to pay the invoice that the update generates.
  • For customer authentication, follow the requires action flow.

A successful payment immediately applies the changes in the pending_update hash and updates the invoice to paid.

If payment fails again, the pending_update hash remains on the subscription with the original expiry date and no changes are applied.

OptionalCancel or change pending updates
Server-side

Supported attributes for pending updates

Pending updates only support attributes that control proration behavior or generate new invoices.

The update subscription endpoint supports the following attributes:

  • expand
  • payment_behavior
  • proration_behavior
  • proration_date
  • billing_cycle_anchor
  • items
    • price
    • quantity
  • trial_end
  • trial_from_plan
  • add_invoice_items

The create subscription item and update subscription item endpoints support the following attributes:

  • expand
  • payment_behavior
  • proration_behavior
  • proration_date
  • price
  • quantity

Expired updates

If you don’t take any action after an update fails, Stripe voids the invoice and discards the update after it expires.

A pending update’s expired_at time matches the first occurrence of either the trial end or the earliest items.current period end. This applies if either time is within 23 hours of the update request. Otherwise, the expiration is 23 hours from the update request.

Stripe also automatically voids the invoice and removes the pending update if any of the following occurs:

  • The subscription reaches a billing threshold.
  • A subscription schedule linked to the subscription transitions to a new phase.

Pending updates events

Use webhooks to listen for the following events related to pending updates:

EventPurpose
customer.subscription.updatedReceive notifications for subscriptions, checking for the pending_updates hash and resolving payment failures if needed.
customer.subscription.pending_update_appliedReceive notifications when pending updates are applied so that you can take further actions like upgrading, downgrading, provisioning, or deprovisioning services.
customer.subscription.pending_update_expiredReceive notifications when pending updates expire or are automatically voided, and if needed, try the update request again.

Pending updates and subscription schedules

You can use both pending updates and subscription schedules to manage subscriptions. A schedule phase change discards a pending update and voids the associated invoice. Retry the update request after the phase transition if needed.

Metered items

If a subscription includes metered items, Stripe bills any outstanding usage on the pending update invoice. However, if the pending update expires before payment, Stripe discards this usage, which prevents any subsequent invoices from billing for them.

If the pending update removes a metered price, Stripe disregards any usage reported between the pending update’s creation and the resulting invoice payment. You can’t bill for that usage. However, if billing_mode=flexible is on the subscription, Stripe bills for usage when removing a metered price.

Was this page helpful?
YesNo
  • Need help? Contact Support.
  • Join our early access program.
  • Check out our changelog.
  • Questions? Contact Sales.
  • LLM? Read llms.txt.
  • Powered by Markdoc