Help with Subscription API testing


I’m encountering challenges while testing the Subscription API in Sandbox, specifically related to simulating different failure scenarios. I’ve noticed there isn’t an option to assign a failing card to a subscription, which complicates testing how the API handles scenarios like expired or lost cards.

Could you advise if there’s a method to deliberately trigger a failure for a recurring charge associated with a card on file? This functionality is crucial for testing the webhook that manages failed subscription events.

Additionally, I’m curious about the behavior of the subscription.updated webhook event when a subscription is paid via an invoice after a card failure. Is subscribing to invoice webhook events also necessary?

Another concern is the handling of paused subscriptions. They are scheduled to pause at the end of the billing cycle, but since this typically coincides with failed payments, does the pause take effect immediately? We need to ensure that the service is inaccessible to delinquent subscribers immediately after a payment failure. Currently, the system still marks the subscription as ‘active’ despite payment delinquency.

Ideally, I believe a delinquent subscription should be automatically paused, but that’s a separate enhancement request.

Thank you for your assistance.

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Payments API Webhooks
Gift Card Webhooks
Test in the Sandbox

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

The Subscriptions API currently does not support the ability to simulate a failed payment scenario in the Sandbox environment. This means you cannot assign a failing card to a subscription to test how the API handles scenarios like expired or lost cards.

As for the subscription.updated webhook event, it is triggered when a subscription is updated, including when a payment is made via an invoice after a card failure. However, to track successful or failed invoice payments, you would need to subscribe to the corresponding invoice webhook events.

Regarding paused subscriptions, when a subscription is set to pause, it does so at the end of the current billing cycle. If a payment fails, the subscription status remains ‘active’ until the end of the billing cycle, even if the customer is delinquent. The system does not automatically pause a delinquent subscription.

Your feedback about automatically pausing delinquent subscriptions is valuable and I recommend submitting this as a feature request through the appropriate channels for consideration in future updates.

This answer was reviewed by @Bryan-Square.