App Subscriptions

The App Subscriptions feature allows App Marketplace developers to take recurring payments powered by Square. Make it easy for Square sellers to onboard to your app with free trial periods and monetize your app by offering monthly or yearly subscription plans to Square sellers using your app.

The Subscription selection flow– choosing between basic, business, and premium app subscription plans billed monthly

Link to section

Overview

App subscriptions are built with the Subscriptions API, which enables Square sellers to offer subscriptions (such as a monthly gym membership) to their customers. Seller subscription plans are a separate feature from developer app subscription plans, but are accessed by using the same API. These subscription features are differentiated by the Square account that's associated with a given subscription plan. The associated Square account determines whose access token is used to access a subscription plan.

  • App subscriptions (and plans) are objects associated with your developer account and accessed using a personal access token.
  • Seller subscriptions (and plans) are objects associated with seller accounts and accessed using OAuth access tokens.
  • App subscription plans and seller plans are stored as catalog objects. However, for the initial Beta release of App Subscriptions, avoid using the Catalog API to manipulate app subscription plans, because the effects are undefined and unsupported. Doing so might have unexpected consequences for your subscribers.
  • If your developer account is also a seller account, both types of subscription objects are accessible by using a single personal access token. You can refer to the catalog IDs listed on the Subscription Plans page in the Developer Console to know which IDs are associated with your app subscription plans.

As a developer offering subscription-based pricing for your app, use the Developer Console, Square Dashboard, and Subscriptions API to manage your app subscriptions. Your subscribers (Square sellers) use the Square Dashboard, along with the Square App Subscriptions UI to manage their subscriptions.

Link to section

Requirements and limitations

App Subscriptions is a feature available to US-based developers who have an app in the Square App Marketplace.

  • Your business must be US-based, meaning that your Square account is registered to a US address.
  • You must offer your app exclusively in the US App Marketplace or be willing to have a non-app-subscriptions sign-up flow for international markets.
  • Your app must support a self-service onboarding experience, meaning that a seller must be able to sign up for your product without manual intervention (that is, sales-assisted onboarding).
  • You must offer at least one monthly or annual paid subscription option in addition to an (optional) free plan.
  • Metered pricing (such as charging based on app activity or the number of locations) isn't supported by App Subscriptions.
  • Your Square account must be activated and ready to take payments. Visit squareup.com/activation and follow the prompts in the Square Dashboard to enable your account to accept payments.
Link to section

Capabilities support matrix

The following list indicates who perform each action in the subsequent table:

  • API column - Performed by you with Square APIs.

  • Developer Console column - Performed by you in the Subscriptions section of the Developer Console.

  • Square Dashboard column - Performed by you in the Square Dashboard, while logged in with your developer account.

  • App Subscriptions UI column - Performed by your subscribers with the App Subscriptions UI.

  • Square Dashboard column - Performed by your subscribers in their Square Dashboard.

The following table indicates which App Subscriptions actions can be performed:

Note

This table encompasses the entirety of supported Beta functionality for App Subscriptions. Avoid using the API or developer-facing UI to modify subscriptions or plans outside of the capabilities and surface areas defined in the table.

Capability API Developer ConsoleSquare DashboardApp Subscriptions UISquare Dashboard
Performed byYouYouYouSubscriberSubscriber
Create new subscription plans
View subscription plans
Add a new subscriber
Upgrade or downgrade a subscriber to a different plan
Cancel a subscription (at end of billing cycle)
Revoke a subscriber's authorization (and schedule a cancellation)
Change a subscriber’s payment method
View subscribers and subscription statuses
Read invoice and payment details
Refund a paid invoice
Link to section

API objects

When working with app subscriptions, your app leverages a variety of common objects shared across multiple areas of the Square API data model.

Link to section

Subscription plans and variations

App subscription plans are special subscription plans that cannot be created through the API. You must use the UI on the Subscription Plans page in the Developer Console to create new plans. Each plan you create has at least one plan variation associated with it. Your subscriptions are associated with these specific variations rather than the plan itself. For general information, see Subscription Plans and Variations.

App subscription plans that support free trials include two separate plan variation catalog objects: one that includes a free trial phase and one without a free trial. Which object is used for new subscriptions depends on whether the user has already exhausted a free trial for any of the plans associated with your client app. Similarly, plans that support both monthly and annual cadences have separate plan variations for each cadence. Free plans consist of one plan variation with an extra long (multi-year) free phase.

Link to section

Subscriptions

Subscriptions are objects that associate a customer (in this case, a Square seller) with one of your subscription plan variations. You can use the Subscriptions API to explore these objects.

Link to section

Customers

Customers are objects associated with your developer account that represent your subscribers. They store basic information about your customers, including their merchant token. For each of your subscriptions, a customer exists with a reference_id equal to the merchant_id of the seller.

Link to section

Merchants

Merchants represent the Square accounts for the sellers that subscribe to your plans. Each subscriber is represented by two objects: a customer and a merchant. Subscriptions are associated with the customers and the customer references the merchant.

