Subscription Plan Checkout

Applies to: Checkout API | Subscriptions API | Cards API | Orders API

Learn how to create a quick pay checkout for a subscription plan.

If a seller offers a Square subscription plan, applications can use the Checkout API (CreatePaymentLink endpoint) to generate a Square-hosted checkout page for buyers to pay and subscribe to the plan (see Checkout API). In this case, applications provide the following information in a CreatePaymentLink request:

• price_money - The initial phase price as defined in the subscription plan. The price in your checkout request should match the subscription plan price or this acts as a price override.
• subscription_plan_id - The ID of the subscription plan.

After receiving a request, the API creates an order and a Square-hosted checkout page. The seller can then send the checkout page URL to a buyer to subscribe to the plan.

After the buyer opens the checkout page and pays the specified amount, Square does the following:

• Creates a customer if a customer doesn't exist in the seller's Customer Directory. The API searches the directory for a customer with the phone number specified in the request.
• Adds a card on file to the customer profile. For more information about cards on file, see Cards API.
• Charges the card on file for the first priced subscription phase. If the plan offers a free initial phase, the card is charged after the free phase.
• Automatically charges the buyer's card on file for recurring payments as defined by the subscription plan.

In this example, you do the following:

• Create a single-phase (with weekly cadence) subscription plan (see Set up a subscription plan) that charges a $15/week subscription fee using the Subscriptions API.
• You then create a checkout page that you can send to a customer to pay and subscribe to the plan.
• You then verify all the objects (customer, card on file order, order, and subscription) created.

Use the following steps to create a checkout for a Square subscription plan:

1. Create a subscription plan with one phase (a $15/week subscription fee).

   Upsert catalog object

   cURL

   From the response, you need the plan ID to create a checkout link in the next step.

2. Create a payment link.

   Create payment link

   cURL

   In response, Square creates an order, creates a checkout page, and returns the order ID and URL for the checkout page. An example response is shown:

   {
     "payment_link": {
       "id": "OTGMWB3A65HJW2WF",
       "version": 1,
       "description": "",
       "order_id": "E1Ho92Z8lquV9QRIiQ5MWLxKw6MZY",
       "checkout_options": {
         "subscription_plan_id": "TF2EBYIBAM6BJTLBNYPAXD2X"
       },
       "url": "https://sandbox.square.link/u/Kzc5PBJq",
       "created_at": "2022-03-16T01:59:01Z"
     },
     "related_resources": {
       "orders": [
         {
           "id": "C0DMgui6YFmgyURVSRtxr4EShheZY",
           "location_id": "{{LOCATION_ID}}",
           "source": {
             "name": "Test Online Checkout Application"
           },
           "line_items": [
             {
               "uid": "8YX13D1U3jO7czP8JVrAR",
               "name": "Auto Detailing",
               "quantity": "1",
               "item_type": "ITEM",
               "base_price_money": {
                 "amount": 12500,
                 "currency": "USD"
               },
               "variation_total_price_money": {
                 "amount": 12500,
                 "currency": "USD"
               },
               "gross_sales_money": {
                 "amount": 12500,
                 "currency": "USD"
               },
               "total_tax_money": {
                 "amount": 0,
                 "currency": "USD"
               },
               "total_discount_money": {
                 "amount": 0,
                 "currency": "USD"
               },
               "total_money": {
                 "amount": 12500,
                 "currency": "USD"
               }
             }
           ],
           "fulfillments": [
             {
               "uid": "bBpNrxjdQxGQP16sTmdzi",
               "type": "DIGITAL",
               "state": "PROPOSED"
             }
           ],
           "net_amounts": {
             "total_money": {
               "amount": 12500,
               "currency": "USD"
             },
             "tax_money": {
               "amount": 0,
               "currency": "USD"
             },
             "discount_money": {
               "amount": 0,
               "currency": "USD"
             },
             "tip_money": {
               "amount": 0,
               "currency": "USD"
             },
             "service_charge_money": {
               "amount": 0,
               "currency": "USD"
             }
           },
           "created_at": "2022-03-03T00:53:15.829Z",
           "updated_at": "2022-03-03T00:53:15.829Z",
           "state": "DRAFT",
           "version": 1,
           "total_money": {
             "amount": 12500,
             "currency": "USD"
           },
           "total_tax_money": {
             "amount": 0,
             "currency": "USD"
           },
           "total_discount_money": {
             "amount": 0,
             "currency": "USD"
           },
           "total_tip_money": {
             "amount": 0,
             "currency": "USD"
           },
           "total_service_charge_money": {
             "amount": 0,
             "currency": "USD"
           }
         }
       ]
     }
   }

The application can send the url in the payment_link to the buyer. The buyer experience is similar to what is described in Quick Pay Checkout. After receiving the request, Square does the following:

• Creates a customer (if a customer with the buyer-provided phone number doesn't exist in the seller's Customer Directory). You can use ListCustomers (Customers API) and search using the buyer-provided phone number.
• Adds the card on file. You can use the The ListCards endpoint (Cards API) by specifying the customer ID to retrieve the cards on file.
• Updates the order by adding a fulfillment (see Order.fulfillments). You can use the RetrieveOrder endpoint (Orders API) to verify the order.
• Creates a subscription. You can call the SearchSubscriptions endpoint (Subscriptions API) and provide the customer ID to retrieve the subscription.

• Checkout API
• Quick Pay Checkout
• Square Order Checkout
• Optional Checkout Configurations
• Manage Checkout