Applies to: Checkout API | Subscriptions API | Cards API | Orders API
Learn how to create a quick pay checkout for a subscription plan.
If a seller offers recurring subscriptions, applications can use the CreatePaymentLink endpoint to generate a Square-hosted checkout page for buyers to pay and subscribe to a subscription plan variation.
- The Checkout API only supports subscription plan variations with one paid phase (or one free phase and one paid phase).
- The Checkout API doesn't support
app_fee_moneyas a checkout option when specifying the plan variation ID for recurring payments. - Cash App Pay and Afterpay aren't supported for subscription payments.
A recurring subscription is represented by three parts in the Square API data model:
- Subscription plan - Represents what is being sold. This can be a single item, a series of recurring services, or a category of items or services.
- Subscription plan variation - Represents how the product is being sold; that is, how often and for what price.
- Subscription - Represents who is buying the product or service. It's an agreement with a specific customer to purchase a subscription from the business.
For more information, see Subscription Plans and Variations.
The Checkout API's CreatePaymentLink endpoint creates a Square-hosted checkout page for buyers to subscribe to a specific subscription plan variation. Your CreatePaymentLink request requires the following:
price_money- The initial phase price as defined in the subscription plan variation. The price in your checkout request should match thepriceof the subscription plan variation. If it doesn't match, this acts as a price override.subscription_plan_id- The ID of the subscription plan variation.
Use the following steps to create a payment link for a Square subscription:
- Create a subscription plan to act as a category for various subscription tiers.
- Create a single-phase subscription plan variation. This example shows a weekly $15 subscription fee.
- Create a checkout page that you can send to a customer to pay and subscribe to the plan variation.
This request creates a new subscription plan called "Membership tiers".
Upsert catalog object
This request creates a subscription plan variation called "Silver Membership Tier" with one phase (a $15/week subscription fee). The subscription_plan_id value associates this variation with the plan created in step 1.
Upsert catalog object
Create a payment link using the Checkout API and the ID of the subscription plan variation you created previously. Put this ID value in the subscription_plan_id field.
Note
Customers subscribe to a subscription plan variation, not to a subscription plan. For this reason, the subscription_plan_id value in the CreatePaymentLink request must contain the ID value for a subscription plan variation.
Create payment link
Your 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. When the buyer makes a payment on the checkout page, Square does the following:
- Searches the seller's Customer Directory for a customer with the phone number provided by the buyer. If no customer exists, a new one is created.
- Adds the card on file to the customer's profile. To view cards on file, you can call the ListCards endpoint (Cards API) and specify the customer ID.
- Updates the order by adding a fulfillment (see Order.fulfillments). You can use the RetrieveOrder endpoint (Orders API) to verify the order.
- Creates a new subscription. You can call the SearchSubscriptions endpoint (Subscriptions API) and provide the customer ID to retrieve the subscription.
- Charges the buyer's 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.
- Continues to charge the card on file as specified by the cadence of the subscription plan variation. In this example, the buyer's card is charged weekly.