Hello,
I have one SubscriptionPlan, with three SubscriptionPlanVariation’s.
Each of the variations has two phases: (1) a two-week free trial, and (2) a billed monthly cycle.
I’d like to give users the ability to swap from one variation to another. When this occurs, at the end of their current phase, their subscription should change to phase (2) of whichever variation they selected.
Is this possible using the swapPlan API? I see there is a parameter “phases” but the documentation isn’t clear on what exactly this means. Any and all insight is greatly appreciated.
Thanks
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
App Subscriptions Billing
Pricing
Order Service Charges
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.
The swapPlan API allows you to change a customer’s subscription plan variation. However, the behavior you’re describing—specifically, transitioning directly to phase (2) of a new variation when swapping—depends on how the phases are configured and how the API handles phase transitions.
The phases parameter in the API is used to define the phases of a subscription plan variation. When you swap a plan, the subscription typically starts from the beginning of the new plan’s phases unless specified otherwise. If you want to skip the free trial phase and move directly to the billed monthly cycle, you would need to ensure that the swap operation is configured to bypass the initial free trial phase.
Unfortunately, the documentation does not explicitly state that you can skip phases directly using the swapPlan API. You might need to handle this logic in your application by setting the appropriate phase when creating or updating the subscription. If the API does not support skipping phases directly, you may need to manually adjust the subscription to reflect the desired phase.
If this functionality is critical, you might need to explore additional options or workarounds, such as creating a new subscription with the desired phase or consulting further resources to confirm the API’s capabilities regarding phase transitions during a swap.
This answer was reviewed by @Bryan-Square.
You might need to handle this logic in your application by setting the appropriate phase when creating or updating the subscription. If the API does not support skipping phases directly, you may need to manually adjust the subscription to reflect the desired phase.
Is this suggesting that it’s possible to update a subscription to change the user’s current phase? If so, how?
Hello, just following up on this as the question is still pending an answer
Current phases can’t currently be adjusted. Once one phase completes then changes will be made to the plan. 
Thanks for the response. Im still a bit confused by the AI’s answer. It mentions that the subscription can be updated to change the phase, and it also mentions:
If you want to skip the free trial phase and move directly to the billed monthly cycle, you would need to ensure that the swap operation is configured to bypass the initial free trial phase.
I’ve read through the Subscription API docs multiple times and there does not appear to be details on how to perform either of these things.
How can the plan be swapped, and a specific phase chosen?
I think the center of my confusion lies on the phases property of the swapPlan API. The property takes a list of ordinal values and Order Template IDs, but its unclear where these Order Template IDs come from, or what the ordinal represents.
Are we creating new phases in the subscription? Or selecting the user’s new phase? What does the Order Template ID represent?