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

Subscription Plan Checkout

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 Overview). 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.

Note

There are guidelines related to the subscription plan for which you can generate a checkout page. For more information, see Guidelines and Limitations.

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 Overview.

  • 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.

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

    Upsert Catalog Object
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    curl https://connect.squareupsandbox.com/v2/catalog/object \
      -X POST \
      -H 'Square-Version: 2023-08-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "object": {
          "type": "SUBSCRIPTION_PLAN",
          "id": "#plan",
          "subscription_plan_data": {
            "name": "One-phase subscription plan for testing checkout  link.",
            "phases": [
              {
                "cadence": "WEEKLY",
                "recurring_price_money": {
                  "amount": 1500,
                  "currency": "USD"
                }
              }
            ]
          }
        }
      }'

    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
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    curl https://connect.squareupsandbox.com/v2/online-checkout/payment-links \
      -X POST \
      -H 'Square-Version: 2023-08-16' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "quick_pay": {
          "name": "Gym membership fees",
          "price_money": {
            "amount": 1500,
            "currency": "USD"
          },
          "location_id": "7WQ0KXC8ZSD90"
        },
        "checkout_options": {
          "subscription_plan_id": "{SUBSCRIPTION_PLAN_ID}"
        }
      }'

    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:

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    • 29
    • 30
    • 31
    • 32
    • 33
    • 34
    • 35
    • 36
    • 37
    • 38
    • 39
    • 40
    • 41
    • 42
    • 43
    • 44
    • 45
    • 46
    • 47
    • 48
    • 49
    • 50
    • 51
    • 52
    • 53
    • 54
    • 55
    • 56
    • 57
    • 58
    • 59
    • 60
    • 61
    • 62
    • 63
    • 64
    • 65
    • 66
    • 67
    • 68
    • 69
    • 70
    • 71
    • 72
    • 73
    • 74
    • 75
    • 76
    • 77
    • 78
    • 79
    • 80
    • 81
    • 82
    • 83
    • 84
    • 85
    • 86
    • 87
    • 88
    • 89
    • 90
    • 91
    • 92
    • 93
    • 94
    • 95
    • 96
    • 97
    • 98
    • 99
    • 100
    • 101
    • 102
    • 103
    • 104
    • 105
    • 106
    • 107
    • 108
    • 109
    {
      "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.