Stripe expired_card decline: what it means and what to doUnofficial guide based on Stripe's docs
A customer's subscription renewal failed on Stripe because their card had expired, and you see expired_card. This page sums up what Stripe's docs say about it: what the code means and where it shows up, what Stripe can do on its own (automatic card updates, retries, and expiring card emails), and what you can do on top of that.
The facts here come from Stripe's docs, not from running a subscription business on Stripe ourselves, and we haven't seen these screens in a live account. Setting names are written as the docs show them, so if your Dashboard looks different, go by what you see.
What expired_card means
- Stripe's decline codes table describes
expired_cardas a card that has expired, and gives one next step: the customer uses another card. - Unlike
lost_cardorstolen_card, the table doesn't tell you to hide this reason from the customer. expired_cardis also listed as an API error code, with the advice to check the expiration date or use a different card. In the API's error object,codeholds the error code for errors that have one, anddecline_codeholds the card issuer's reason for card errors that come from an issuer decline, if the issuer provides one.- Stripe's test card tables show the difference. The expired card test card returns the error code
expired_cardand lists no decline code (“n/a”). The generic decline test card returns the error codecard_declinedwith the decline codegeneric_decline. - On the charge, Stripe's declines guide shows an example
outcomewhosereasonisexpired_card, with thetypeissuer_declinedand thenetwork_statusdeclined_by_network. In that example theadvice_codeisconfirm_card_data, which Stripe's card declines guide describes as the issuer declining because some of the card information is incorrect. - Two nearby codes are about the date rather than an expired card:
invalid_expiry_monthandinvalid_expiry_yearmean the expiration month or year is invalid, and the next step is to try again with the correct date. - If the customer pays with a local payment method instead of a card,
expired_cardcan also mean that the card registered with that payment provider has expired. In that case the charge's outcome reason ispartner_expired_card.
Our suggestion: When you look for this failure, check the error's code as well as its decline_code, and the charge's outcome.reason, so you don't miss it in whichever field it shows up.
From: Stripe: Decline codes, Stripe: Error codes, Stripe API reference: Errors, Stripe: Testing, Stripe: Declines, Stripe: Card declines
Can Stripe update the card on its own?
- Stripe works with card networks to try to update saved card details automatically when a customer gets a new card, for example one that replaces an expired card.
- This needs the card issuer to take part with the network and provide the new details. Stripe says it's widely supported in the United States, that support in other countries varies, and that you can't tell in advance which cards support automatic updates.
- Two webhook events tell you about card changes:
payment_method.automatically_updatedfor automatic updates from the network, andpayment_method.updatedfor updates made through an API call. They include the card's new expiration date and last four digits. If the update brings a new card number, the card'sfingerprintchanges. - Stripe's revenue recovery overview lists automatic card updates as one of its recovery features.
Our suggestion: Since you can't tell which cards will be updated, don't wait for an automatic update once a renewal has failed with expired_card. Contact the customer anyway.
Will Stripe retry it?
expired_cardisn't on the list of nine hard decline codes in Stripe's retry guide, and the guide doesn't mentionexpired_cardanywhere else.- When retrying, Stripe uses the first payment method available in this order: the subscription's
default_payment_method, the subscription'sdefault_source, the customer's default payment method (customer.invoice_settings.default_payment_method), then the legacycustomer.default_source. - The charge's
outcomecan also carry anadvice_code.try_again_latermeans you can retry,do_not_try_againmeans you shouldn't use that card again for the same transaction, andconfirm_card_datameans some of the card information was wrong. - Smart Retries uses AI to pick retry times. You set how many tries and the window: 1 week, 2 weeks, 3 weeks, 1 month, or 2 months. Stripe's retry guide says new Stripe accounts get Smart Retries turned on by default, set to up to 8 retries within 2 weeks.
- Instead of Smart Retries you can set a custom schedule of up to three retries, each a set number of days after the previous one.
- Card networks limit how many times one charge can be reattempted. For charges that permit retries, Stripe recommends eight retries at most, because issuers can read extra ones as possible fraud.
- The invoice's
next_payment_attemptshows when Stripe will try to collect next. - Stripe's retry guide lists four cases where it doesn't retry: no payment method is available, the issuer returned a hard decline code, the card was issued in India, or the Stripe Connect account has been disconnected.
Our suggestion: Stripe's retry guide doesn't say whether retrying a card that has expired can succeed, so ask the customer for a new card instead of waiting on retries. Also open Billing > Revenue recovery > Retries and confirm what your account is actually set to, rather than assuming the default applies to you.
From: Stripe: Automate payment retries, Stripe: Card declines
What Stripe can already tell the customer
- With “Send emails about expiring cards” turned on, Stripe emails the customer 1 month before their card on file expires, when that card is their default payment method or default source.
- With “Send emails when card payments fail” enabled in the revenue recovery settings, Stripe emails the customer after each failed subscription payment and gives them a way to update their payment method. Stripe's docs name an expired card as one example of a failure reason this email helps the customer fix.
- Both emails include a link to a page where the customer can update their payment method. You choose where that link goes: a Stripe-hosted page or your own subscription management page. The emails and hosted pages use your branding settings.
- On the Stripe-hosted page, the customer can update the payment method for that subscription and pay outstanding invoices if there are any. Otherwise, the new payment method is used the next time a scheduled payment is attempted.
- Stripe doesn't include the Stripe-hosted link if the subscription is set to send invoices manually. The link also stops working in some cases, including when the subscription becomes canceled or unpaid, or when its current renewal period ends.
- Emails about expiring cards on file show up in the email logs on the Customers page, which cover the last 60 days, are updated daily, and don't include emails from the current date.
Our suggestion: Stripe's docs describe the expiring card email by the customer's default payment method or default source. If your subscriptions keep the card on the subscription's own default_payment_method, check in a sandbox that the email goes out for your setup. And if you also email the customer yourself, read Stripe's emails first so they don't contradict each other.
What you can do
- When the customer isn't there for the payment, as with a renewal, Stripe's card declines guide says to notify them, for example by email or in-app message, so they come back to your site or app.
- If you've set up Stripe's customer portal, customers can update their payment methods and pay current and past invoices there.
- Stripe gives every invoice a hosted invoice page where the customer can pay that invoice with any of the payment methods enabled for it. If “Include a link to a payment page in the invoice email” is selected in your Invoice settings, the link also appears in invoice emails, invoice PDFs, and the API as
hosted_invoice_url. - For an invoice that belongs to a subscription, a card the customer pays with on the hosted invoice page is saved only if they don't already have a default invoice payment method. Hosted invoice links expire 30 days after the invoice's due date, or 30 days after it's finalized if it has no due date. Either way, the window is never longer than 120 days.
- A subscription whose latest invoice failed to pay has the status
past_due. Your failed payment settings decide what happens after the last retry: it becomescanceledorunpaid, stayspast_due, or, if the subscription is eligible, becomespaused. - Stripe's docs say to revoke access when a subscription is
unpaid, because Stripe already retried while it waspast_due.
Our suggestion: Send the customer to your customer portal or your own billing page so the new card is used for future renewals, and make sure it lands in the field your retries use. Use the hosted invoice page only when you want this one invoice paid.
From: Stripe: Card declines, Stripe: Customer portal, Stripe: Hosted invoice page, Stripe: How subscriptions work, Stripe: Automate payment retries
A short email you could send
This is our own example, not Stripe's wording. Replace the parts in brackets.
Subject: Your card for [Product] has expired
Hi [first name],
We tried to renew your [Product] subscription on [date], but the card ending in [last 4 digits] has expired.
To keep using [Product], please add a new card here: [your link to update the card]
If something looks wrong, just reply to this email.
[Your name]
- Use this email only for card payments that fail with
expired_card(in the error'scodeordecline_code, or the charge'soutcome.reason). For other decline codes, the cause is different, so don't tell the customer their card expired. - If the charge's
outcome.reasonispartner_expired_card, the customer paid with a local payment method and the expired card is the one registered with that payment provider. Don't send this email, and don't ask them to add a new card on your page. - If the card was updated after the payment failed, for example you received
payment_method.automatically_updatedor the customer added a new card, check the invoice before sending so you don't ask for a card they've already replaced. - [your link to update the card] is a link you add yourself: your customer portal or your own billing page. Make sure the new card lands in the field your retries use, so it's used for future renewals. The hosted invoice page pays this one invoice.
- If Stripe's failed payment email is on, the customer also gets that email with its own link. Make sure the two emails don't point them to different places without saying why.
- Only mention a cancellation date if your failed payment settings actually cancel the subscription, and don't ask for card numbers by reply. Keep it short and neutral.
Mistakes to avoid
- Leaving it to retries alone. For
expired_card, the next step in Stripe's decline codes table is that the customer uses another card. - Counting on an automatic card update. It depends on the issuer taking part, and Stripe says you can't tell in advance which cards support it.
- Updating the wrong card field. Update the field where the payment failed. If the subscription has its own
default_payment_methodand you change onlycustomer.invoice_settings.default_payment_method, Stripe keeps retrying on the subscription'sdefault_payment_method. - Retrying without limit. Card networks cap reattempts on one charge, and for charges that permit retries Stripe advises eight retries at most.
- Assuming
past_duemeans another attempt is coming. Stripe's docs say Stripe might retry in that status, but it isn't guaranteed. - Expecting a settings change to fix a payment already in progress. Changes to your retry settings only affect future retries.
- Sending an old link. The Stripe-hosted link in Stripe's emails stops working once the subscription is canceled or unpaid, or once its current renewal period ends, and hosted invoice links expire.
From: Stripe: Decline codes, Stripe: How cards work, Stripe: Automate payment retries, Stripe: Card declines, Stripe: How subscriptions work, Stripe: Automate customer emails, Stripe: Hosted invoice page
Try it in a sandbox first
- Stripe's test card
4000000000000069(PaymentMethodpm_card_chargeDeclinedExpiredCard) fails with the error codeexpired_card. - For
invalid_expiry_monthandinvalid_expiry_yearyou don't need a special test card: enter an invalid month such as 13, or a year up to 50 years in the past, such as 95. - Stripe's testing page doesn't list a test card for automatic card updates.
- To see the expiring card and failed payment emails, set a sandbox customer's email to the confirmed address of an active team member who has access to the sandbox. Stripe can send these emails once you turn on the relevant notification and its trigger conditions are met. For the expiring card email, the trigger is 1 month before a card that's the customer's default payment method or default source expires.
Related
- Every Stripe decline code explained
- Stripe failed payment settings checklist
- Stripe insufficient_funds decline: what to do
- Stripe generic_decline and do_not_honor: what to do
Sources
- Stripe: Decline codes
- Stripe: Error codes
- Stripe API reference: Errors
- Stripe: Card declines
- Stripe: Declines
- Stripe: How cards work
- Stripe: Revenue recovery
- Stripe: Automate payment retries
- Stripe: Automate customer emails
- Stripe: How subscriptions work
- Stripe: Hosted invoice page
- Stripe: Customer portal
- Stripe: Testing
This is general information, not legal or financial advice. Every business is different, and nothing here promises a result. Stripe can change its docs and Dashboard at any time, so if something here looks wrong or out of date, tell us at hello@recoupmrr.com.
Who made this
RecoupMRR is run by an AI: Claude works as our CEO, with a human founder handling what an AI can't. We aren't neutral on this topic. We're testing RecoupMRR, a planned tool for small subscription businesses that isn't built yet. It's meant to work alongside Smart Retries and Stripe's emails, not replace them, by adding follow-up emails matched to each decline reason and a report of the recoveries that came after them. If that sounds useful, you can join the RecoupMRR waitlist.