The steps for Subscription Plan Checkout vs Subscription Plans and Variations seem to conflict so I am not clear on the proper steps needed.
Specifically, the Subscription Plan Checkout doc article makes absolutely no mention of plan variations and the steps include setting the price when creating the subscription plan.
Whereas the Subscription Plans and Variations doc article says you explicitly need a subscription plan variation.
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
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.
At this time this is how to create a subscription payment link with the Checkout API for all versions 2023-06-08 and newer.
{
"idempotency_key": "{{$guid}}",
"quick_pay": {
"name": "Coffee membership fees",
"price_money": {
"amount": 100,
"currency": "USD"
},
"location_id": "{{location_id}}"
},
"checkout_options": {
"subscription_plan_id": "WJZ33ATP5ER36Y6Y2ZIE33SZ" //is the subscription_variation_id
}
}
What if there is a trial period or initial setup fee - that all needs to be associated with the Subscription Plan Variation first and then the Quick Pay information passed to create the payment link and includes the recurring cost via the price_money?
If that’s the case you can create a variation that has multiple phases like the following:
{
"idempotency_key": "{{$guid}}",
"object": {
"id": "#1",
"type": "SUBSCRIPTION_PLAN_VARIATION",
"subscription_plan_variation_data": {
"name": "Coffee Month",
"phases": [
{
"cadence": "WEEKLY",
"ordinal": 0,
"periods": 1,
"pricing": {
"price_money": {
"amount": 100,
"currency": "USD"
},
"type": "STATIC"
}
},
{
"cadence": "MONTHLY",
"ordinal": 1,
"periods": 2,
"pricing": {
"type": "STATIC",
"price_money": {
"amount": 200,
"currency": "USD"
}
}
}
],
"subscription_plan_id": "ATZTVO7BLE6AV37DJ7K3FRVZ"
}
}
}
I’m more unclear on why we are setting a price on the Subscription Plan Variation AND the Quick Pay. Why both?
If it’s not set you’ll get a MISSING_REQUIRED_PARAMETER error. The quick_pay amount will need to total the amount the amount that the customer will be charged for the subscription.
Sorry, that added more questions than answers again unfortunately.
So when I define a Subscription Plan Variation, I need to set the initial price (sign up fee) paid at checkout and the recurring price?
The Quick Pay also needs to define the initial price or the recurring price - I am not clear?
I am also getting the following error that isn’t clear at all:
“For Square-Version 2024-12-18, phase pricing must be set on the Pricing field instead of Recurring Price Money”
My code for creating a subscription payment link can be found here: pmpro-square/classes/class.pmprogateway_square.php at dev · derekashauer/pmpro-square · GitHub
I got the unknown error to go away, but I am still not clear where I assign the recurring billing amount and the initial payment amount.
Every time I get a successful payment link to be generated and complete the test, no subscriptions ever actually show at https://app.squareupsandbox.com/dashboard/subscriptions-list - should they appear there?
This is expected when testing payment link subscriptions in sandbox. It’s an incomplete experience and won’t actually create the subscription you see in the Dashboard. In production it works as expected.
Oh boy, so no way to confirm actual subscriptions are being created until we do live payments? That’s a bit bonkers to me.
If I set the Subscription Plan Variation to have a phase at $150 per year and the Quick Pay to be $100 for the initial amount - all it shows me is a payment for $100 and no mention of the $150 anywhere on the actual payment page. Here is what I see: CleanShot 2025-01-14 at 16.30.07 · CleanShot Cloud
Without subscriptions being shown in the Dashboard, I have absolutely no way to know if this is actually working.
Also, if no subscriptions ever get created how can I test receiving successful recurring payment webhooks?
Unfortunately, due to the way the payment links work in sandbox there isn’t a way to test webhooks and seeing it in Dashboard. What I do to test is to set every phase to $1 and use production to create the subscription. 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.
Ok, but how on earth am I supposed to know if I am making these subscription payment links correctly? There is nothing in the UI to indicate the recurring amount. Users absolutely need to know the exact terms they are subscribing to on that checkout payment link.
At the top of the UI it will display when the first phase ends with the quickpay amount you passed in.
Then when the customer pay for that it will send a confirmation the the buyer that includes the details of the other phases:
So mine is not doing that and now I have absolutely no idea what I am doing wrong to create these subscription links. I’m back at square one I guess.
Are you in production?
Oh my, I have been going round and round pulling my hair out for days. There needs to be a very clear mention that nothing about subscriptions works in Sandbox and you have to test in Live. It would have saved me an immense amount of stress and time.
That said, I do see the subscription terms now on the checkout when using Live - however, they are the wrong subscription payment amounts. It is only using the initial payment as the recurring payment and does not indicate a difference between the two.
So how do I differentiate an initial payment amount and then recurring amount? For example, $150 for the first payment and then $100 each month there after.
You gave me an example of setting up two phases earlier, but one was was for a 1 week phase and then every month which did not align with my example so I wasn’t clear on what the point of that was.
The point of the multiple phases was to give an example of what you can do with phases. What are the phases you need?
The reason for setting a quick pay amount and having the price set in the plan variation is requirement when using the payment links to create subscriptions. It’s just the way it’s engineered. If you’d like to create a custom UI and checkout experience that display’s all aspects when customers setup subscriptions we recommend using the Subscriptions API, Web Payments SDK, Customers API, and Cards API.
Any updates to subscriptions after they’ve been created will be with the Subscriptions API. You can swap plans with the adjusted periods.
The point of the multiple phases was to give an example of what you can do with phases. What are the phases you need?
I need the ability to set up an initial payment that is $150 at time of checkout and then $100 on a recurring yearly basis after that. This is just one example - I need to be able to set up any kind of subscription scenario but I am starting with this one to get my head wrapped around this API.
The reason for setting a quick pay amount and having the price set in the plan variation is requirement when using the payment links to create subscriptions.
That’s fine, but in my scenario where do I put the initial payment and where do I put the recurring amount? I have tried lots of things and nothing is yet working.
Any updates to subscriptions after they’ve been created will be with the Subscriptions API.
If I need to change my above example from $150 to start and $100 recurring every year to $75 to start and $50 recurring every month - how do I do that? I am not looking to change existing customer subscriptions, but the pricing and/or timing of the core subscription plan variation for future customers who sign up for it.
Okay, if you need to charge $150 on signup and then a year later charge $100 you’ll have to create a SUBSCRIPTION_PLAN_VARIATION like this:
{
"idempotency_key": "{{$guid}}",
"object": {
"id": "#1",
"type": "SUBSCRIPTION_PLAN_VARIATION",
"subscription_plan_variation_data": {
"name": "Coffee Month",
"phases": [
{
"cadence": "ANNUAL",
"ordinal": 0,
"periods": 1,
"pricing": {
"price_money": {
"amount": 15000,
"currency": "USD"
},
"type": "STATIC"
}
},
{
"cadence": "ANNUAL",
"ordinal": 1,
"pricing": {
"type": "STATIC",
"price_money": {
"amount": 10000,
"currency": "USD"
}
}
}
],
"subscription_plan_id": "{{subscription_plan_id}}"
}
}
}
Then you will CreatePaymentLink with the subscription_plan_variation_id. That will look like this:
{
"idempotency_key": "{{$guid}}",
"quick_pay": {
"name": "Coffee membership fees",
"price_money": {
"amount": 15000,
"currency": "USD"
},
"location_id": "{{location_id}}"
},
"checkout_options": {
"subscription_plan_id": "{{subscription_plan_variation_id}}" //is the subscription_variation_id
}
}
When the customer pays through the generated link they will be charged $150. Then a year from the date they signed up they’ll be charged $100.
If you need to change the amount to start with $75 and then go to $50 you’ll create a new SUBSCRIPTION_PLAN_VARIATION with those prices in the phases and pass the newly generated ID in when creating the payment link.