Pending updates

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.

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"
      }
    ]
  },

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.