Testing

Test Square APIs with API Explorer

API Explorer is an interactive interface you can use to build, view, and send HTTP requests that call Square APIs. API Explorer lets you test your requests using actual Sandbox or Production resources in your account, such as customers, orders, and catalog objects.

You can also use API Explorer to quickly populate resources in your account. Then, you can interact with the new resources in the Seller Dashboard. For example, if you use API Explorer to create a customer in your Sandbox environment, the customer is displayed in the Sandbox Seller Dashboard.

Feature overview Permalink Get a link to this section

API Explorer provides many features that help you to build and test HTTP requests that call Square APIs.

API Explorer with numbered callouts for several features

1. Sandbox and Production toggle

If you are signed in to your Square developer account, you can choose to work with the Sandbox or Production environment for your account. The Sandbox is an isolated server environment provisioned for each Sandbox test account. When you create a developer account, Square creates a default test account for you.

Square recommends using Sandbox for testing. For more information, see Test in the Sandbox.

2. API and endpoint selector

Select the Square API category and endpoint that you want to try. API Explorer displays the HTTP method, path, and description for the selected endpoint. If the endpoint requires a URL parameter or request body, or if it supports query parameters, API Explorer displays fields where you can provide values.

3. Dynamic requests

API Explorer provides a boilerplate request for each endpoint. As you enter values for the request in the page form, API Explorer automatically updates the contents of the Request pane. This pane also contains copy, expand, and run buttons.

4. Real-time responses

If you are signed in to your Square developer account, the Response pane displays the response for the requests that you run. This pane also contains copy and expand buttons.

5. Access token selector

If you are signed in to your Square developer account, you can select an access token to use for your request. API Explorer lists the access token for each of your applications, which grant permissions for all Square APIs. You can also enter other access tokens to use in the request. For more information, see Test access permissions.

6. Language selector for requests

Select the programming language that API Explorer uses for the request. API Explorer provides requests in cURL and languages for Square SDK platforms. For more information, see Generate language-specific requests for your applications.

7. API version selector

Select the Square API version to use for the request. By default, API Explorer uses the latest API version, but you can choose an earlier version. This feature is useful if you want to test changes to an existing application that's based on an earlier API version. For more information, see Versioning in Square APIs and Changelog for Square Connect APIs.

Integration with documentation Permalink Get a link to this section

Each endpoint description includes an Open in API Reference link that opens the endpoint documentation in the Square API Technical Reference.

Each parameter and attribute can also display a description in a tooltip:

  • For a request, choose the attribute name or ? button in the page form. If the attribute is an object data type, you can choose the object name.

  • For a response, choose the attribute name in the Response pane.

Docs integration links in the request and response

Did you know?

In the Technical Reference, you can use the Try in API Explorer button to open an endpoint in API Explorer.

Inline tools for fields Permalink Get a link to this section

Specific field types provide inline tools that make it easier to enter values:

  • Idempotency key generator. For idempotency_key values, you can generate a random ID for the request. Using an idempotency key guarantees that Square processes a request only once, even if you send the same request multiple times. For more information, see Idempotency.

  • Nonce and card-on-file test values. When creating a payment in the Sandbox environment, you can select a test nonce or card on file for the source_id value. You can also enter a nonce that you obtain using one of the Sandbox test values for credit cards. For more information, see Test payments.

  • File upload utility. Fields that represent image files and other file formats include a file selector that you can use to select and upload a local file.

  • Typeahead search for enum values. Fields that represent enum values provide typeahead search suggestions that make it easier to find supported values. You can use your mouse to select a value, or on the keyboard, the down-arrow key followed by Enter or Return.

  • Formatted timestamp examples. Many fields that represent timestamp values display example values that use the supported RFC 3339 format (for example, 2020-07-30T21:59:15.286Z). For more information, see Working with Dates: Square APIs.

Generate language-specific requests for your applications Permalink Get a link to this section

In addition to cURL, API Explorer supports languages that correspond to Square SDK platforms. You can select a programming language in the Request pane to generate language-specific requests that you can paste into your applications. For languages that correspond to strongly typed Square SDKs, such as Java, PHP, and C#, API Explorer uses the appropriate data models and syntax for the requests.

Requests generated by API Explorer should work as is in your application, assuming that the application is ready to call the Square APIs. For example, your application must be set up to use the target Square SDK and your code must initialize the SDK client object.

After you paste the request from API Explorer into your application, you can add application-specific logic for handling success and failure conditions in the response code blocks.

Test access permissions Permalink Get a link to this section

All requests to Square endpoints require a bearer access token in the Authorization header. If you are signed in to your Square developer account, you can choose an access token for your application that provides read and write permissions to all Square APIs.

