How to allow trial phase on Subscription plan, API Version 2022-11-16

Questions
1

Hi I need to allow trial phase on a subscription plan, which is basically a $0 charge for certain days. I couldn’t find any clear documentation about that. I need to make this happen with API version ‘2022-11-16’ because I can’t change API version for some good reason. Thanks

2

:wave: 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

Additional Documentation

Guidelines and Limitations
Square Sandbox
Onboard to Square Appointments

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.

1 Like
3

Is there a specific reason you can’t use a newer version of the API? If you can it would be ideal to use the new subscription model that came out in 2023. :slightly_smiling_face:

4

Well, our product (Which is a WordPress plugin) provides different payment gateways like Stripe, Paypal, Square, etc, to integrate into their business. So once they setup Square according to our implementation, we just can’t change our code implementation because then we need to notify everyone to change their Square credentials to the respective API version. If they don’t their business might get disrupted. I hope you get the point. Thanks

5

So your having your customers target a specific Square version?

If you pass in the Square-Version in the header of the request you’ll override what’s set in the application. So while a customers API version may be set to a date in the past your integration can pass in a newer version to target to allow you to update to our new subscription model. :slightly_smiling_face:

6

Thanks, I get that API version part. Even on the newer API version, how do I allow a trial phase for certain days on a subscription plan? I couldn’t find any elaborate explanations in the Square API documentation.

7

In the subscription_plan_variation you’ll include a free trial. It will look something like this variation:

{
    "idempotency_key": "{{$guid}}",
    "object": {
      "type": "SUBSCRIPTION_PLAN_VARIATION",
      "id": "#1",
      "subscription_plan_variation_data": {
        "name": "Coffee of the Month Club",
        "phases": [
          {
            "cadence": "MONTHLY",
            "ordinal": 0,
            "periods": 1,
            "pricing": {
              "type": "STATIC",
              "price": {
                "amount": 0,
                "currency": "USD"
              }
            }
          },
          {
            "cadence": "MONTHLY",
            "ordinal": 1,
            "pricing": {
              "type": "RELATIVE",
              "discount_ids": [
                "4VHZQB576CGW7LK2AU3YMB5B"
              ]
            }
          }
        ],
        "subscription_plan_id": "DA442EYC7ITK75BAJS4TIW7J"
      }
    }
  }

:slightly_smiling_face:

8

Thanks for the clarification. If possible, I want to be more clear about trial days, such as for odd trial days, e.g., 3/4/5 or 13 days which don’t belong to any specific criteria of DAILY, WEEKLY, or MONTHLY. Thanks

9

For odd days like that you can do a DAILY phase and specify the periods as the odd days you want to set. :slightly_smiling_face:

10

I did exactly the same. However, the checkout page doesn’t show any card information input when the amount is $0, which is the case for trial days. That’s why many of our users are concerned about how their customers will be billed after trial days, as apparently no card information is stored.

image.png
image.png558×820 38.9 KB

11

FYI: I am using the ‘subscription-plan-checkout’ API.

12

Okay, in that case the Checkout API won’t be collecting a payment method for the trial phase. When the billing phase starts then the customer will be sent an invoice to pay for the subscription. Unfortunately the ability to collect card information on a free trial phase with the Checkout API isn’t currently available. :slightly_smiling_face:

13

Thank you for clearing that up. :pray: