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.
Create a subscription plan with one phase (a $15/week subscription fee).
From the response, you need the plan ID to create a checkout link in the next step.
Create a 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.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.