Clarification Needed on Handling Payments and Invoices with Square Subscriptions API

Hello,

I’m currently integrating Square’s Subscriptions API and have encountered some challenges understanding the relationship between subscription statuses, payments, and invoicing, particularly when dealing with failed payments and resuming subscriptions.

Here’s a specific scenario: A subscription payment fails due to an expired credit card, and we respond by setting the subscription status to “PAUSED.” This prevents the subscriber from accessing the benefits until the issue is resolved. Suppose several months later, the subscriber updates their payment method and wishes to resume their subscription. I have a few questions regarding how to handle the payments in such cases:

  1. Invoicing and Payments: Are all subscription payments handled as ‘invoices’ in the Square system? Does a failed payment mean that an invoice remains unpaid, and do we need to retrieve and settle this specific invoice when the subscription is resumed?

  2. Resuming Subscriptions: Upon resuming a subscription after a payment failure, what exactly is the subscriber paying for? Are they clearing a past due, or does the subscription restart from the resume date?

  3. Subscription Status vs. Payment: It seems there isn’t a direct link between subscription status (e.g., “PAUSED”) and the payment processes. Could you elaborate on how these elements should be effectively managed to ensure continuity and compliance without providing benefits to those who haven’t paid?

Any insights or documentation that could help clarify these points would be greatly appreciated. Ensuring we manage subscriptions and payments correctly is crucial to avoid inadvertently offering services without proper compensation.

Thank you!

: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:
https://developer.squareup.com/docs/app-marketplace/requirements/subscriptions-api

Additional Documentation

Invoices API Overview
Create and Publish Invoices
Square Developer

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.

  1. Invoicing and Payments: Yes, all subscription payments are handled as ‘invoices’ in the Square system. When a subscription payment fails, the corresponding invoice remains unpaid. However, when the subscription is resumed, you don’t need to settle the specific unpaid invoice. Instead, a new invoice is created for the new billing period.

  2. Resuming Subscriptions: When a subscription is resumed after a payment failure, the subscriber is paying for the new billing period. The subscription restarts from the resume date, not from the date of the failed payment. Any past due is not cleared when the subscription is resumed.

  3. Subscription Status vs. Payment: You’re correct that there isn’t a direct link between subscription status and the payment processes. The subscription status (e.g., “PAUSED”) is managed independently of the payment processes. When a subscription is paused, existing subscriptions continue to work but you cannot add new subscriptions. If a payment fails, you should manually pause the subscription to prevent the subscriber from accessing the benefits. When the subscriber updates their payment method and wishes to resume their subscription, you should manually resume the subscription. This ensures that you’re not providing benefits to those who haven’t paid.

This answer was reviewed by @Bryan-Square.

I am really struggling to understand how these invoices are settled over durations of time.

As far as I can tell, ResumeSubscription does not handle anything related to the payment of an invoice. Calling ResumeSubscription will change the status of the subscription to ‘ACTIVE’, but I still don’t understand how we have settled the charge.

Square sends an invoice to the customer that will let them pay for the invoice. This will also update the card on file moving forward, but if this action takes months to complete, I don’t understand what the customer is paying for, what is considered settled, or how the flow of the subscription works.

If a subscription is on a monthly billing cadence, with a monthly anchor date of the 1st of each month, and the automatic payment fails on January 1st, and we then pause the subscription, what happens when the customer tries to resume their subscription on April 12th?

•	Are we settling the January invoice?
•	Does the anchor date change to the 12th of each month?
•	Why are we resuming the subscription before we have settled the payment?

I need a clear understanding of how to manage these scenarios to ensure we are billing our customers correctly and maintaining accurate subscription statuses.

That’s correct, resuming a subscription doesn’t handle anything related to payments. It will activate the subscription. On the next billing cycle the customer will be billed for the subscription period.

Square will send an invoice to the customer to pay. Unfortunately it won’t update the card on file for the subscription. You’ll have to do this with the API.

If a subscription is on a monthly billing cadence, with a monthly anchor date of the 1st of each month, and the automatic payment fails on January 1st Square will send the customer an invoice. If you pause the subscription and customer wants to resume their subscription on April 12th its your application that would resume the subscription. You don’t have to resume the subscription till the invoice is paid for the failed payment. Or if it is resumed and not paid then the amount due of the previous invoice will be added in the next billing cycle along with current amount due. :slightly_smiling_face:

Hi Brian,

I have noticed, at least anecdotally in the sandbox environment, that when a subscription is paid by invoice, the card on file is updated to the new payment method in the subscription details on the dashboard. I haven’t needed to update the payment method through the API in this scenario. Am I mistaken here?

Regarding invoices: In our situation, an invoice is generated due to a failed payment, and we then pause the subscription to prevent multiple invoices from becoming due if a customer takes several billing cycles to update their payment method. Are we still able to settle that initial failed invoice for January? It seems that a payment must be settled before we would want to unpause a subscription.

If this is the case, will Square continue to bill as normal with the new card on file?

Example scenario:

  1. January 1st: Payment fails. An invoice is generated for the January 1-31 payment and emailed to the customer. The webhook fires and the subscription is switched to “paused”.
  2. April 12th: The customer wants to reactivate their subscription. They open the email sent by Square in January and pay that invoice.

What happens now?

  1. Does Square update the anchor date to the 12th of each month?
  2. Does Square immediately invoice the April payment?
  3. Does Square understand that the January invoice being paid has an effect on the subscription?
  4. Does the Square system care about the relation between the invoice and the subscription status, or is there an additional step I need to handle on my end?

I guess ultimately what I’m asking, is what exactly triggers an invoice when we get knocked off of a successful automatic payment cycle for a duration longer than a single billing cycle.

Thank you,

When a subscription payment method fails to successfully charge the card on file that is when we will send the customer the invoice. Other then that all the other logic is up to your app. When the subscription resumes after being paused we will not bill for the paused periods. :slightly_smiling_face:

But you will bill on the original anchor date? Or does the anchor date change to the new payment date?

Yes, when the subscription resumes we will bill on the anchor date moving forward. :slightly_smiling_face: