Learn how to use the Square API (REST). You manage the resources of a Square account by making HTTPS requests to URLs that represent those resources.
Build Basics

Using the REST API

The Square API follows the general patterns of REST. Applications can manage the resources (such as payments, orders, and catalog items) of a Square account by making HTTPS requests to URLs that represent those resources. For a list of Square resources and operations, see API Reference.

Overview Permalink Get a link to this section

Before you call the Square API, you need two items: a Square account and an application created in the Developer Dashboard. The application provides you with credentials (for use in production applications and for testing in the Square Sandbox). Note that:

  • To access resources in your own account, you use a personal access token.

  • To manage resources in other Square accounts, use OAuth to ask the account owner for resource permissions so that you can work on their behalf. For more information, see OAuth API Overview.

For information about creating a Square account and an application, see Get Started.

If you know a few patterns, you can call any Square API. The following sections introduce the common patterns. cURL examples are used to keep it simple.

Note

Instead of making REST API calls in your applications, you might choose to use language-based SDKs that provide convenient wrappers for the Square APIs.

Create an HTTPS request Permalink Get a link to this section

To perform operations on a resource, you make an HTTPS request that specifies the URL for the resource to act on, as well as the appropriate headers, method, request body, and query parameters.

For example, the following cURL command passes a JSON object containing the values used to create a new customer in a Square Sandbox account using the CreateCustomer endpoint:

In the request:

  • {ACCESS_TOKEN} is a valid Square access token.

  • {UNIQUE_KEY} is a unique value (an idempotency key) that you provide for this particular create operation.

A successful call returns a response with 200 status code and a response body with the newly created customer represented as a JSON object that looks like the following:

Now that you have seen what a Square API call looks like, you can review it line by line.

Specify a resource URL Permalink Get a link to this section

You access a resource with its URL. See the URLs for each resource in the Square API Technical Reference.

In the example, the first line of the preceding cURL command specifies the URL for the resource you want to work with:

Note the following:

  • Production and Sandbox environments have different base URLs:

    • For Production accounts, use https://connect.squareup.com/v2.

    • For Sandbox accounts, use https://connect.squareupsandbox.com/v2.

  • The current major version of the Square API is version 2. Make sure that V2 is in the resource path after the host name.

Specify the HTTP method Permalink Get a link to this section

You specify an HTTP method to perform an action on a resource. The common actions in the Square API are:

  • GET to read or list resources.

  • POST to create.

  • PUT to update.

  • DELETE to delete.

In the following example, the call is creating a customer and uses the POST method:

Set the headers Permalink Get a link to this section

You use HTTP headers to specify additional information about the call.

In the following example, the call specifies three headers:

Note the following:

  • Authorization. This header is required. It contains the credentials used for the call and the type. The Square access token is the bearer token.

    Important

    The resource URL determines whether you are accessing resources in the Production or Sandbox account. You must use a valid access token accordingly.

  • Accept. You provide this header to specify the type of data the calls return. Currently, application/json is supported.

  • Square-Version. Specifies the Square API version. If not provided, the default API version associated with the application (in the Developer Dashboard) is assumed. For more information, see Versioning in Square APIs.

Create the request body Permalink Get a link to this section

Typically, you use the request body to pass complex parameters (for operations such as create, update, and search) as a JSON object.

In the following example, the call has a request body containing a JSON object with the values used to create a new customer:

Idempotency works as follows:

  • After a resource is created, if you retry the call using the same idempotency key and same request details, the response returns a 200 status code and a response body contains the details of the existing resource.

  • If you retry the call using the same idempotency key and change any of the request details, you get a 400 Bad Request status code with an error that looks like the following:

Did you know?

You can watch Square video: introduction to idempotency for a quick multimedia tutorial of the concept.

Specify query string parameters Permalink Get a link to this section

Use query string parameters for sorting, filtering, or paging in list operations. List operations use query string parameters to specify how to return the list of resources.

For example, the ListPayments endpoint lets you filter the list of payments returned by the card brand, last four digits of the credit card, and other attributes. The following cURL command returns the list of payments for Visa cards (there could be multiple) with 1234 as the last four digits in the card number:

All list and search operations are paginated and have a page size that specifies the number of resources returned in a single list endpoint call. A call to a list or search operation returns a cursor value if there are additional pages to return.

Handle the response Permalink Get a link to this section

API calls return a JSON object that contains the resources requested or an errors list. Check the response status code to see whether the response succeeded or failed.

Success responses Permalink Get a link to this section

Successful responses are marked by an HTTP 200 status code. Create and update operations return the details of the resources operated on. List and search operations also return a cursor if there is another page of resources to return.

In the previous CreateCustomer example, a successful call returned a JSON object representing the new customer and it looked like the following:

Read the response payload:

  • For an operation on a single object, the response contains a single JSON object named with the type of resource it is. For example, it is customer for the previous CreateCustomer call.

    In general, the object type is the lowercase name of the API (for example, customer, order, and payment).

  • For list and search operations, the response contains a named array (the name is the plural of the object type; for example, customers for a ListCustomer response) and a cursor value if there are additional objects in the list. If there are no objects for a list call to return, it returns an empty JSON object.

    Check the cursor for list and search operations. Make sure you get all items returned in a list call by checking for the cursor value returned in the response. When you call a list or search endpoint the first time, you set the cursor to an empty string or omit it in the request. If the response contains a cursor value, you call the API again to get the next page of items using that cursor value and continue to call that API with the cursor from the previous call until a cursor is not returned in the response.

Error responses Permalink Get a link to this section

Non-200 HTTP status codes are errors. For more information, see Handling Errors.

Note

If your application sends a high number of requests to Square APIs in a short period of time, Square might temporarily stop processing your requests and return RATE_LIMITED errors.

Your application should monitor responses for 429 RATE_LIMITED errors and use a retry mechanism with an exponential backoff schedule to resend the requests at an increasingly slower rate. It is also a good practice to use a randomized delay (jitter) in your retry schedule.

Additional build basics considerations Permalink Get a link to this section

There are several other introductory topics provided for a new developer to quickly learn the basics of developing applications with Square. For more information, see Basics of Building Applications with Square.

Related topics Permalink Get a link to this section

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.