Using the REST API

The Square API follows the general patterns of REST. You manage the resources of a Square account (items, payments, orders, etc.) by making HTTPS requests to URLs that represent those resources. See them all in the API Reference.

Note: If you are using Ruby, Python, Node.js, PHP, C# (.NET), or Java, there are also language-based SDKs that provide convenient wrappers for the Square APIs.

Before you call the Square API, you need two things:

  • A Square account. If you don’t have one already, sign up for a developer account.

  • An application. If you don’t have one already, go to your Developer Dashboard and create your first application. All you need to do is give it a name. When you’re doing this for your production application, enter the name as you would want a customer to see it.

If you know a few patterns, you’ll be able to call any Square API. Let’s cover the important ones.

Production versus Sandbox
Permalink Get a link to this section

A Square account is comprised of a production account and one or more sandbox accounts.

Your production account is where you manage the resources (items, orders, payments, etc) that you use to do your actual business.

Your sandbox accounts are isolated environments where you test your applications as you build your application and prepare it for production.

Because production and sandbox accounts are separated, you use credentials and a base URL that is specific to them. We’ll call these out when they are different from each other.

Get an access token
Permalink Get a link to this section

To use the Square API, you need to create an application (or use an existing one) in the Developer Dashboard and an access token for that application.

You must provide an access token with every Square API call. An access token has specific permissions to resources in a specific Square account. Use an access token that is appropriate for your use case. There are two options:

  • To manage the resources for your own Square account, use the Personal Access Token for the application created in your Square account.

  • To manage resources for other Square accounts, use OAuth to ask owners of the accounts you want to manage for resource permissions so that you can work on their behalf. OAuth lets you define the specific resources to request access to and provides an OAuth access token and refresh token with approved permissions for their account. For more information, see the OAuth overview.

Important: For both use cases, make sure you store and access the tokens securely.

Production and sandbox accounts use access tokens that are specific to those accounts. Get an access token for the account you want before you create an HTTPS request.

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.

Let’s start with a basic request. To keep it simple, we’ll use cURL.

The following cURL command passes a JSON object containing the values used to create a new customer in a production account using the Create Customer endpoint:

curl https://connect.squareup.com/v2/customers \
  -X POST \
  -H 'Authorization: Bearer SQ_PRODUCTION_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"
  }'

where SQ_PRODUCTION_ACCESS_TOKEN is a valid Square access token and KEY_UNIQUE_TO_THIS_OPERATION is a unique value ( idempotency key) that you generate for this particular create operation.

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

{
  "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"}
}

Now that you’ve seen what a Square API call looks like, let’s go through it line by line.

Access a resource by URL
Permalink Get a link to this section

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

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

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

However, there are three important things to know:

  • You must use the HTTPS protocol.

  • Production and Sandbox accounts have different base URLs. Make sure you use the base URL for the account type that you intend to use.

    Production: https://connect.squareup.com/v2

    v2 Sandbox: https://connect.squareupsandbox.com/v2

  • The current major version of the Square is version 2. Make sure that v2 is in the resource path just after the host name. Production accounts use https://connect.squareup.com/v2 and v2 Sandbox accounts use https://connect.squareupsandbox.com/v2

For our example, we call the Create Customer endpoint in a production account using the following URL:

https://connect.squareup.com/v2/customers

If you wanted to call the endpoint for a sandbox account, you would use this instead:

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

Most resources have straightforward resource paths that are the names of the resources such as the Customers API.

Specify the HTTP method
Permalink Get a link to this section

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

  • GET to read or list resources

  • POST to create

  • PUT to update

  • DELETE to delete

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

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

Set the headers
Permalink Get a link to this section

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

In the example, the call specifies three headers:

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

where SQ_ACCESS_TOKEN is a valid Square access token and Square-Version specifies the version of the Square API so that you are explicit about the version and feature set you are building against.

All REST requests to Square API endpoints must include the following HTTP headers (some operations will require additional ones):

  • Authorization contains the credentials used for the call as well as the type. The Square access token is a bearer token.

  • Accept specifies the type of data returned in the call.

  • Square-Version specifies the version of the Square API

Important: Make sure that the access token matches the environment (production or sandbox) you want to access. Production and sandbox have different base URLs. For example, if you specified https://connect.squareupsandbox.com/v2/customers, you are working against v2 Sandbox and you must use the access token for the sandbox account whose resources you want to manage. When developers move back and forth between sandbox and production, a common error is specifying the token for the wrong account type.

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, search, etc.) as a JSON object.

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

curl https://connect.squareup.com/v2/customers \
  -X POST \
  -H 'Authorization: Bearer SQ_PRODUCTION_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"
  }'

where SQ_PRODUCTION_ACCESS_TOKEN is a valid Square access token and KEY_UNIQUE_TO_THIS_OPERATION is a unique value (idempotency key) that you generate for this particular create operation. A successful call returns a response with status code 200 and a response body with the new customer represented as a JSON object that looks like this:

{
  "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"}
}

Use idempotency for create, update, or other calls that you want to avoid calling twice. An idempotency key enables you to uniquely identify a specific action on a resource. To make an idempotent API call, you add the idempotency_key with a unique value in the request body.

If you retry the call and a resource with that idempotency key has already been created, the response will return a 200 status code and a response body containing the details of the existing resource.

If you retry the call keeping the same idempotency key but changing any of the details of the request, you would get a 400 Bad Request status code with an error that looks like this:

{
    "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
Permalink Get a link to this section

List operations use query string parameters to specify how to return the list of resources.

For example, the List Payments endpoint enables you to filter the list of payments returned by total amount, card brand, last four digits of the credit card, etc. The following cURL command returns the list of payments for Visa cards (there could be multiple) with 1234 as the last 4 digits in the card number:

curl 'https://connect.squareup.com/v2/payments?card_brand=VISA&last_4=1234' \
  -X GET \
  -H 'Authorization: Bearer SQ_ACCESS_TOKEN' \

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 will return 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 resource(s) 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 status code 200. Create and update operations will return the details of the resources operated on. List and search operations will also return a cursor if there is another page of resources to return.

In the previous Create Customer example, a successful call returned a JSON object representing the new customer and it looked like this:

{
  "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"}
}

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 Create Customer call above. In general, the object type is the lower cased name of the API (for example, customer, order, payment, etc.). 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 List Customer 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 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. When a request returns an error, you can get details about the error by reading the response. The HTTP status code tells you the type of error. The response body is JSON containing an errors list with detailed descriptions about the error. For example, the following response body is for a 401 Unauthorized caused by specifying an access token that is not authorized to make the call:

{
    "errors": [
        {
            "category": "AUTHENTICATION_ERROR",
            "code": "UNAUTHORIZED",
            "detail": "This request could not be authorized."
        }
    ]
}

You can read about error categories and codes in the API Reference.