Necessary API calls to take payment for a Subscription via payment link and not through email

I’m building a subscription flow for a SaaS service where the user must enter the card details from the outset, even if there’s a trial period. Trying to understand the sequence of APIs that need to be called. There are gaps in my understanding of the API sequencing, so I’d appreciate if anyone can help correct the following before I set out building this. Hopefully this will also help others embarking on a similar journey.

One time initialization

  1. Create CatalogItems for each feature of the SaaS service
  2. Create CatalogItemVariations for each subscription plan mapping to the features that are included (modeled as CatalogItems)
  3. Create SubscriptionPlans for each tier of subscription e.g. Starter, Premium, Enterprise and associate with the CatalogItemVariation for that subscription plan
  4. Create SubscriptionVariations for each payment cadence e.g. a Monthly variation and an Annual variation. Include ones or more phases in each variation, depending on whether there’s a free trial offered at the start. Use STATIC pricing for each phase.
  5. Create OrderTemplates for each subscription tier x payment cadence. e.g. Starter Monthly, Starter Annual, Premium Monthly, Premium Annual

User subscription flow

  1. Display Subscriptions in the FE - Use Catalog API - List Catalog
  2. User selects their tier and chooses payment cadence (Monthly/Annual) clicks Subscribe
  3. BE creates payment link using Checkout API with subscription plan id set in checkout options and order line items set to order template IDs. Order created by API and Order ID returned in response.
  4. FE redirects user to payment link
  5. User enters credit card info and submits payment form. Do I need a webhook here to fire on payment success and create the subscription with that order ID (and customer, location, subscription variation ids)?
  6. User redirected to thank you page.

I’m not sure when I need to create the customer record, I can presumably do so prior to any of this, or maybe only do so once a successful payment has been made.

Greatly appreciate any feedback on this flow as I get to grips with the Square API.

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

https://developer.squareup.com/docs/app-marketplace/requirements/subscriptions-api

Additional Documentation

Customers API Workflows
Orders API: How It Works
Create and Publish Invoices

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

You’ll want to create the customer prior to any payments being processed so you can include the customer_id when creating the subscriptions for the customers. :slightly_smiling_face:

Thanks Bryan! Do steps 3-6 look accurate in the user flow otherwise?

Yes, those are correct except for step 3. You’ll really create the payment link with the subscription_variation_id. It will look like:

{
    "idempotency_key": "{{$guid}}",
    "quick_pay": {
      "name": "Coffee membership fees",
      "price_money": {
        "amount": 100,
        "currency": "USD"
      },
      "location_id": "{{location_id}}"
    },
    "checkout_options": {
      "subscription_plan_id": "WJZ33ATP5ER36Y6Y2ZIE33SZ" //is the subscription_variation_id
    }
  }

:slightly_smiling_face: