Hello, I’m building a subscription system but need your help understanding the subscription wording and how it works:
Questions on wording:
a) deactivated subscription = the customer who was subscribed is no longer subscribed and the subscription plan remains available to other customers?
b) Subscription updated refers to the event when a customer who is paying for a subscription gets charged for a second or consecutive time? Is the first time a customer’s card gets charged from a subscription also considered a subscription updated event and will the API fire in that case?
c) If a customer subscribed on the 15th of June for a monthly subscription, will he get charged on the 15th of July at the end of the month of July? If I understand this article by Square correctly, he would get charged at the end of the month but it feels odd.
When a subscription update happens in a subscription (aka when a customers card has been charged for a second or consecutive time, but not the first time - subscription creation):
Which webhooks do I need to listen to? If it’s invoice.payment_made → how can I differentiate if this is a payment from a subscription and how can I check if it’s the first payment or a consecutive payment?
a) That’s correct. The individual customer is no longer subscribed, but the subscription plan as a whole remains available.
b) The subscription.updated event is for when the subscription object itself changes (for example, the status changes from ACTIVE to CANCELED). Since subscriptions send invoices for payment, you can use the invoice.payment_made webhook to know when the customer is charged.
The invoice.payment_made webhook will contain a subscription_id field when the payment was for a subscription. If you retrieve that subscription via RetrieveSubscription, there should be an invoices_id array that lists all invoices sent for the subscription from newest to oldest.
c) For a customer that starts a subscription on June 15, they will get charged immediately on June 15. They will be charged again on July 15. The part of the documentation you linked refers specifically to situations where the date that would normally be billed does not fall within that month. For the example given in the docs, if the subscription starts on May 31, Square would normally try to bill again on June 31 — but since June only has 30 days the next bill is sent on June 30 instead.
So when I retrieve the subscription, the charged_through_date is the day until which the subscription is paid, correct?
So if the subscriber paid on June 15 for a monthly subscription, the charged_through_date will be July 15, right?
Hey @axme, one quick clarification: The charged_through_date is the date through which a customer has been invoiced. There’s a possibility that a customer does not pay the invoice immediately, meaning the date that they were invoiced and the date they paid are not necessarily the same.
Sorry about that miscommunication! Let me know if there’s anything I can clear up.
In case a customer does not pay the invoice immediately, will the charged_through_date change only when the customer has successfully paid for the new billing cycle?
Meaning:
I subscribed from 12th of January to 12th of February (monthly subscription)
I don’t pay the invoice on the 12th because my card had no money
I pay on the 15th of February
→ what is my charged_through_date on Feb 13th? will it be feb 12th?
→ what is my charged_through_date on Feb 16th after I paid? 15th of march