To test the OAuth permissions required for your application, you can also paste an access token into the Access token field. This can be an access token for another Sandbox test account or one that you obtain through the OAuth API. You can configure the permissions for these accounts and then check the responses to make sure that your application handles success and failure scenarios.

Note

In the Sandbox environment, the application and default test account are issued the same access token.

For more information, see the following topics:

Get started with API Explorer Permalink Get a link to this section

The following procedure describes how to use API Explorer to send simple GET and POST requests to Square APIs. For more information about working with Square APIs, see Using the REST API.

Before you begin Permalink Get a link to this section

To get started with API Explorer, all you need is a Square developer account and an application. You can access your applications and create new applications from the Developer Dashboard.

If you do not have a Square developer account, you can quickly create a free account and an application.

  1. At the top of this page, choose Sign up.

  2. Enter your email address, create a password, and select your country. Choose Continue.

  3. On the Applications page, choose Create your first application.

  4. Enter a name for your application and agree to the Square Developer Terms of Service. Choose Save.

Step 1: Sign in and get an access token Permalink Get a link to this section

First, sign in and choose your access token. All requests to Square APIs require an access token.

  1. In your web browser, sign in to API Explorer with your Square developer account.

  2. Keep Sandbox selected at the top of the page. Square recommends using resources in your Sandbox environment when testing Square APIs.

  3. For Access token, choose Get Token.

    API Explorer in Sandbox mode with the "Get Token" button highlighted

  4. Choose an access token. API Explorer uses this token in the Authorization header of your requests. For more information, see Test access permissions.

Now you are ready to send requests to Square APIs.

Step 2: Send a GET request Permalink Get a link to this section

Try sending a GET request.

  1. On the Select API menu, choose Locations. By default, this loads the ListLocations endpoint.

    API Explorer displays the HTTP method and path for the endpoint, along with a description and link to the endpoint documentation in the Square API Technical Reference.

    Note the Request and Response panes:

    • The Request pane displays a cURL request that includes the endpoint URL and required headers. cURL is selected by default, but you can optionally select a language for supported Square SDK platforms. For more information, see Generate language-specific requests for your applications.

    • The Response pane displays the JSON response after you run the request.

      The "List locations" endpoint selected in API Explorer

      Did you know?

      To view the request or response in a larger window, choose the expand button in the Request or Response pane.

  2. To run the request, choose Run Request at the top of the page.

    • If the request succeeds, the API returns a 200 status code and a JSON object that represents your locations. The response should contain the location that was automatically added to your Sandbox environment.

    • If the request fails, the API returns an error status code and message.

Step 3: Send a POST request Permalink Get a link to this section

Next, try sending a POST request.

Many endpoints require a URL parameter or request body or they accept query parameters. For these endpoints, API Explorer displays fields where you can provide parameter and property values. The information you provide is dynamically added to the request.

  1. Select Customers and Create customer. Note that the Request pane displays a partial request that contains an empty body.

    The "Create customer" endpoint selected in API Explorer

    The page form displays fields for all required and optional properties in the request. If the property is an object data type, choose Add to expand it.

    • To see the description for a property, choose the property name.

    • To see the description for an object, choose the object name. For example, for the address property, choose Address.

  2. Enter a value for at least one of the following fields: given_name, family_name, company_name, email_address, or phone_number.

  3. For idempotency_key, choose Generate. This generates a random GUID that represents a unique ID for this request.

  4. Run the request.

    • If the request succeeds, the API returns a 200 status code and a JSON object that represents the new customer.

    • If the request fails, the API returns an error status code and message.

  5. To view the new customer in the Sandbox Seller Dashboard:

    1. Open the Developer Dashboard.

    2. In the Sandbox Test Accounts section, choose Open for your test account.

    3. In the Sandbox Seller Dashboard, from the Apps pane, choose Customers.

Requirements and limitations Permalink Get a link to this section

The following requirements, considerations, and limitations apply for using API Explorer:

  • To interact with resources in your account, you must sign in to API Explorer with a Square developer account. Your account must contain at least one application.

    Note

    If you do not have a Square developer account, you can choose Sign up at the top of this page to create a free account and an application. For more information, see Before you begin in Get started with API Explorer.

  • API Explorer supports only publicly available Square APIs (also known as Connect v2 APIs). The following APIs, SDKs, and plugins are not supported:

    • Connect v1 APIs

    • Mobile APIs, SDKs, and plugins:

      • Reader SDK

      • Point of Sale API

      • In-App Payments SDK and plugins

    • Square Payment Form

  • Deprecated Square APIs might not be available.