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.

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 does not 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.

Create a checkout link for a Square subscription plan Permalink Get a link to this section

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: 2022-06-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: 2022-06-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:

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 does not 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.

  • The Order.state) remains DRAFT.

  • Creates a subscription. You can call the SearchSubscriptions endpoint (Subscriptions API) and provide the customer ID to retrieve the subscription.

Related topics Permalink Get a link to this section

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