2016-02-16 Changelog

We have made changes 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.

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.

• 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 /v1/{location_id}/items
• 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 the id of the location they want to list items for.
• Business-level applications will be able to get a business' location ids by sending a GET request to /v1/me/locations

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.

No, with the exception that applications created after February 16 will not be able to specify me in the path of a request to access a location's transactions or items. Applications created before February 16 can continue to specify me as usual.