I really hope someone at Square can help me to understand the correct process for creating a subscription plan using the Checkout API. So far, I have had nothing but troubles.
First, I will describe what I need to do, which should seem obvious given that we are creating a subscription:
- I need to send the user to a Square-hosted page to sign up/pay
- I need to then be able to somehow track that the user has paid and is up to date
Following the guide here, I expect that Square will create both a customer object and a subscription object. However, the webhooks that are sent during this checkout process contain no information whatsoever about the customer or subscription, and there does not seem to be anyway to obtain that information afterwards. I cannot retrieve the customer or subscription based on any of the pieces of information sent in the webhooks.
The order objects sent with the webhooks do not contain the customer or subscription information. I would expect that they would, or maybe they do, but only if you specify an existing customer in the inital request? But this is difficult to determine as the sandbox environment behaves strangely, and also because I cannot figure out the correct way to specify both an existing subscription plan in the ‘create payment link’ request in addition to providing a customer id.
Square suggests that I can look up the customer by phone number, which would be great, since our database has their phone number already stored. But the customer could enter any phone number during signup, so this is actually not helpful.
As far as I can see, the only alternative is to create a customer using the customer API and then use that customer ID when sending the ‘create payment link’ request. However, in order to do that, I am required to create an order. So I settled on this code, after creating a customer via the customersAPI:
const checkoutResponse = await checkoutApi.createPaymentLink({
idempotencyKey: randomUUID(),
checkoutOptions: {
subscriptionPlanId: plan.id,
redirectUrl: 'https://our.website',
},
order: {
locationId: locationId,
customerId: customer.id,
lineItems: [
{
quantity: '1',
basePriceMoney: {
amount: costInfo.recurringPriceMoney.amount,
currency: costInfo.recurringPriceMoney.currency
},
catalogObjectId: plan.id
}
],
pricingOptions: {
autoApplyTaxes: true
}
}
});
where plan refers to a CatalogObject which is a subscription type. However, when I make this request, I receive an error response:
INVALID_REQUEST_ERROR
NOT_FOUND
Item variation with catalog object ID `SWWHQL7GVINH2BSBJ76X2Z4P` not found.
However, this subscription plan does exist, as I can confirm in the API Explorer retrieve catalog object endpoint. It’s not clear to me what other order information is required.
So, my question is:
What is the correct way to create a payment link for a subscription plan, using the Checkout API and an existing customer, OR is there some other way that I can retrieve the subscription and customer information after they have successfully subscribed?
I would love some clear explanation as I find the guide that I linked to be lacking in specifics and the API Explorer explanations of what fields are required/mutually exclusive seem to me to be confusing and/or non-existent. Maybe there is something I have overlooked somewhere, I’m not sure. I also have some suggestions:
- The checkout API should allow creation of a subscription payment link using nothing more than this, if an order is created anyway:
const checkoutResponse = await checkoutApi.createPaymentLink({
idempotencyKey: randomUUID(),
checkoutOptions: {
subscriptionPlanId: plan.id,
redirectUrl: 'https://our.website/',
}
}
- I should also be able to add an existing customer id, and/or there should be a webhook that relates the information that was created behind the scenes, like the customer and the subscription
I appreciate any help with this issue! Thanks in advance!
With Subscriptions create with Checkout API you’ll want to listen to invoice webhooks. With the invoice events your get the 