Connect API Basics
v1 versus v2
Connect APIs come in 2 forms: Connect v2 and Connect v1.
The Connect v2 API suite supports online payments, order creation for itemized transactions, product catalog management, inventory management, and customer management.
The Connect v1 API suite supports webhooks and employee, role, and timecard management. Payment and item management functionality in the v1 suite is still fully supported but provided primarily for backward compatibility.
Connect v1 APIs, endpoints, data types, and enums are denoted with the prefix V1:
- Business management endpoints for employees, timecards, and drawer shifts are organized under the V1Employees API.
- Business management endpoints for locations and business information are organized under the V1Locations API.
- Item management endpoints for catalog items, item categories, discounts, fees, and Square Point of Sale customization are organized under the V1Items API.
- Transaction management endpoints for payments, settlements, refunds, and bank accounts are organized under the V1Transactions API.
Build with SDKs
Square offers SDKs in PHP, Ruby, Node.js, Java, .NET, and Python, to simplify development with Connect APIs. See the Square SDKs for a full list of available web and mobile SDKs.
Build with REST
Connect endpoints are hosted from the base URL https://connect.squareup.com
and use v1
or v2
in the endpoint path
to indicate whether they are in Connect v1 or Connect v2.
For example, the endpoint path for the the Connect v2 CreateOrder endpoint is /v2/locations/{location_id}/orders
which
makes the full endpoint URL:
connect.squareup.com/v2/locations/{location_id}/orders
Request headers
All REST requests to Connect API endpoints must include the following HTTP headers:
Authorization: Bearer SQ_ACCESS_TOKEN Accept: application/json
where SQ_ACCESS_TOKEN
is a valid Square access token.
POST
and PUT
requests must also include the following HTTP header:
Content-Type: application/json
Request parameters
GET
and DELETE
requests provide parameters in a URL-escaped query string appended to the request URL. For example,
including the value 2016-01-15T00:00:00+02:00
as the begin_time
parameter of the ListTransactions results in the
following request
URL:
https://connect.squareup.com/v2/locations/LOCATION_ID/transactions?begin_time=2016-01-15T00%3A00%3A00%2B02%3A00
POST
and PUT
requests provide parameters as JSON in the body of the request. For example, the body of a request to
the CreateCustomer endpoint looks like:
{ "given_name": "Amelia", "family_name": "Earhart" }
Responses
By default, all endpoint responses provide data as JSON in the response body and include a Content-Type: application/json
header.
Versioning
Square API versions (Square-Version
) track changes in the evolution of Connect v2 APIs. The Square-Version naming
scheme is YYYY-MM-DD
, which indicates the date the version was released. Connect v1 APIs are not versioned. Square
continues to support Connect v1, but future releases will focus on improving Connect v2 functionality.
By default, new Square applications are pinned to the version current at the time the application is created. Pinning an
application sets the default Square-Version
for the application. The default Square-Version
of an application can be
reviewed and updated at any time on the settings pages for the application.
See the Versioning Overview for more information.