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.

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 Dashboard to know which IDs are associated with your app subscription plans.

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

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 Seller Dashboard to enable your account to accept payments.

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

• API column - Performed by you with Square APIs.

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

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

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

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

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

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

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 Dashboard 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.

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.

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.

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.

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

During the app submission process, you use the Developer Dashboard 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.

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.

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.

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 Dashboard, 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.

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 Dashboard, 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.

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.

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“,
}

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.

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 Seller 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).

When your subscription plans are live, you can view them on the Subscription Plans page of the Developer Dashboard. 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 Subscriptions page of the Developer Dashboard 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.

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 Dashboard.

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.

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).