Skip to content
Sign in
An image of the Stripe logo
/
Create account
Sign in
Home
Payments
Finance automation
Banking as a service
Developer tools
No-code
All products
Home
Payments
Finance automation
Home
Payments
Finance automation
Banking as a service
Developer tools
Overview
Billing
    Overview
    Subscriptions
      How subscriptions work
      Quickstart
      Build a subscriptions integration
      Embed a pricing table
      Design an integration
      Migrate subscriptions to Stripe
      Recurring pricing models
      Manage subscription cycles
        Set billing cycles
        Upgrade and downgrade subscriptions
        Pause payment collection
        Manage pending updates
          Pending updates reference
        Cancel subscriptions
        Manage prorations
        Share a link to update payment details
        Customer credit balance
        Set payment methods for subscriptions
      Subscription schedules
      Tax
      Subscription webhooks
    Invoicing
    Quotes
    Collection methods
    Revenue recovery
    Manage recurring revenue
    Products and prices
    Customer management
    About the Billing APIs
    Test your integration
    Strong Customer Authentication (SCA)
    Invoices API updates
Tax
Reporting
Data
Startup incorporation
HomeFinance automationBillingSubscriptionsManage subscription cycles

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, updates are applied 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.

Caution

Pending updates aren’t supported when the subscription’s collection_method is send_invoice or when bank debits are used as the payment method for the subscription.

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 https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:
\ -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" } ] },

Handling failed payments
Client-side

After making the update, check the pending_update hash on the subscription. If you want to be notified automatically, you can build a webhook that listens for the customer.subscription.updated event. If the pending_update hash is populated, the payment failed and the subscription will continue to cycle as if no update request was made.

Payments often fail because the payment method is declined or because they require customer authentication. You should build logic to handle both of these scenarios.

Use the instructions for payment failures to handle card declines. You need to attach a new payment method to the customer and then use the pay endpoint to pay the invoice that the update generates.

Use the customer action instructions to handle customer authentication. This walks the user through the authentication process and then pays the invoice.

A successful payment:

  • Immediately applies the changes in the pending_update hash.
  • 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.

OptionalCanceling or changing pending updates
Server-side

See also

Details on the lifecycle, webhooks, and supported attributes when using pending updates:

  • Pending updates reference
Was this page helpful?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Update the subscription
Handling failed payments
See also
Products Used
Billing
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$