Need help Understanding Square Subscription API and SDK


I’m trying to build a subscription inside our app using Square payments (I’m coming from Stripe which is a bit different) and have some questions that I could not figure out in terms of feasibility.

Most important question:
Can I process the credit card subscription charge through my own interface or is it always have to be through a square hosted invoice? (not sure if this post is still valid or the Web payments SDK is valid for subscriptions)

I don’t see in the subscription documentation where the customer would put their credit card info in my app, it seems like they’d only get an invoice with a payment link on their email or I can only charge them if we already have a credit card on file

If there’s a way I can create my own interface where customers enter their credit card information, proceed to these questions please :slight_smile:

  1. Is this event to cancel the subscription of one user or does it cancel the subscription plan? I don’t see where to enter the customer ID of the person who wants to cancel the subscription POST /v2/subscriptions/{subscription_id}/cancel - Square API Explorer POST v2/subscriptions/{subscription_id}/cancel

  2. If a subscription is not paid automatically on the day it’s due: is there a way to fire a subscription cancellation for that user automatically? We offer unlimited coffee, so if we don’t get paid we need to cancel that subscription immediately so that only paying subscribers can get the coffee.

  3. is there a specific webhook to only listen to subscription update events? Would this “update subscription” ping us so that we update the number of credits of a user or the subscription status of a user if they have paid their subscription?

  4. If I already have an existing customer on my square and i create another customer with the same email, name, and phone number in order to subscribe him: will that trigger an error? Or can I create a second customer with the same data and that one is the one who is using the subscription?

Thank you very much

:wave: With Square Subscriptions API invoices will be the mechanism that will charge or bill the customer. The Payments API isn’t used for subscriptions. During your onboarding flow you’ll want to have your customer save the card on file with the Web Payments SDK and Cards API prior to creating the subscription. Then you’ll have the card_id for the customer to pass in at the time of subscription creation. :slightly_smiling_face:

  1. The event to cancel a subscription is to cancel that customers subscription. Not the plan. The customer_id is part of the subscription which is why it’s not needed in the cancel POST.

  2. Canceling a subscription won’t cancel it immediately. It will still be active till it’s charged_through_date However you’re application can subscribe to Invoice webhooks to be notified when a webhook subscription isn’t paid and disable the customers ability to get coffee based on the invoices payment status.

  3. Any creation or updates to the subscription will trigger a Subscription webhook event. Any payment of a subscription will trigger an Invoice, Payment, and Order webhook events.

  4. Creating a duplicate customer won’t error out. You’ll have a duplicate and should be aware of any merge events of duplicate profiles.

When duplicate customer profiles are identified and merged, either manually by the seller or using automated detection, the existing profiles are merged into a single profile that is assigned a new ID.

If you specify the ID of a customer profile that was deleted in a merge operation, the Customers API returns the new customer profile. For example, suppose customers A and B are merged and a new customer C is created. If you call RetrieveCustomer using the ID of customer A or B, the Customers API returns customer C.


Thank you very much @Bryan-Square, appreciate the detailed help from you :slight_smile:

When the customer enters the credit card details into the Web Payments SDK to have the card on file. can I create a subscription for that customer at the same time that the customer has submitted his credit card information?

I’m thinking it’s a strange UX to have someone put in their credit card, press save, and then have to press “subscribe” again.
Could I just ask them for their credit card to save the card and in the same button inside the web payment SDK also create the subscription?

  1. Duplicate customers:
    If a duplicated customer is merged by the staff of the café I will get notified with the merge context when the customer is created, but will the credit card on file still be stored on the newly created customer when a duplicate customer is merged?

Yes, you can absolutely save the card on file and then create the subscription all in one checkout experience for the customer. Once the customer submits their card information in the Web Payments SDK your server will take the generated token from the Web Payments SDK and call CreateCard. Once it has the card_id from that call your server can then call CreateSubscription.

As for merged customer profiles the card on file will still be stored on the customer profile. Merging won’t disable the card. :slightly_smiling_face:

Hi there @Bryan-Square, following up on this conversation, I was wondering how you would go about the following scenario:

I have a new customer that visits my site for the first time. They get an online quote to get their house cleaned “Every two weeks” (subscription). After finishing the quote form, the customer lands on the final Checkout page and is ready to pay.

The customer will enter his email, phone number, and card information and hit PAY.

Should my code do this?

1- Check if the customer exists, if it doesn’t, then create a new customer.
2- Save the card on file for that new customer.
3- Create a new subscription associated with this new customer. (Based on an existing plan)

Does this sound like too much for a checkout page?
Would you use a different flow/approach?

Thank you in advance!

You nailed it! That’s the recommended workflow. :slightly_smiling_face:

1 Like