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.

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.

Link to section
Create a checkout link for a Square 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.

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.

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.

Link to section
See also

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Subscription Plan Checkout

Note

Link to section
Create a checkout link for a Square subscription plan

Link to section
See also

On this page

Docs

Subscription Plan Checkout

Note

Link to section Create a checkout link for a Square subscription plan

Link to section See also

On this page

Link to section
Create a checkout link for a Square subscription plan

Link to section
See also