Pending updates reference

    Learn more about the pending updates feature.

    Supported attributes

    Only certain attributes can be used to create a pending update. These attributes either control proration behavior or generate new invoices.

    The supported attributes for the update subscription endpoint are:

    • expand
    • payment_behavior
    • proration_behavior
    • proration_date
    • billing_cycle_anchor
    • items
      • plan
      • quantity
    • trial_end
    • trial_from_plan

    The supported attributes for the create subscription item and update subscription item endpoints are:

    • expand
    • payment_behavior
    • proration_behavior
    • proration_date
    • plan
    • quantity

    Pending updates lifecycle

    If payment succeeds, the invoice is updated to paid and the changes are applied to the subscription immediately. If payment fails, the updated values are added to the pending_update hash on the Subscription object. The latest_invoice for the subscription refers to an unpaid invoice in an open status. The subscription will continue to cycle as if no update request was made.

    There are two ways to handle payment failures. These are related to declines and customer authentication. After resolving these issues, payment is attempted again. If the payment succeeds, the changes are applied and the pending_update hash is cleared. If payment fails again, the pending_update hash remains on the subscription with the original expiry date and no changes are applied.

    If you cancel a pending update, the pending_update hash is cleared and the associated changes are discarded.

    Expiration

    If you don’t take any action after an update fails, the invoice is voided and the pending update is discarded after the expired_at time on the pending_update has passed. This time is set to either the trial end time or the current period end, whichever comes first. If these times are greater than 23 hours from the time the update is made, the expired_at time is calculated to 23 hours after the update call was made.

    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

    You can use webhooks to listen for the following events related to pending updates:

    Event Purpose
    customer.subscription.updated Receive notifications for subscriptions, checking for the pending_updates hash and resolving payment failures if needed.
    customer.subscription.pending_update_applied Receive notifications when pending updates are applied so that you can take further actions like upgrading, downgrading, provisioning or deprovisioning services, etc.
    customer.subscription.pending_update_expired Receive notifications when pending updates expire or are automatically voided, and if needed, try the update request again.

    Pending updates and subscription schedules

    Pending updates and subscription schedules can both be used to manage subscriptions. If a pending update exists when a schedule changes phases, the pending update is discarded and the associated invoice is voided before the phase transition occurs. You can retry the update request after the phase transition if needed.

    Was this page helpful?

    Feedback about this page?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page