Link to section

Invoices

Subscriptions are billed using the Invoices API. You can use this API to check due dates and payment statuses.

Link to section

Create subscription plans

During the app submission process, you use the Developer Console to create new app subscription plans. Set details for each plan, including its name, billing cadence, price, and benefits (such as what Square sellers receive by subscribing to your app). You can indicate whether each plan includes a free trial period and its duration.

Each plan is initially created in a draft state, where all fields remain editable.

The Subscription Plans page of the developer dashboard. The list of plans is empty, with a button to "Create a subscription plan"

When you're satisfied with the details of each plan, click the menu button and choose Change to Test plan. While plans are in a test state, their billing details (price and cadence) cannot be changed. Create new plans if you want to test different prices or cadences.

Changing an app subscription plan from "Draft" to "Test plan in the developer dashboard

Link to section

Create app subscription URLs

Square sellers use the standard OAuth flow to authenticate with your app. As part of this flow, you create a redirect URL and an authorization page URL to process the authorization response. With app subscriptions, sellers using your app have a separate app subscriptions URL where they can view your subscription plans and decide which to select. To create this URL, change the base path of your Authorize URL from https://connect.squareup.com/oauth2/authorize to https://squareup.com/app-subscriptions/plans. The new URL contains your developer application ID and looks similar to https://squareup.com/app-subscriptions/plans?client_id=sq0ids-_EXAMPLECmxM2bbAOQJIWw. Sellers are directed to this URL when they start the sign-up flow.

Link to section

Testing

While your subscription plans are in a test state, they're publicly accessible on your app subscriptions page, allowing you to test your integration with multiple Square accounts. A warning banner appears at the top of the page reminding you not to expose this page to sellers.

You can view your test plans and preview your sign-up flow in the following ways:

  • If you haven't yet completed the app review process and don't have any live plans, visiting the app subscriptions URL you created in the previous step defaults to showing the current test plans.
  • On the Subscription Plans page in the Developer Console, choose Preview Test plans from the menu button in the plan details.
  • If you already have at least one live plan, but want to preview new test plans, append a plan_state=test parameter to your URL. The new URL looks like https://squareup.com/app-subscriptions/plans?client_id=sq0ids-_EXAMPLECmxM2bbAOQJIWw&plan_state=test.

Note

The Square Sandbox isn't supported in the Beta launch of App Subscriptions. During development, you should test your app subscription implementation using temporary test plans in production. Consider the following options as you develop your solution:

  • Create a secondary client app reserved specifically for development work.
  • Use free plans if you want to test the full sign-up functionality without incurring charges.
  • When testing plans with small dollar amounts, use the Square Dashboard to refund plan payments after you're done testing. Per Square's return policy, the processing fee isn't refunded as part of this operation.
  • Currently, users can't change plans or resubscribe while their subscription status is 'Pending Cancel'. Sometimes pending cancellations can take up to a day to process. If this processing time affects your implementation testing, you can reach out to Developer & App Marketplace Support to enable instant resubscription for your Square Developer Account during testing.
Link to section

Review and launch

As part of the App Marketplace app submission process, Square reviews your integration to ensure it meets technical requirements. When you submit your app through the Developer Console, you specify which of your test plans to launch publicly. These plans transition to a live status and are available to purchase by subscribers when your app launches.

Link to section

Authenticate and onboard subscribers

When users connect to your app using the Square App Marketplace, they're directed to the plan selection page at your app subscriptions URL to begin the sign-up flow. To add new subscribers using your app, you're required to direct users to the App Subscriptions sign-up flow immediately following a successful login to your app. Sellers don't need to have already authorized your app prior to entering this flow.

The Subscription selection flow– choosing between basic, business, and premium app subscription plans billed monthly

When a new subscriber completes the sign-up flow, your redirect URL is called with an authorization code and a newly created subscription ID (plus an optional state parameter):

[redirect_url]?code=CODE_FROM_AUTHORIZE&subscription_id=NEW_SQUARE_SUBSCRIPTION_ID

Pass this code to the ObtainToken endpoint to receive the seller's OAuth access token and refresh token. A subscription.created webhook is posted for you to track the new subscription. You can also use the NEW_SQUARE_SUBSCRIPTION_ID provided in the response to retrieve the new subscription details.

curl https://connect.squareupsandbox.com/oauth2/token \ -X POST \ -H 'Square-Version: 2024-05-15' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "<YOUR_APPLICATION_ID>", "client_secret": "<YOUR_APPLICATION_SECRET>", "code": "<THE_AUTHORIZATION_CODE_YOU_WERE_GIVEN>", "grant_type": "authorization_code" }'

The response from ObtainToken looks similar to the following:

{ “access_token”: “ACCESS_TOKEN“, “token_type”: “bearer”, “expires_at”: “2024-06-13T22:19:44Z”, “merchant_id”: “MERCHANT_ID“, “refresh_token”: “REFRESH_TOKEN“, }
Link to section

Existing subscribers

