How Do I Fix the "Charges original charge refundable subtotal in cents must be greater than or equal to 0" Error?

This error occurs when a subscription's next bill date was modified prior to an attempt to move the subscription to a new plan. When the timing of the plan change is set to take effect immediately, the system attempts to prorate the charge but is unable to due to the prior change in the bill date.

To resolve this issue and upgrade the subscription, you have several options:

Recommended Solutions

• Upgrade the subscription and then adjust the bill date. Upgrade the subscription from the old plan to the new plan and set the timing to take effect immediately. This will result in prorated charges and credits being applied based on the time spent on the prior subscription. Afterward, you can adjust the next bill date if needed.

• Upgrade at the next renewal. Upgrade the subscription from the old plan to the new plan and set the timing to take effect at the next bill date. Then, adjust the next bill date as needed.

• Upgrade at the next term end. Move the subscription from the old plan to the new plan, but set the timing to take effect at the next bill date or term end.

• Terminate the old subscription. You can completely terminate the old subscription, issue a partial refund if needed, and then apply the new subscription to the account.

Workaround for Special Use Cases

If your goal is to give a customer a free billing cycle on their existing plan before upgrading them to a new one, you can use the following multi-step process:

1. Grant the Free Month: Change the next bill date to accommodate the additional free month, or apply a coupon that fully discounts the next renewal.

2. Cancel the Old Plan: Set that subscription to cancel at the next_bill_date so that your customer is no longer billed for it.

3. Apply the New Plan: Apply the new, upgraded subscription to the account with a future start date. The new plan will begin once the old subscription is canceled/expires at the next renewal date.

With this method, you are still giving your customer the free month as promised, and they will be seamlessly upgraded to the new plan on the future start date.

Monitoring for Declined Payments

If the customer's payment for the new plan declines, you can monitor for this with webhooks. Consider listening for the failed_payment_notification and the new_dunning_event_notification webhooks. Listening for these webhooks allows you to query the API for additional account details and, if needed, prevent access to the upgraded plan.

These events will also trigger the Payment Declined or Invoice Past Due email notifications, if enabled, which are associated with your Dunning Management Settings and are designed to encourage customers to update their billing information. You can find these email templates under the Configuration tab in the Recurly Admin Console. You can also include the parameter {{transaction_decline_details}} in the email template to indicate the specific reason for the payment decline and how they can resolve it.