General Guidance

Behavioral differences

The sections below outline the basic 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

Connect v1 APIs were released before Square implemented versioning and are therefore not versioned.

Square APIs use a Square-Version header to control breaking changes over time. The Square-Version naming scheme is YYYY-MM-DD, which indicates the date the version was released.

Square pins newly created apps in the Developer Portal to the most recent Square-Version. Pinning an app sets a default Square-Version for the app, which can be reviewed and updated at any time on the settings pages for the app.

The pinned default Square-Version determines how API requests are processed by Square. The default value can be overridden by setting the Square-Version header in the HTTPS request as shown in the following example:

curl https://connect.squareupsandbox.com/v2/payments \
  -X GET \
  -H 'Content-Type: application/json' \
  -H 'Square-Version: 2020-01-22'

For more information, see the full Square Versioning Overview.

Monetary amounts

In Connect v1 APIs, V1Money fields are alwys 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 (e.g., amounts related to collecting taxes and tips).

• Monetary values are negative if they represent a decrease in the amount of money an account receives (e.g., 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 for the field.

Dates

All Square endpoints expect dates and timestamps as strings in UTC (e.g., "2013-01-15T00:00:00Z") or offset from UTC to indicate time zone (e.g., "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 may require 1 of 2 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 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 webhook through the Developer Portal. For more information, see Webhooks v2: 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 (e.g., 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.