Articles in this section

Migrate from deprecated Square API endpoints

Links:

Square has announced retirement dates for many of its existing transaction and employee-related API endpoints. If you have any existing integrations with Square, it’s important to review your existing flows to ensure they do not call the endpoints scheduled for retirement.

This article explains how to find deprecated endpoints, replace them with the new endpoints, and apply transformation rules.

Endpoint replacement list

Square APIs are typically deprecated at least 12 months before permanent retirement. The following table lists the endpoints scheduled for retirement in the near future:

Deprecated endpoints

Replacement endpoint

Retirement date

ListEmployeeWages

List team member wages

2021-08-26

Get employee wage

Get team member wage

2021-08-26

ListEmployees

Search team members

2021-08-26

RetrieveEmployee

Retrieve team member

2021-08-26

List refunds, List transactions

SearchOrders

2021-09-01

Charge

Create Payment

2021-09-01

Retrieve transaction

BatchRetrieveOrders

2021-09-01

Capture transaction

Complete payment

2021-09-01

Create refund

Refund payment

2021-09-01

Void transaction

Cancel payment

2021-09-01

A. Find deprecated endpoints in existing flows

Find each import and export that uses a Square connection:

  1. From the Resources menu, navigate to Connections.

  2. Search for Square.

  3. In your first matching Square connection, from the Actions overflow (...) menu, select Used by. A list of all items that use this connection appears.

  4. Right-click the first flow step in the list and select your browser’s option to open it in a new tab.

  5. Review the configuration for any of the deprecated endpoints listed in the table below:

API name

Operation

Transactions(Export)

ListRefunds, ListTransactions , Retrieve transaction

Employees

ListEmployees, RetrieveEmployee

Labor

ListEmployeeWages, Getemployeewage

Transaction(Import)

Capture transaction, Create refund, Void transaction, Charge

When you encounter a deprecated endpoint, first copy the path parameter and search parameter values to a reference document to back them up when replacing the endpoints, following the instructions in the next section.

Examples of each type of parameter replacement

Deprecated

Replacement

begin_time

updated_at.start_at

end_time

updated_at.end_at

sort_order

sort_order

4403216091163-Path_parameters_in_used_in_deprecated_operations.png

Path parameters used in deprecated operations

4403222669467-Search_parameters_used_in_deprecated_operations.png

Search parameters used in deprecated operations

4403216118043-Search_and_path_parameters_updated_in_replacement_operations.png

Search and path parameters updated in replacement operations

B. Update flows to use replacement endpoints

For each export or import containing a reference to a deprecated API name and operation, convert it to the replacement API name and operation.

Deprecated

Replacement

API name

Operation

API name

Operation

Transactions(Export)

ListRefunds

Orders

Search Orders

Transactions(Export)

ListTransactions

Orders

SearchOrders

Transactions(Export)

Retrieve transaction

Orders

BatchRetrieveOrders

Employees

ListEmployees

Team

Search team members

Employees

RetrieveEmployee

Team

Retrieve team member

Labor

ListEmployeeWages

Labor

List team member wages

Labor

Getemployeewage

Labor

Get team member wage

Transaction(Import)

Capture transaction

Payments

Complete payment

Transaction(Import)

Create refund

Refunds

Refund payment

Transaction(Import)

Void transaction

Payments

Cancel payment

Transaction(Import)

Charge

Payments

Create Payment

Example of a deprecated operation and the replacement operation

If the existing export is configured with API name: Transactions and Operation: ListTransactions, then it should be converted to API name: Orders and Operation: SearchOrders.

4403222681243-Export_using_deprecated_operation.png

Export using a deprecated operation

Location Id is a path parameter in a deprecated operation; in the new operation instead pass it in Search parameters.

After_using_replacement_Operation-_2.png

After using the replacement operation

After_using_replacement_Operation-_1.png

Configure body paramaters launched

C. Add transformation rules

The responses from the deprecated Square endpoints and the replacement endpoints are different, as shown in the following example:

4403216145563-Compare_Doc.png

In the deprecated endpoint’s response, the field name was first_name, whereas in the response of the new endpoint it is given_name. Also, the path was employee.first_name, but in the response of the new endpoint it is team_member.given_name.

Left as is, these dueling fields will affect your import mapping . To avoid referencing nonexistent fields, you can add transformation rules to the export. After converting the new response data format to the old one, the mapping should work correctly.

Example of response formats

ListRefunds, deprecated operation response format:

{
  "refunds": [
    {
      "id": "b27436d1-7f8e-5610-45c6-417ef71434b4-SW",
      "location_id": "18YC4JDH91E1H",
      "transaction_id": "KnL67ZIwXCPtzOrqj0HrkxMF",
      "tender_id": "MtZRYYdDrYNQbOvV7nbuBvMF",
      "created_at": "2016-01-20T00:28:18Z",
      "reason": "some reason",
      "amount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "additional_recipients": [
        {
          "location_id": "057P5VYJ4A5X1",
          "description": "Application fees",
          "amount_money": {
            "amount": 10,
            "currency": "USD"
          }
        }
      ],
      "status": "APPROVED"
    }
  ]
}

Search Orders, replacement endpoint new operation response format:

{
  "orders": [
    {
      "id": "KwGenMpg46lpgtcMXGWMmGWaZOPZY",
      "location_id": "8TY75SDX0QV43",
      "created_at": "2021-04-02T12:00:40.760Z",
      "updated_at": "2021-04-02T12:00:43.000Z",
      "state": "COMPLETED",
      "version": 4,
      "closed_at": "2021-04-02T12:00:40.863Z",
      "refunds": [
        {
          "id": "PHulYsZzlAqI6F1mXt4oFmR8tvDPpqgpsAOKR743nmV",
          "location_id": "8TY75SDX0QV43",
          "transaction_id": "uuEulsnPhpvy83VUMcZZL9mFjgCZY",
          "tender_id": "90bEqcZ9N7JBXMwSPW4GYPxnd7IZY",
          "created_at": "2021-04-02T12:00:39Z",
          "reason": "Refund via API",
          "amount_money": {
            "amount": 2,
            "currency": "USD"
          },
          "status": "APPROVED"
        }
      ]
    }
  ]
}

To apply transformation rules and convert the data format, follow the instructions below:

  1. View the flow where you replaced the endpoint in Flow Builder.

  2. Click + to define a transformation (

    define_transformation.svg

    ) for the export. The Define transformation advanced field editor (AFE) opens.

List_Refunds.png
  • Using the format shown in the examples below, configure the transformation rules.

List_Transactions.png

ListTransactions converted to Search Orders

Batch_retrieve_orders_-_retrieve_transaction.png

Retrieve transaction converted to BatchRetrieveOrders

Repeat the process described in this article for each import/export that appears in the Used by list for your Square connection if you determine it references deprecated endpoints. If you have multiple Square connections, review all imports/exports where each connection is used.