Connect API changes (2016-02-16)
On February 16, 2016, changes were made to the representation of a Square merchant in the Connect API.
These changes have different effects on Connect API applications created before and after February 16. Applications created before February 16 continue to work as before.
Before, most Square merchants had a single account that they used to process all of their payments and manage all of their items.
Applications with the necessary permissions had access to all of these transactions and items.
After this change, a Square merchant instead has a business entity that includes one or more locations. Each location typically represents a different brick-and-mortar store, and each one has its own transactions and its own items.
As this change rolls out, Square is creating a business entity for every merchant. The business has a single location, which contains all of the merchant's existing transactions and items.
The majority of merchants will choose to stick with a single location, but they can add as many locations as they want from their merchant dashboard.
How does this affect applications created before February 16?
If you created your Connect API application before February 16, your application works as before. However, your application is a single-location application. This means the following:
- Your application cannot use endpoints listed in the Business Management section of the Connect API reference. These endpoints are primarily for managing a business' employees and timecards.
- If one of your merchants adds a location to their business, your application will not have access to the new location's transactions and items.
- When a new merchant authorizes your application, they will automatically be prompted to choose one of their locations to grant your application access to.
- In order to grant your application access to multiple locations, a merchant will have to complete the OAuth flow once for each location. Your application will need to keep track of a different access token for each location.
How does this affect applications created on or after February 16?
If you created a Connect API application on or after February 16, your application is a business-level application. This means that when a merchant authorizes your application, they'll grant it access to all of their business' locations.
Business-level applications must specify a location in their requests to access transactions or items. For example, the path for the List Items endpoint is
Single-location applications have always been able to simply specify
me for the
value of the
location_id parameter, but business-level applications must provide
id of the location they want to list items for.
Business-level applications will be able to get a business' location
GET request to
Can I upgrade my single-location application to a business-level application?
It is not possible to upgrade an existing application listed in the application dashboard.
Instead, you can create a new application in the dashboard after February 16 and reauthorize your merchants with the new application.
Before you move your merchants to a new application, you will need to make sure your new
application's code supports the location
id requirement for business-level
applications described above.
Are endpoint paths changing?
No, with the exception that applications created after February 16 will not be able to
me in the path of a request to access a location's transactions or
Applications created before February 16 can continue to specify
me as usual.