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.

Behavioral differences

The following sections outline the behavioral differences between Connect v1 APIs and Square APIs.

Endpoint path

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:

connect.squareup.com/v1/{location_id}/categories

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:

connect.squareup.com/v2/locations/{location_id}/orders

Versioning

How Square API versioning works

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.

curl https://connect.squareup.com/v2/payments \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

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.

curl https://connect.squareup.com/v2/payments \
  -H 'Square-Version: 2021-05-13' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json'

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.

Monetary amounts

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.

Dates

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

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:

Link:<https://connect.squareup.com/v1/LOCATION_ID/payments?batch_token=BATCH_TOKEN>;rel='next'

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:

{
  "payments": [
    LIST_OF_PAYMENTS
  ],
  "cursor": "Q2g4SUF4SWJUVkpYYlZSTGVFSkVUbEpuZDJaT1UxcHdkRUZQTnpaNGRXRkNFSmVJNVBpOExRPT0"
}

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.

Errors

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:

{
  "type": "not_found",
  "message": "The resource specified in the request wasn't found.",
}

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:

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

Webhooks

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.

Batching

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.

OAuth access tokens

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.