If you have existing subscribers paying for your app who still need to connect with Square, continue to follow the standard OAuth connection flow to send each subscriber through the permissions-granting UI and receive an authorization token without requiring them to sign up for a new subscription.

Note

Square doesn't know whether your customers already have a subscription outside of Square. Therefore, to prevent double-billing, avoid directing customers to the App Subscriptions sign-up flow if they're already subscribed.

Link to section

Manage app subscriptions

Link to section

Plan changes and cancellation

Sellers can make changes to their plans by accessing the sign-up experience at any time after they’ve subscribed or by going to the Pricing & Subscriptions page on the Square Dashboard. You must update your app to direct subscribers to this UI whenever they need to add or modify subscriptions. Sellers can select a new plan, update their payment method, or cancel their subscription through this UI. For each plan change, the seller is shown specifics about how the change impacts their billing and access to your app. For more information, see App Subscriptions Billing.

Sellers are given two options for cancellation:

  • Cancel subscription - Initiates the cancellation of the subscription and revocation of OAuth, both of which go into effect at the end of the current billing period. Sellers retain access to your app and its connection to Square until the end of the billing period.
  • Disconnect and cancel - Immediately revokes OAuth to your app and initiates the cancellation of the subscription for the end of the billing period. Sellers retain access to your product but are no longer able to use the app (integration to Square).
Link to section

View subscription plans

When your subscription plans are live, you can view them on the Subscription Plans page of the Developer Console. You can change some aspects, such as the plan name or benefits copy, from this page. However, you cannot change the billing details or deactivate a plan after it's live.

The Plans page of the Developer Dashboard listing multiple plan variations, their prices, and cadence. The plans are in "Test" status.

Note

You should use the Developer Console instead of the Catalog API to view and manage your subscription plans because the API hasn't yet been updated for this initial Beta release.

Link to section

View subscriptions

The Subscriptions page of the Developer Console gives you a list of all active and inactive subscriptions for your customers. However, this UI is in Beta and should be considered read-only. Avoid using this page to create or modify subscriptions. Use this page to identify subscription payments that are current and overdue.

To take action on a subscription (such as change or cancel subscription or update a card on file), ask your customer to visit the subscription sign-up page where these actions are supported.

Link to section

Access subscriptions using the Customers API

Each subscription is associated with a Customer object by the customer_id value. Because the customers for your app are Square sellers, each customer's reference_id is the same as that seller's merchant_id.

To determine whether a seller has a subscription, use the SearchCustomers endpoint to query by reference_id matching a seller's merchant_id and use the SearchSubscriptions endpoint to query by customer_ids.

Each subscription response includes a plan_variation_id that matches the catalog ID of the plan variation shown in the Developer Console.

In addition, the SearchSubscriptions endpoint can be:

  • Called with a query filter that matches source_names of "App Subs" to list all your app subscriptions.
  • Used to retrieve information about a single subscription given a subscription ID.

Use the SearchCustomers endpoint to find a customer for a given subscriber's merchant_id.

Search customers

Use the SearchSubscriptions endpoint to find subscriptions for a single customer or a set of customers.

Search subscriptions

Use the RetrieveSubscription endpoint to get details for a single subscription, including invoice IDs.

Retrieve subscription

App subscriptions are invoiced the same way buyer-to-seller subscriptions are invoiced and leverage the Invoices API. If you have an invoice_id for a subscription, call the GetInvoice endpoint to retrieve more detailed payment information about a subscription, such as its status.

Get invoice

Sellers should cancel their own subscription through the App Subscriptions UI as outlined in Plan changes and cancellation, but you can also cancel subscriptions using the Subscriptions API if absolutely necessary. Subscriptions can be canceled two ways:

  1. By calling the CancelSubscription endpoint. The subscription remains active through the end of the current billing period. At that time, the seller’s OAuth access token is revoked.

Cancel subscription

  1. By calling the RevokeToken endpoint. Your subscriber is generally the person who would revoke your app's access to their Square account on the Square Dashboard. However, as a developer, you can also do this through the API. Revoking a seller's access token doesn't immediately cancel their subscription. It remains active through the rest of the billing cycle, after which it's canceled.

Note

Revoking an access token schedules all app subscriptions associated with the seller to be canceled at the end of their active billing cycle.

Revoke token

Link to section

Webhooks

You're notified through webhooks when sellers modify their subscriptions. If a seller upgrades to a more expensive subscription tier, a subscription.created event is published for the new subscription and a subscription.updated event is published to indicate that the old subscription is canceled. Cancellations aren't immediate, so you might want to track both subscriptions until the old one is fully canceled.

Downgrades to a less expensive subscription tier don't take effect until the end of the current billing cycle, at which time a subscription.updated webhook is published.

Cancellations publish a subscription.updated event at the end of a billing cycle, followed by an oauth.authorization.revoked event. If you know a subscriber wants to cancel, you should send them directly to the cancellation page for your app subscriptions (https://squareup.com/app-subscriptions/cancel? client_id=sq0ids-_EXAMPLECmxM2bbAOQJIWw).