Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stigg.io/llms.txt

Use this file to discover all available pages before exploring further.

When a subscription renewal payment fails, Stripe can automatically retry the charge to recover the revenue. Stigg reflects the resulting subscription state changes in real time as Stripe works through its retry cycle.

​
How it works

Stigg delegates payment collection and retry logic entirely to Stripe. When Stripe retries a failed invoice:
  1. Stripe attempts the charge according to your configured retry schedule.
  2. On each retry attempt, Stripe emits an invoice.payment_failed webhook.
  3. Stigg receives these events and keeps the subscription in an Active + Payment error state while retries are ongoing — the customer retains access to their current entitlements during this period.
  4. If a retry succeeds, the subscription returns to a normal Active state.
  5. If all retries are exhausted, Stripe transitions the subscription based on your recovery failure settings, and Stigg reflects that final state immediately.
During the retry cycle, Stigg does not revoke entitlements. Access is only removed once Stripe marks the subscription as canceled or unpaid.

​
Configuring retries in Stripe

Go to Billing > Revenue recovery > Retries in the Stripe Dashboard to configure the retry policy. Stripe offers two retry modes: Stripe’s AI-powered retry engine selects optimal retry times based on signals such as card activity patterns and time-of-day success rates. You configure only:
  • Number of retries: how many attempts Stripe should make.
  • Maximum duration: the window within which retries occur (1 week, 2 weeks, 3 weeks, 1 month, or 2 months).
Stripe’s default is 8 retries within 2 weeks, which is the recommended starting point.

​
Custom retry schedule

If you prefer full control, you can define up to three retry attempts, each a specific number of days after the previous one. This is less adaptive than Smart Retries but gives you a predictable timeline.

​
What happens when all retries are exhausted

When Stripe’s retry cycle ends without a successful payment, it transitions the subscription to one of three states depending on your Stripe configuration:
Stripe settingStripe subscription stateStigg behaviour
Cancel the subscriptioncanceledStigg cancels the subscription and revokes all entitlements
Mark the subscription as unpaidunpaidStigg keeps the subscription in Payment error state; entitlements are retained
Leave the subscription overduepast_dueStigg keeps the subscription in Payment error state; future invoices continue to be generated
Stigg recommends using “Cancel the subscription” or “Mark as unpaid” as the failure action. Leaving subscriptions past_due indefinitely can result in accumulated unpaid invoices and may confuse entitlement state for your customers.

​
Payment method ordering

When Stripe retries a payment, it uses the first available payment method in this priority order:
PriorityPayment method
1Subscription default payment method (subscription.default_payment_method)
2Subscription default source (subscription.default_source)
3Customer invoice default payment method (customer.invoice_settings.default_payment_method)
4Legacy customer default source (customer.default_source)
If a customer updates their payment method after a failure, make sure to update it at the same level where the previous attempt failed. For example, if the subscription has a default_payment_method, updating only customer.invoice_settings.default_payment_method will not cause Stripe to use the new card — it will continue retrying on the subscription-level method. You can update a customer’s payment method in Stigg, which will propagate the change to Stripe: 
await stiggClient.updateCustomer({
  customerId: 'CUSTOMER-ID',
  billingInfo: { paymentMethodId: 'NEW-PAYMENT-METHOD-ID' }
});

​
Hard decline codes

Stripe will not successfully execute a retry if the card issuer previously returned a hard decline (e.g. lost_card, stolen_card, incorrect_number). Retries remain scheduled and attempt_count increments, but the charge only executes if a new payment method is provided. If a customer is stuck in a payment error state due to a hard decline, prompt them to update their payment method via Stripe’s Billing Portal or your own checkout flow.

​
Receiving payment failure notifications

You can listen for failed payment events from Stigg using the customer.payment_failed webhook. This is useful for notifying customers, triggering support workflows, or updating your own systems.

Integrate Stigg with additional applications using webhooks

Handling payment errors