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
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 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.
Use the following steps to create a checkout link for a Square subscription plan:
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.
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.