Using the REST API

Learn how to use the Square API (REST) to manage HTTPS requests.

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 Square API Reference.

Before you call the Square API, you need two items: a Square account and an application created in the Developer Console. 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.

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.

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:

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2019-08-14' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "given_name": "Lauren",
    "family_name": "Noble"
  }'

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:

{
  "customer":{
    "id":"N6XSAFC2Y8T01B32ZW1X2WBSJM",
    "created_at":"2019-09-23T18:39:30.671Z",
    "updated_at":"2019-09-23T18:39:31Z",
    "given_name":"Lauren",
    "family_name":"Noble",
    "preferences":{
      "email_unsubscribed":false
    },
    "creation_source":"THIRD_PARTY",
    "version":0
  }
}

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

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

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

curl https://connect.squareupsandbox.com/v2/customers \

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.

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:

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \

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

In the following example, the call specifies three headers:

curl https://connect.squareup.com/v2/customers \
  -X POST \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Accept: application/json' \
  -H 'Square-Version: 2019-09-25' \

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're 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 Console) is assumed. For more information, see Versioning in Square APIs.

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:

curl https://connect.squareupsandbox.com/v2/customers \
  -X POST \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Accept: application/json' \
  -H 'Square-Version: 2019-08-14' \
  -d '{
    "idempotency_key": "KEY_UNIQUE_TO_THIS_OPERATION",
    "given_name": "Lauren",
    "family_name": "Noble"
  }'

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:

  {
      "errors": [
          {
              "category": "INVALID_REQUEST_ERROR",
              "code": "IDEMPOTENCY_KEY_REUSED",
              "detail": "The idempotency key can only be retried with the same request data.",
              "field": "idempotency_key"
          }
      ]
  }

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:

curl 'https://connect.squareupsandbox.com/v2/payments?card_brand=VISA&last_4=1234' \
  -X GET \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Accept: application/json'

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.

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.

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's 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:

{
  "customer":{
    "id":"N6XSAFC2Y8T01B32ZW1X2WBSJM",
    "created_at":"2019-09-23T18:39:30.671Z",
    "updated_at":"2019-09-23T18:39:31Z",
    "given_name":"Lauren",
    "family_name":"Noble",
    "preferences":{
      "email_unsubscribed":false
    },
    "creation_source":"THIRD_PARTY",
    "version":0
  }
}

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 isn't returned in the response.

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

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.

• Square SDKs
• Square video: The Sandbox - Idempotency
• Square blog: Understanding the Essentials of Idempotency