How to handle subscription events?

I have multiple plans that my customers can subscribe to. My application needs to be alerted when the customer’s subscription is activated and each subsequent renewal.

I understand how to create a Checkout link for the subscription.

However, it is entirely unclear after reading through the documentation, how you are meant to handle the subscription.

According to the documentation, the Checkout will automatically create a customer. This does not appear to be the case; perhaps something to do with the sandbox mode? It’s also not clear how I would pass in a customer ID to this endpoint, if that is possible.

I read on this forum to pass in a “reference_id”, but I cannot find where this is mentioned in the documentation.

What is the recommended setup to correlate subscription activation and renewal with the users in my database?

You first want to create a customer and get the customer ID. Then you want to create a card on file using customer ID and card token. Then use both customer ID + Card ID to create the subscription. When you view the customer you will see both the sub and card on file under their account.

With the Square provided payment links for subscriptions we will generate the customer_id and add it to the subscription. The sandbox experience doesn’t exactly mirror production at this time. We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team. :slightly_smiling_face:

Thanks for the response.

How do I test your API if the sandbox is not comparable to the actual site?

If you want to test the Square Dashboard generated subscription links at this time you’ll need to test in production. You can create some $1.00 subscriptions to test and then refund them when you’re finished. :slightly_smiling_face:

The documentation does not adequately say how to handle subscriptions.

And you’re saying I can’t test it without wasting my actual money on every run?

Is there an example application? Anything that shows how to handle subscriptions beyond just creating and deleting them?

All I need to do is:

  • :heavy_check_mark: Create a checkout link for a subscription
  • Associate this subscription with my user
  • Receive an alert when the user has paid or failed to pay

On Square’s competitor’s API, it is incredibly clear how to do this in the docs, with an accompanied example application.

Are you going to be using webhooks to listen for events? If so you’ll want to use the Subscriptions webhooks for any created and updated notifications. For notifications on payments of a subscription you’ll want to listen to Invoices webhooks. :slightly_smiling_face:

I understand that.

The problem is how do I associate the checkout subscription with a user in my database? The http response of the checkout endpoint is unhelpful.

In code.

When the subscription is create the subscription.create event will have the Square customer_id. With the customer_id you can call RetrieveCustomer to get the customer details. :slightly_smiling_face:

How do I associate the new subscription with the user (as in, the user in my database) who created the checkout link?

While creating the checkout link, can I pass in a customer email or UUID? If so, how?


Do you know who the customer is before they subscribe and your wanting to pass a unique ID from your database to identify them after they subscribe? :slightly_smiling_face:

That is correct.

Okay, in that case you can add the customer_id value in your database to the redirect_url. Once the customer pays you’ll get the customer_id and the subscription_id in the redirect. For example if the redirect_url is: You’ll get the following when the customer pays: :slightly_smiling_face:

1 Like

Am I missing a huge section of your documentation???

In which field do I put the redirect url?

“idempotency_key”: “%s”,
“quick_pay”: {
“name”: “xxx”,
“price_money”: {
“amount”: %d,
“currency”: “USD”
“location_id”: “xxx”
“checkout_options”: {
“subscription_plan_id”: “%s”

Please point me to it if I am missing it, but it seems like 40% of the API is undocumented.

It’s in the checkout_options. :slightly_smiling_face:

1 Like

This advice got me BANNED from Square.


What do you mean it got you banned from Square? What’s your application ID so we can take a look? :slightly_smiling_face: