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.

Link to section

Overview

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.

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

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

    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

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