General Guidance
Learn about the high-level differences between Connect v1 and Square APIs and review the general migration guidance. For API-specific migration guidance, see the list of API migration guides in Connect v1 Retirement.
Square hosts all endpoints from the base URL https://connect.squareup.com
and uses namespaces in the endpoint path to indicate a Connect v1 or Square (previously known as Connect v2) API.
Connect v1 APIs use the v1
namespace. For example, the endpoint path for the Connect v1 CreateCategory
endpoint is /v1/{location_id}/categories
, which makes the full endpoint URL:
Square APIs use the v2 namespace. For example, the endpoint path for the Square API CreateOrder
endpoint is /v2/locations/{location_id}/orders
, which makes the full endpoint URL:
Square uses the YYYY-MM-DD
API version-naming scheme, which indicates the date the API version was released. The API versioning scheme is used to control breaking changes.
Each application you create in the Developer Dashboard has a default API version associated with it. When you create an application (see Get Started), Square pins the latest API version to it as the default. This default is set only when you create a new application. As new API versions are released, you might choose to pin your application to the new API version after you test the API.
When you set an access token in your request, Square assumes the API version pinned to the application.
You can override this default by explicitly specifying an API version in a request by adding the Square-Version
request headers. This enables developers to test different API versions.
Regardless of whether you explicitly specify Square-Version
in the request, the response always returns the square-version
header so you know which API version is used.
Release notes in the developer documentation describes API changes. Developers can learn about the API changes from the release notes and test migrations by overriding the default API version (by explicitly setting the preferred Square-Version
in the HTTP header of REST calls to the Square API).
For more information, see Versioning in Square APIs.
In Connect v1 APIs, V1Money fields are always unidirectional and have an implicit transfer direction based on whether the associated amount is positive or negative:
Monetary values are positive if they represent an increase in the amount of money an account receives (such as, amounts related to collecting taxes and tips).
Monetary values are negative if they represent a decrease in the amount of money an account receives (such as, amounts related to discounts and refunds).
In Square APIs, Money fields can be bidirectional and do not have an implicit transfer direction:
Some
Money
fields are bidirectional, which means they can hold positive or negative amounts. Bidirectional field descriptions in the Technical Reference section of the Developer resource site indicate the meaning of a positive or negative value in the context of a given endpoint.Some
Money
fields are unidirectional, which means they can only hold positive amounts. Unidirectional field descriptions in the Technical Reference section of the Developer resource site indicate the assigned meaning and transfer direction of the field.
All Square endpoints expect dates and timestamps as strings in UTC (such as, "2013-01-15T00:00:00Z") or offset from UTC to indicate time zone (such as, "2013-01-15T00:00:00-08:00" for 8 hours behind UTC). Clients must account for daylight saving time when providing offset dates.
In Connect v1, date and timestamp strings always use ISO 8601 format:
Fields that only require a date value can use
YYYY-MM-DD
notation. For example, "2007-04-05".Fields that only require a time value can use 24-hour notation (
HH:MM:SS
). For example, "14:30:00".Fields that require a data and time value use
YYYY-MM-DDTHH:MM
notation. For example, "2007-04-05T14:30".
In Square APIs, fields might require one of two possible formats depending on how the field is used and whether it represents a date or a timestamp:
Fields that accept a partial date or time definition use ISO 8601 format. For example, the
start_date
field in a DateRange definition.Fields that require a full timestamp definition, including a timezone, use RFC 3339 format. For example, the
begin_time
field in a Catalog.SearchCatalogObjects request.
Pagination is available in Connect v1 and Square APIs, but the pagination token is packaged differently.
Connect v1 endpoints that support paginated results include a URL value in the Link
field of response header. For example:
To fetch the next set of results, clients send the original request to the provided URL. The final set of results does not include a Link
URL.
Square API endpoints that support paginated results include a cursor
field in the response body. For example:
To fetch the next set of results, clients send requests to the same URL with the cursor
field set in the request body. The final set of results does not include a cursor
field.
Connect v1 APIs return different responses for success and failure. Error responses indicate a single error type and a human-readable message describing the error. For example:
Square APIs set different response fields for success and failure. In the case of an error, the errors field in the response body contains an array of Error objects that describe the failure. For example:
In Connect v1, clients subscribe to webhooks through a Webhooks API. Square APIs do not include a webhooks subscription API. Instead, applications subscribe to webhooks through the Developer Dashboard. For more information, see v2 Webhooks: What It Does.
The Connect v1 API suite includes a generic batching endpoint, V1SubmitBatch
, that bundles multiple v1 API endpoint requests as a single request. The Square API collection does not include a generic batching endpoint.
The following Square APIs provide explicit batching functionality. All other batching behavior that relies on V1SubmitBatch
must be replaced with repeated, individual calls to the relevant Square API endpoint.
Catalog API
BatchDeleteCatalogObjects. Supports cascading deletes of
CatalogObjects
.BatchRetrieveCatalogObjects. Returns a set of
CatalogObjects
, including child information (such as, associated item variations or modifier lists).BatchUpsertCatalogObjects. Creates or updates up to 10,000
CatalogObjects
, organized into batches.
Inventory
BatchChangeInventory. Applies adjustments and counts to the provided item quantities.
BatchRetrieveInventoryChanges. Returns historical physical counts and adjustments based on the provided filter criteria.
BatchRetrieveInventoryCounts. Returns current counts for the provided
CatalogObjects
at the requested locations.
Orders
BatchRetrieveOrders. Retrieves an unpaginated set of orders based on the provided IDs.
The Square API requires seller-scoped access tokens. Your app must migrate to the new seller-scoped tokens before making calls on the Square API. If your application requires multi-location sellers to select a location, you must migrate to the multi-location OAuth flow. Read Migrate to the Square API OAuth Flow to learn about migrating your application to use the new tokens.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.