Hi everyone,
I have been reading through this discussion regarding the confusion between Subscription Variations vs Subscription Phases and how to properly link them to a Checkout Payment Link.
I understand the concept conceptually: I need to create a Subscription Plan Variation with multiple phases (Ordinal 0 for the initial setup fee, Ordinal 1 for the recurring fee) and then pass that Variation ID into the CreatePaymentLink endpoint.
However, I am struggling to implement this.
Questions:
- Does the amount on
quick_pay need to match Phase 0 ($150.00)?
- Why does the payment link UI not display any information about the second phase?
- How will the customer know they will be charged a different amount from the second phase?
- How would I know if this is actually working?
- I there any other approach (better way) to implementing this flow?
- I don’t want to create a customer object before creating subscription which subscription API requires.
- I need to be able to retrieve the Payment link.
Python
# 1. Define Phases
phases = [
{
"cadence": "MONTHLY",
"ordinal": 0,
"periods": 1,
"pricing": {
"type": "STATIC",
# Subscription + Setup Fee
"price_money": {"amount": 15000, "currency": "USD"}
}
},
{
"cadence": "MONTHLY",
"ordinal": 1,
"pricing": {
"type": "STATIC",
# Recurring
"price_money": {"amount": 10000, "currency": "USD"}
}
}
]
# 2. Create Payment Link
# Does 'amount' here have to match Phase 0 ($150.00)?
client.checkout.payment_links.create(
idempotency_key="...",
quick_pay={
"name": "VIP Membership Setup",
"price_money": {"amount": 15000, "currency": "USD"},
"location_id": "..."
},
checkout_options={
"subscription_plan_id": "..."
}
)
Any guidance or working examples for this flow would be greatly appreciated!
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:
Additional Documentation
Split Payment: Let Customers Split Payment Transactions
App Subscriptions Billing
Split Payment: Let Customers Split Payment Transactions
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.
To address your questions and concerns:
-
Does the amount on quick_pay need to match Phase 0 ($150.00)?
- Yes, the amount specified in the
quick_pay section should match the initial phase price (Phase 0) of the subscription plan variation. This ensures that the initial payment aligns with the setup fee you intend to charge.
-
Why does the payment link UI not display any information about the second phase?
- The Checkout API’s payment link UI is designed to handle the initial payment phase. It does not display information about subsequent phases directly on the checkout page. The recurring nature and details of the subscription are typically communicated to the customer through other means, such as a confirmation email or terms of service.
-
How will the customer know they will be charged a different amount from the second phase?
- It’s important to communicate the full details of the subscription, including any recurring charges, to the customer outside of the payment link UI. This can be done through a detailed description on your website, a confirmation email, or a terms of service agreement that the customer agrees to before completing the purchase.
-
How would I know if this is actually working?
- You can verify the subscription creation and payment processing by checking the responses from the API calls. Additionally, you can use the Square Dashboard to monitor the subscriptions and payments. The Subscriptions API can also be used to retrieve and verify subscription details.
-
Is there any other approach (better way) to implementing this flow?
- With payment links you don’t need to create a customer up front. The customer will be created when the subscription is created with the information that the customer puts in.
- To retrieve the payment link, ensure that your API call to
CreatePaymentLink is correctly set up to return the link URL, which you can then store or send to the customer.
Overall, while the Checkout API provides a streamlined way to handle initial payments, managing customer expectations and communication about recurring charges is crucial and often handled outside the API’s direct capabilities.
This answer was reviewed by @Bryan-Square.
This document says: ( Subscription Plan Checkout )
- The Checkout API only supports subscription plan variations with one paid phase (or one free phase and one paid phase).
But I am still able to create payment link using a Plan Variation that has multiple paid phases. So, does this actually work? Will the second billing cycle use the second phase or will it always be the amount from the first phase?
I am only looking for another approach as the Payment link UI is broken. it will make the customers confused if they need to pay 150 USD every month or a different amount. and also payment links actually might not support multiple phases to begin with according to Subscription Plan Checkout post.
Multiple phases works with the Checkout API. The only thing is that the additional phase price won’t show in the UI when the customer signs up.
If you are looking for an alternative solution you can use the Web Payments SDK to store the card on file and call the Subscriptions API directly to create subscriptions. 
Is this something that is on the roadmap and might be fixed in the next 2 months? I might need to look into different providers if that’s not the case.
At this time we don’t have a public roadmap for features or improvements. 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.
Are you clearly displaying the different phases to the customer prior to redirecting to our checkout page?
