Subscription ID in invoices

Hi there,

As far as I can tell, Subscriptions API appears to be built on top of Invoices API, so I am tagging both in hopes it is specific enough.

Our subscription service requires the subscription to be paused immediately when a payment fails. As this is not the default behavior of the Subscriptions API, I am attempting to manually pause the subscription.

Pausing a subscription requires the subscription ID. I am currently subscribed to the invoices.scheduled_charge_failed webhook. Can I access the subscription ID directly from the invoice? Or do I need to retrieve the invoice separately? Also, does an invoice recognize the difference between a subscription and, say, some other type of service?

TLDR; How do I access a subscription ID from an invoice?

: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

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.

I see that you’ve marked the documentation as a solution. Were you able to get the answer from the documentation?

Also please note that the invoices.scheduled_charge_failed event won’t fire with failed subscription payments. It’s for recurring invoices which is a separate feature then the Subscriptions API. :slightly_smiling_face:

Yes, I saw in the docs that the subscription_id will be passed in the response if the invoice is a subscription.

But with invoices.scheduled_charge_failed not working with subscriptions, which webhook am I looking for? It is essential to know when a payment fails.

Discovered that the answer is in payments.updated, where you filter for failed payments. If anyone needs help with this issue in the future

Yes, the payments webhooks will be what you’ll want to listen to for any failed payments. Which will also include failed invoice payments. :slightly_smiling_face:

Last question on this,

If a subscription is scheduled to begin at a future date, if the card on file fails for that initial charge (attempting to activate the subscription) on that date, will that also trigger a payments.updated webhook event?

It will trigger a payment.created webhook for the failed payment. :slightly_smiling_face:

Ok just so I’m clear-

A subscription fails to be created due to a failed payment: payment.created

A recurring subscription charge fails due to a card on file failing: payment.updated

A subscription that failed a charge, but is being paid for by an invoice emailed by Square: invoice.payment_made

Not exactly. The subscription is already created. It’s the scheduled payment that failed. That failed payment will trigger a payment.created event. We will send the customer an invoice. They can then pay through the invoice which will trigger invoice.payment_made, payment.created, and payment.updated events. :slightly_smiling_face:

Got it. So listening to the invoices webhook isn’t necessary, because the payments webhook will also catch the events.

So simply listening the payment.created and payment.updated will cover all the potential subscription scenarios(?)

Yes, with card on file subscriptions it will. If a subscription doesn’t have a card on file you may want to listen to invoices webhooks so you know when they’re sent to the customer. :slightly_smiling_face: