Connect API Overview
The Connect API provides HTTP endpoints for the following types of tasks:
- Retrieving reports for your payments, refunds, settlements, and other merchant data
Common conventions for these endpoints are described here.
Connect API endpoints are hosted from the base URL
example, the List Payments
endpoint's full path is
An endpoint's API version is included in its path. Bug fixes and minor feature additions might be made to an endpoint's behavior without advancing its version number. This can include adding optional parameters or response fields. To prevent future compatibility issues, your application should be prepared to receive response fields beyond those currently returned by a given endpoint.
Functionality is never removed from a particular version of an endpoint, nor do field names or types change.
Currently, all Connect API endpoints have a single version (
Endpoint names and return values
An endpoint's name indicates the type of data it handles and the action it performs on that data. The most common actions are:
|List||Returns summary information for all entities that match query parameters you provide. To get comprehensive information for a particular entity, use the corresponding Retrieve endpoint.|
|Retrieve||Provides comprehensive information for the single entity that matches the identifier you provide.|
For example, the List Payments endpoint returns an array of processed payments.
Request and response headers
All of your requests to Connect API endpoints must include the following HTTP headers:
Authorization: Bearer YOUR_ACCESS_TOKEN Accept: application/json
In the place of
YOUR_ACCESS_TOKEN, provide your application's personal access token
(available from the Apps page).
By default, all endpoint responses provide data as JSON in the response body and include a
Content-Type: application/json header.
The way you provide parameters to a Connect API request depends on the HTTP method of the request.
GET requests, you provide parameters in a query string you append to your
request's URL. For example, you provide the
order parameter to the List Payments endpoint like so:
Parameter values must be URL-escaped. For example, to provide the value
2013-01-15T00:00:00+02:00 as the
begin_time parameter of the List Payments endpoint, you specify the following:
Working with dates
All representations of dates are strings in ISO 8601 format.
You can provide date strings that are either UTC (for example,
2013-01-15T00:00:00Z) or offset from UTC to indicate time zone (for
2013-01-15T00:00:00-08:00 for eight hours behind UTC). If you provide
offset dates, be sure to account for daylight saving time correctly, if applicable.
Date strings returned by the Connect API are always UTC.
List endpoints might paginate the results they return. This means that instead of returning all results in a single response, these endpoints might return some of the results, along with a response header that links to the next set of results. This header has the following format:
Send a followup request (including all usual headers) to the
next URL to
fetch the next set of results. Repeat this process until you receive a response without a
Handling duplicate results
List endpoints might return duplicate results. Use the
id attribute of the result
objects to identify any such duplicates.
Handling the enum value
Some Connect API enums (such as
BankAccount.Type) include the value
OTHER. If you retrieve an
object (such as a
BankAccount) that currently has the value
OTHER for one of its fields,
that field might have a different value if you retrieve the object again at a later
date, when an appropriate value has been added to the enum.
Enum values besides
OTHER never change retroactively.
Replacing a personal access token
If need to replace your application's personal access token, go to the Apps page and select your application. Click Replace Token next to the Personal Access Token field to generate a new token for your application. This invalidates your application's previous token.
Connect API endpoints use HTTP protocol status codes to indicate errors. Error code values range from 400 to 599.
All Connect API error responses provide a JSON object with the following fields:
|The type of error that occurred. This value does not change based on the locale of the request.|
|A user-readable message that's translated into the locale of the request. For unsupported locales, an English error message is provided.|
The following are the possible error types that correspond to each HTTP error code. Your application should be ready to handle any of these errors from any Connect API endpoint.
Bad Request (400)
|A required parameter was missing from the request.|
|The request included an invalid parameter.|
|The request was otherwise malformed.|
|Your application is not authorized to make this request.|
|Your application's access token was revoked.|
|Your application's access token has expired.|
Not Found (404)
|The resource specified in the request wasn't found.|
Internal Server Error (500)
|Square encountered an unexpected error processing the request.|
Service Unavailable (503)
|The Connect API service is currently unavailable.|