General Guidance for Migrating from Connect v1 APIs

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 migration guides listed in Migrate from Deprecated APIs.

All Connect v1 APIs have been deprecated. Square strongly recommends against using Connect v1 APIs in your applications. You should migrate affected code before the functionality is retired and permanently disabled. Deprecated endpoints are clearly flagged in the API Reference and Square provides migration guides for affected developers. For more information about how Square handles API deprecation and retirement, see Square API Lifecycle.

Link to section

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/orders, which makes the full endpoint URL:

connect.squareup.com/v2/orders

Link to section

Behavioral differences

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

Link to section

Versioning

The Square API uses the YYYY-MM-DD version-naming scheme, which indicates the date that the API version is released. This versioning scheme is used to control breaking changes and lets you test newer API versions before upgrading. The API version applies to all Square APIs, such as the Payments API, Orders API, and Customers API.

Each application that you create in the Developer Dashboard has a default API version, which you can view or update on the Credentials page. The default API version is pinned to the application and used for all requests unless overridden by the Square-Version header.

The following request doesn't include the Square-Version header, which directs Square to use 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 the default by explicitly specifying an API version in the Square-Version header in your request. This feature enables developers to test different API versions.

curl https://connect.squareup.com/v2/payments \
  -H 'Square-Version: 2022-12-14' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Regardless of whether you explicitly specify a version in the request, the response always returns the Square-Version header so you know which API version is used.

The release notes describe the changes in each API version. After learning about changes from the release notes, you can test migrations by explicitly specifying the preferred Square-Version in your requests.

For more information, see Versioning in Square APIs.

Link to section

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 don't have an implicit transfer direction:

• Some Money fields are bidirectional, which means they can hold positive or negative amounts. Bidirectional field descriptions in the API Reference 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 API Reference indicate the assigned meaning and transfer direction of the field.

Link to section

Dates

Square endpoints generally 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. For more information, see Working with 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.

Link to section

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 doesn't 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 doesn't include a cursor field. For more information, see Pagination.

Link to section

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."
    }
  ]
}

Link to section

Webhooks

In Connect v1, clients subscribe to webhooks through the Webhooks API. To migrate, client can use the Webhook Subscriptions API or manually subscribe to webhooks from the Developer Dashboard.

Link to section

Batching

The Connect v1 API collection includes the V1SubmitBatchendpoint, which bundles multiple v1 API requests as a single request. The Square API collection doesn't include a generic batching endpoint.

The following Square APIs provide explicit batch or bulk functionality. All other batch or bulk operations must be replaced with repeated, separate calls to the relevant Square API endpoint.

Link to section

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. For more information about migrating your application to use the new tokens, see Migrate to the Square API OAuth Flow.