Delinquency Management

Failed payments on recurring subscriptions introduce involuntary churn and increase your costs. Using our Billing API, we provide precise control over how to handle unpaid invoices, letting you balance risks with user experience:

• Issue invoices at renewal or days in advance
• Offer grace periods with full connectivity while awaiting payment
• Apply restrictions to delinquent subscriptions to minimize costs

Invoicing in advance

By default, invoices for subscription renewals are created after the subscription renews. This means users will start receiving connectivity for the new period before they have completed the payment, which could result in unrecoverable costs if they never pay.

To prevent this situation, you can choose how many days in advance you want to issue the invoices, as well as what happens at renewal when the invoices are not paid.

Lifecycle of an unpaid Invoice

When you fail to collect payments for recurring invoices, you can decide how much time to wait and reattempt to collect the funds before the subscription is automatically ended. This recovery period is composed of a grace period, followed by an overdue period. You can choose the length of both or disable them completely.

Grace Period

The grace period starts immediately at renewal and allows subscribers to retain complete access to their plan while you attempt to collect payment. It can be configured at the project level using the gracePeriodDays setting, but can be overridden per subscription when a different delinquency configuration is needed for specific users.

When subscribers pay during this period, the renewal date stays the same and subscriptions remain in active status. If payment isn't collected by the end of the grace period, the invoice becomes overdue and the overdue period begins.

Overdue Period

After the grace period ends, the overdue period begins. During this time, you can decide whether subscribers retain full access to their plan or face restrictions on their actions and allowances to reduce costs and encourage payment. In the same way as the grace period, it can be configured using the overduePeriodDays setting at the project level, or overridden per subscription.

You can choose how long this period lasts or skip it entirely, which ends subscriptions immediately. Subscribe to the invoice.willBeOverdue and invoice.overdue events to be notified when this happens.

Restriction

During the overdue period, you can reduce subscription connectivity by restricting subscriptions. Restricted subscriptions have a restricted status, limited allowances and cannot take actions such as replacing a SIM or changing their base plan. We currently support three restriction modes that can be configured using the restrictBehavior setting:

• Incoming only: Can only receive incoming calls and SMS, without being able to make outgoing calls, send SMS, or use data
• Talk & Text: Can make calls and send SMS using the same limits as the original plan, but cannot use data
• Throttled Data: Can make calls and send SMS using the same limits as the original plan, and use up to 1GB of data with speed throttled to 256kbit/s

Once overdue invoices are paid, subscriptions are automatically restored and become active again. You can subscribe to the subscription.restricted and subscription.restored events to take action when this happens.

Resetting the renewal date

When subscriptions are restored, you can choose whether to maintain the original renewal date or reset it to provide users with a full period of connectivity using the restoreBehavior setting. When the date is reset, the period anchor changes to the current moment, ending the current period and creating a new one immediately.

We also credit the original invoice and issue a new one that accurately reflects the new period and renewal date.

1. Old invoice credited: A credit note is issued for the original paid invoice with creditTo: userBalance. You don't need to take any action on this credit note.
2. New invoice issued: A new invoice is created for the new period with reason: subscriptionRestore. You don't need to take any action on this invoice either.

The new invoice is immediately paid using the credit from the previous invoice, which means that you don’t need to take any action to handle the credit note or invoice.

Choosing the right configuration

By combining advance invoicing with grace and overdue periods, you can create flexible billing scenarios that fit your desired experience. Here are some common configurations:

• Invoice at renewal and provide a grace period with full connectivity
• Invoice a few days before renewal and restrict connectivity while payments are not made
• Invoice a few days before renewal and end unpaid subscriptions right away

To decide how many days in advance to create invoices, how long the grace and overdue periods should be, and which action to take when an invoice becomes overdue, consider these factors:

• Estimate the average time it takes to collect funds from your users.
• Account for potential delays, such as unexpected downtime.
• Consider how much time your users typically need to resolve payment issues.
• Assess how subscription termination impacts your user experience.

Limitations

• Invoices cannot be issued more than one period length in advance.
• Invoices are not issued in advance if unpaid renewal invoices already exist.
• The combined grace and overdue periods cannot exceed the plan period length.
• Changes on the delinquency settings only affect future invoices.
• Restriction is not yet supported on all providers.
• Connectivity may be lost for up to 30 minutes during restriction and restoration.