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.
Important
Some Connect v1 functionality isn't implemented in the Square API due to low usage. Where possible, the applicable migration guide provides an alternative approach.
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/orders
, which makes the full endpoint URL:
The following sections outline the behavioral differences between Connect v1 APIs and Square APIs.
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.
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.
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.
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.
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.
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 doesn't 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 doesn't include a cursor
field. For more information, see Pagination.
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 the Webhooks API. To migrate, client can use the Webhook Subscriptions API or manually subscribe to webhooks from the Developer Dashboard.
The Connect v1 API collection includes the V1SubmitBatch
endpoint, 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.
API | Endpoint | Description |
---|---|---|
BookingCustomAttributes | BulkDeleteBookingCustomAttributes | Deletes custom attributes for bookings. |
BookingCustomAttributes | BulkUpsertBookingCustomAttributes | Creates or updates custom attributes for bookings. |
Bookings | BulkRetrieveBookings | Retrieves bookings. |
Catalog | BatchDeleteCatalogObjects | Deletes catalog items. |
Catalog | BatchRetrieveCatalogObjects | Retrieves catalog objects. |
Catalog | BatchUpsertCatalogObjects | Creates or updates catalog objects. |
CustomerCustomAttributes | BulkUpsertCustomerCustomAttributes | Creates or updates custom attributes for customer profiles. |
Inventory | BatchChangeInventory | Applies adjustments and counts to the provided item quantities. |
Inventory | BatchRetrieveInventoryChanges | Returns historical physical counts and adjustments based on filter criteria. |
Inventory | BatchRetrieveInventoryCounts | Returns current counts for the specified catalog objects. |
LocationCustomAttributes | BulkDeleteLocationCustomAttributes | Deletes custom attributes for locations. |
LocationCustomAttributes | BulkUpsertLocationCustomAttributes | Creates or updates custom attributes for locations. |
MerchantCustomAttributes | BulkDeleteMerchantCustomAttributes | Deletes custom attributes for a merchant. |
MerchantCustomAttributes | BulkUpsertMerchantCustomAttributes | Creates or updates custom attributes for a merchant. |
OrderCustomAttributes | BulkDeleteOrderCustomAttributes | Deletes custom attributes for orders. |
OrderCustomAttributes | BulkUpsertOrderCustomAttributes | Creates or updates custom attributes for orders. |
Orders | BatchRetrieveOrders | Retrieves orders. |
Team | BulkCreateTeamMembers | Creates team members. |
Team | BulkUpdateTeamMembers | Updates team members. |
Vendors | BulkCreateVendors | Creates vendors, which represent suppliers to a seller. |
Vendors | BulkRetrieveVendors | Retrieves vendors. |
Vendors | BulkUpdateVendors | Updates vendors. |
Note
Unlike transactional batch operations, individual operations in a bulk request can be successfully processed even if other operations in the request fail.
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.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.