Subscription Retries
The subscription retries function enables personalized retry settings when subscription-generated installment orders encounter issues. For example, if your customer's payment doesn't go through, the system will automatically make additional attempts based on the customized settings configured in your Store Variables.
When a subscription exceeds the maximum number of retries, Chord will automatically cancel the subscription. This prevents the system from constantly retrying subscriptions that have not be fixed and improves the accuracy of the number of active/valid subscriptions in the system.
Chord OMS will never cancel subscriptions due to out-of-stock failures.
A subscription installment order may fail for three reasons:
- Payment failure: this is the most common type of failure, which occurs when a payment cannot be captured with the card associated with the subscription (e.g., the card has expired or the issuing bank declined the payment).
- Out of stock: one (or more) of the subscription line items is out of stock.
- General failure: captures every other type of failure that could occur.
Navigate to your Settings --> Store --> Environment Variables.
Scroll down and add the following:
Setting | Value | Note |
|---|---|---|
SUBSCRIPTION_REPROCESSING_ENABLED | enabled/disabled | Enables/disables subscription retries within Chord. |
SUBSCRIPTION_MAXIMUM_REPROCESSING_COUNTER | Integer | Maximum number of days that a subscription can be reprocessed. After that time, the subscription will be auto-canceled. Value can be set up to a maximum of 5 days. The default value is 5. If this value is 0, Chord will not retry the subscription installments and the subscription will be automatically canceled after the first failure |
SUBSCRIPTION_REPROCESSING_INTERVAL | Integer | Determines the number of days Chord will wait before reprocessing a failed installment. The range is between 1 and 7, and the default is 1. For example, if this value is 5 and a subscription installment is generated and fails on January 1, the system will NOT attempt to reprocess that failed installment until January 6. (5 days) |
What does this mean?
To enable subscription retries, set the SUBSCRIPTION_REPROCESSING_ENABLED variable to enabled. Failed subscription installments will now be automatically retried on the next day.
If this value is disabled, failed installments will not be reprocessed. When an installment fails, Chord will pause the subscription to prevent future installments from generating (i.e. prevent abandoned subscriptions from continuing to process forever). If transactional emails are enabled, Chord will send an email to the customer about the failed installment.
When enabled, the subscription retry functionality can be adjusted in a few ways. Chord OMS will not retry the installment when theSUBSCRIPTION_MAXIMUM_REPROCESSING_COUNTER value is set to 0. The installment state will be unfulfilled, the order state will be canceled, and the subscription will be canceled (i.e., no further installments will be generated).
When the SUBSCRIPTION_MAXIMUM_REPROCESSING_COUNTER value is > 0 or Undefined, and the subscription has not had any previous failures when an installment fails
- Chord OMS will retry processing the installment the following day.
- Chord OMS sends an event to Segment, depending on the type of failure (see below).
- Chord OMS logs a subscription event noting the failure, viewable on the Subscription page in Chord OMS.
- Chord OMS emails your customer about the failure (if enabled in your store).
When the SUBSCRIPTION_MAXIMUM_REPROCESSING_COUNTER is reached and an installment fails:
- Chord OMS will not retry the installment.
- Chord OMS repeats the same steps mentioned above when an installment fails.
- Chord OMS cancels the subscription and sets the Actionable Date to blank/null.
- Chord OMS sends a Subscription Canceled event to Segment
- Chord OMS logs a subscription event, noting the subscription is canceled, viewable on the Subscription page in Chord OMS.
- Chord OMS sends an email to the customer that the subscription is canceled
In the example below, you can see this subscription order has a failed event due to an out-of-stock item; The installment_out_of_stock event type indicates the reason for the failure. A more detailed explanation can help you identify the issue.
The Retry Installment function allows a store admin to retry the subscription immediately without having to wait for automatic reprocessing the following day. This can be useful for testing or if a customer updates their payment method on their subscription and requested the subscription be retried immediately.
Suppose the SUBSCRIPTION_MAXIMUM_REPROCESSING_COUNTER is configured with a value greater than 0 but equal to or less than 5. In that case, the installment will undergo another retry the following day.
However, if you want to initiate the installment processing immediately, you can click on the Retry Installment button, which will again trigger the processing of the installment.
When an installment fails, Chord will emit the below events to Segment:
Event Name | Description |
|---|---|
Subscription Payment Failed | Payment failure |
Subscription Out of Stock | Out-of-stock failure |
Subscription Failed | General failure |
Subscription Cancelled | The subscription was canceled because the maximum reprocessing time threshold was met |