Migrate from deprecated Square API endpoints

Links:

• Square API reference on retirement date and migration
• Square deprecated endpoints list

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:

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:

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

Path parameters used in deprecated operations

Search parameters used in deprecated operations

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.

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.

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 the replacement operation

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:

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.

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

{
  "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 (  ) for the export. The Define transformation advanced field editor (AFE) opens.

3. Using the format shown in the examples below, configure the transformation rules.

ListTransactions converted to Search Orders

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.