New Subscriptions API Integrations with Catalog and Orders

The Subscriptions API allows you to integrate Square Subscriptions into your applications, empowering sellers to drive repeat business and build stronger relationships with customers.

Today, we are thrilled to announce the general availability of two new integrations with Square Catalog and Orders for the Subscriptions API. These integrations create a tighter connection between the Subscriptions API and the broader Square ecosystem, making it easier for you to configure, manage, and fulfill subscriptions for sellers.

Catalog Integration

You can now attach catalog items to a single subscription plan, allowing sellers to automatically apply a common set of pricing and subscription rules to a group of items. This makes it significantly easier for sellers to set up subscriptions quickly and accurately. The integration also enables you to streamline processes and automate updates to subscription plans. For example, you can now automatically apply configured sales tax rates, item variants, and modifiers to subscribable items, and automate updates to Square Inventory when items are sold via subscriptions.

Orders Integration

The enhanced integration with orders provides you with greater visibility and control over the order tracking and fulfillment of subscriptions. You can use the Orders API to retrieve subscription order details directly from the Square Dashboard. This allows you to access important information, such as the customer name, associated items, payment status, and more. You also have the flexibility to add shipping addresses or attach service charges to subscription orders.

How it works

The Catalog API already stores SubscriptionPlan objects for sellers to define what their buyers can subscribe to, and now accepts fields to describe which items (or item categories) are subscribable under the plan. There’s also a flag to toggle whether all items are subscribable. The following example creates a new "Coffee Subscription" subscription plan, where all items in the seller's coffee category are subscribable:

curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-06-08' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "type": "SUBSCRIPTION_PLAN",
      "id": "#1",
      "subscription_plan_data": {
        "name": "Coffee Subscription",
        "all_items": false,
        "eligible_category_ids": [
          "2CJLFP5C6G74W3U3HD5YAE5W"
        ]
      }
    }
  }'

Now you can define the variations on the plan, which control the different phases of the subscription (i.e. free trial and evergreen phase), and their cadence and what discounts apply. Let’s say one of the variations on the Coffee Subscription plan is a “Coffee-of-the-Month Club,” and has a 1-month trial for $10, and a 15% discount (defined elsewhere in the catalog) after that. Once you have the ID of our Coffee Subscription plan, you can create the variation with a request like this:

curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-06-08' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "type": "SUBSCRIPTION_PLAN_VARIATION",
      "id": "#1",
      "subscription_plan_variation_data": {
        "name": "Coffee of the Month Club",
        "phases": [
          {
            "cadence": "MONTHLY",
            "ordinal": 0,
            "periods": 1,
            "pricing": {
              "type": "STATIC",
              "price": {
                "amount": 1000,
                "currency": "USD"
              }
            }
          },
          {
            "cadence": "MONTHLY",
            "ordinal": 1,
            "pricing": {
              "type": "RELATIVE",
              "discount_ids": [
                "5PFBH6YH5SB2F63FOIHJ7HWR"
              ]
            }
          }
        ],
        "subscription_plan_id": "VVH3YXQSQATSL3XR4LIKD3QM"
      }
    }
  }'

The request will return the completed variation object with its ID. Now it’s ready to be subscribed to, all a new subscription request needs is an order to subscribe to. You can create one with a request to the Orders API for any of the items in the category:

curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2023-06-08' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "LE40N37TVF5FT",
      "state": "DRAFT",
      "line_items": [
        {
          "quantity": "1",
          "catalog_object_id": "KAQJXCONWUSBWPHR62W3DZTO"
        }
      ]
    }
  }'

The returned Order will have an ID that can be used for a subscription, any DRAFT order whose line items match the constraints in the plan can be subscribed to.

Now, subscription creation requests can include the new plan variation ID and an order template ID for each phase, and the subscription will bill $10.00 USD for the first month, and apply a 15% discount to whatever order the subscription includes. The order for each phase can be different, or the same one every time:

curl https://connect.squareupsandbox.com/v2/subscriptions \
  -X POST \
  -H 'Square-Version: 2023-06-08' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "customer_id": "Y3MBJEF62GVTXAP56H7SD2AFJW",
    "location_id": "LE40N37TVF5FT",
    "plan_variation_id": "CUPS23SKJ7J4FD4F3IMVAEOH",
    "phases": [
      {
        "ordinal": 0,
        "order_template_id": "x7ClfqqNapjeDMvrQOZhbgVFVKFZY"
      },
      {
        "ordinal": 1,
        "order_template_id": "x7ClfqqNapjeDMvrQOZhbgVFVKFZY"
      }
    ]
  }'

And you’re all set! Now buyers can enjoy their coffee every month, without worrying about running out of their favorite blend.

Get started

Subscriptions API catalog and orders integrations are generally available in the U.S., Canada, U.K., Ireland, Australia, France, Spain, and Japan.

To start building, check out our developer documentation, technical reference, and payments pricing. As always, please share your feedback in our community Slack channel or Square Developer Forums. If you want to keep up to date with the rest of our content, be sure to follow this blog and our Twitter account.