Merchants API

Applies to: Merchants APIMerchants API | OAuth APIOAuth API | Locations APILocations API

Learn about the Merchants API and how to retrieve information about a Square seller account that's integrated with your application.

Link to section

Overview

The Merchants API groups individual seller locations into larger organizations, allowing them to operate as a single entity. Each merchant represents one organization or business that sells with Square and all team membersteam members of that business can coordinate on behalf of the merchant.

When a Square seller connects to your application with OAuthOAuth or a personal access token, your application receives an access token that is scoped to that merchant group. Use the Merchants API to retrieve core information about the organization connecting to your application, such as the language preferences, business name, country, and account status.

Some API tasks, such as managing ordersorders or taking paymentspayments, are associated with a specific seller location using a location_id. Use the Locations APILocations API to access information about these locations.

Note

  • The application developer account and seller account are separate Square accounts. Developers cannot perform any actions, such as taking payments, on behalf of sellers before the seller has granted the application developer permissions through OAuth. For more information, see OAuth APIOAuth API.
  • The id of a particular merchant is only accessible through the Merchants API. It's not visible on the Square Dashboard or Developer Console.

In the Square data model, the access token (OAuth or PAT) used to connect your application to a Square seller is associated with a single merchant. Use this merchant's ID in the request URL for the RetrieveMerchantRetrieveMerchant endpoint to access information about the merchant.

Retrieve merchant

Copy

The following is an example response:

Copy
Expand
{ "merchant": { "id": "DM7VKY8Q63GNP", "business_name": "Apple a Day", "country": "US", "language_code": "en-US", "currency": "USD", "status": "ACTIVE", "main_location_id": "7WQ0KXC8ZSD90", "created_at": "2021-09-20T14:29:08.025Z" } }

Alternatively, you can request the specific merchant associated with your account's access tokens by calling RetrieveMerchantRetrieveMerchant using me in place of the merchant ID.

Retrieve merchant

Copy

You can also retrieve the associated merchant using the ListMerchantsListMerchants endpoint.

List merchants

Copy

Note that the response is in the form of a list, but contains only one merchant: the one associated with your application based on the given access token.

Copy
Expand
{ "merchant": [ { "id": "DM7VKY8Q63GNP", "business_name": "Apple a Day", "country": "US", "language_code": "en-US", "currency": "USD", "status": "ACTIVE", "main_location_id": "7WQ0KXC8ZSD90", "created_at": "2021-09-20T14:29:08.025Z" } ] }
Link to section

See also

On this page