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.
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 |
Find each import and export that uses a Square connection:
-
From the Resources menu, navigate to Connections.
-
Search for Square.
-
In your first matching Square connection, from the Actions overflow (...) menu, select Used by. A list of all items that use this connection appears.
-
Right-click the first flow step in the list and select your browser’s option to open it in a new tab.
-
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.
|
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
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 |
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
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.
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:
-
View the flow where you replaced the endpoint in Flow Builder.
-
Click + to define a transformation (
) for the export. The Define transformation advanced field editor (AFE) opens.
-
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.