Settlements V1 Migration

Migrate from the Square Settlements API Deprecated

This component is deprecated. See below for guidance about what to use instead.

Learn how to migrate an application from the Settlements API to the Payouts API.

To view payout data prior to January 2021, you need to use the V1 Settlements API.

Migration overview
ListSettlements field mappings
RetrieveSettlement field mappings
Reporting of Square internal transfers
Migrate V1 Settlements to the Payouts API

Link to section
Migration overview

The Payouts API replaces the Settlements API and provides new functionality to make it easier to get a list of deposits and withdrawals from a seller's bank accounts.

Link to section
Important dates

Deprecation: 2019-11-15
Retirement: 2023-06-16

Link to section
Get help

If you need help migrating to Square APIs or need more time to complete your migration, contact Developer Support, join our Discord community, or reach out to your Square account manager.

Link to section
New features in the Payouts API

The Payouts API provides all the functionality of the Settlements API and adds these features:

ListPayoutEntries endpoint - The ListPayouts endpoint provides summary-level information while a new ListPayoutEntries endpoint retrieves a list of all payout entries for a specific payout. The Settlements API doesn't differentiate between summary-level payout information and specific payout entry information.
Permissions - The Payouts API supports a new PAYOUTS_READ permission that replaces the SETTLEMENTS_READ permission for the OAuth scope. You can still use the SETTLEMENTS_READ permission, but you should migrate to the PAYOUTS_READ permission before Square retires the SETTLEMENTS_READ permission on June 16, 2023.
Transfer reporting scope - Payouts only show transfers from the Square balance to a seller's external bank account, a Square checking or savings account (available only in the United States), or a debit card (for instant transfers). Transfers from Square checking or savings account to an external bank account aren't reported by the Payouts API.
Pagination - The ListPayouts and ListPayoutEntries endpoints support pagination. You can specify the page size (the number of items to return in the response) using a limit field.
Reporting of transfers to Square Checking or Square Card - The total_amount field in the Payout object represents the sum of amounts of the individual transactions included in the payout. It excludes non-zero amount settlements for Square Checking (in the United States) or Square Card (in Canada). For more information, see Reporting of Square internal transfers.
Manual transfers - For manual transfers, the Payouts API generates payouts with individual payout entries, whereas the Settlements API generates a single payout entry of the OTHER type.
Payouts to Square Savings - SIMPLE payouts are created for all transfers to the Square Savings account (available only in the United States). These transfers show up as payout entries in the subsequent BATCH payout to deduct the amount of the SIMPLE payout.
Webhooks support - You can use webhooks in an application to get notification of a payout status change. For more information, see Square Webhooks Overview.
Sandbox support - You can create payments, refunds, or disputes using the Payments, Refunds, and Disputes APIs in the Sandbox environment and then retrieve the Payout objects containing those transactions on the next business day after you transfer the funds.

Link to section
Endpoints

The Payouts API endpoints replace the ListSettlements and RetrieveSettlements functionality in the Settlements API.

Deprecated Settlements API endpoint	Payouts API replacement endpoint
ListSettlements	ListPayouts
RetrieveSettlement	GetPayout and ListPayoutEntries

Link to section
ListSettlements field mappings

The ListSettlements endpoint is replaced by the ListPayouts endpoint. The following sections provide mapping information about the path parameters, query parameters, and response fields.

Link to section
Path parameter mappings

The following table shows how the V1 ListSettlements path parameters map to the ListPayouts endpoint:

V1 ListSettlements path parameter	ListPayouts path parameter	Notes
`location_id`	N/A	`location_id` is changed to a query parameter.

Link to section
Query parameter mappings

The following table shows how the V1 ListSettlements query parameters map to the ListPayouts endpoint:

V1 ListSettlements query parameter	ListPayouts query parameter	Notes
`order`	`sort_order`
`begin_time`	`begin_time`	No longer requires ISO 8601 format for the date time. Now requires RFC 3339 format.
`end_time`	`end_time`	No longer requires ISO 8601 format for the date time. Now requires RFC 3339 format.
`limit`	`limit`
`status`	`status`	New status type: `PAID` indicates that the payout has successfully completed.
`batch_token`	`cursor`
N/A	`location_id`	The ID of the location associated with the payout.

The ID schema for settlement_id and payout_id aren't the same. You cannot directly map a V1 settlement_id to its corresponding payout_id in the V2 Payouts API. If your application is syncing historical payout records, it might have synced a payout under a different ID with the Settlements API.

Link to section
Response field mappings

The V1 ListSettlements endpoint returns settlement information as a Settlement object in the response body, whereas the ListPayouts endpoint returns a Payouts object.

V1 ListSettlements field	ListPayouts field	Notes
`items`	`payouts`	The requested list of payouts. For more information, see Payouts.
`bank_account_id`	`destination`	Banking destinations include bank accounts, Square checking accounts, or debit cards. For more information, see Destination.
`entries`	N/A	A new ListPayoutEntries endpoint retrieves a list of all payout entries for a specific payout.
`initiated_at`	`created_at`	The timestamp of when the payout was created and submitted for deposit to the seller's banking destination, in RFC 3339 format.
`status`	`status`	New status type: `PAID` indicates that the payout has succeeded.
`total_money`	`amount_money`	The amount of money involved in the payout.
N/A	`location_id`	The ID of the location associated with the payout.
N/A	`arrival_date`	The calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout is due to arrive in the seller’s banking destination.
N/A	`payout_fee`	A list of processing fees and any taxes on the fees assessed by Square for this payout.
N/A	`type`	Indicates whether the payout is a `BATCH` or `SIMPLE` type.
N/A	`updated_at`	The timestamp of when the payout was last updated, in RFC 3339 format.
N/A	`version`	The version number, which is incremented each time an update is made to this payout record.

Link to section
RetrieveSettlement field mappings

The RetrieveSettlement endpoint is replaced by the GetPayout and ListPayoutEntries endpoints. The following sections provide mapping information about the path parameters, query parameters, and response fields.

Link to section
Path parameter mappings

The following table shows how the V1 RetrieveSettlement path parameters map to the GetPayout and ListPayoutEntries endpoints:

V1 RetrieveSettlement path parameters	GetPayout and ListPayoutEntries path parameters
`location_id`	N/A
`settlement_id`	`payout_id`

Link to section
Query parameter mappings

The following table shows how the V1 RetrieveSettlement query parameters map to the ListPayoutEntries endpoint:

V1 RetrieveSettlement query parameters	ListPayoutEntries query parameters
N/A	`sort_order`
N/A	`cursor`
N/A	`limit`

Link to section
Response field mappings

The following table compares the fields for the V1 RetrieveSettlement and GetPayout endpoints:

V1 RetrieveSettlement field	GetPayout field	Notes
N/A	`payout`	The requested payout.
N/A	`location_id`	The ID of the location associated with the payout.
`status`	`status`	New status type: `PAID` indicates that the payout has succeeded.
`total_money`	`amount_money`	The amount of money involved in the payout.
`initiated_at`	`created_at`	The timestamp of when the payout was created and submitted for deposit to the seller's banking destination, in RFC 3339 format.
`bank_account_id`	`destination`	Banking destinations include bank accounts, Square checking accounts, or debit cards. For more information, see Destination.
`entries`	N/A	A new ListPayoutEntries endpoint retrieves a list of all payout entries for a specific payout.
N/A	`arrival_date`	The calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout is due to arrive in the seller’s banking destination.
N/A	`payout_fee`	A list of processing fees and any taxes on the fees assessed by Square for this payout.
N/A	`type`	Indicates whether the payout is a `BATCH` or `SIMPLE` type.
N/A	`updated_at`	The timestamp of when the payout was last updated, in RFC 3339 format.
N/A	`version`	The version number, which is incremented each time an update is made to this payout record.

The V1 RetrieveSettlement endpoint returns entries information as a SettlementEntry object in the response body, whereas the ListPayoutEntries endpoint returns a PayoutEntry object.

V1 RetrieveSettlement field	ListPayoutEntries field	Notes
`amount_money`	`net_amount_money`	The net proceeds from this transaction after any fees.
`fee_money`	`fee_amount_money`	The amount of Square fees associated with this payout entry.
N/A	`gross_amount_money`	The amount of money involved in this payout entry.
N/A	`payout_id`	The ID of the payout entry associated payout.
N/A	`effective_at`	The timestamp of when the payout entry affected the balance, in RFC 3339 format.
N/A	`type_{entry type}_details`	The `type_<payout entry type>_details` field in a payout entry contains information specific to the type of the payout entry. For more information, see ListPayoutEntries.

Link to section
Reporting of Square internal transfers

For transfers to Square Checking (in the United States) or Square Card (in Canada), the V1 Settlements API shows a settlement amount of 0 and includes the settled transactions and a negative amount entry labeled OTHER. Alternatively, the Payouts API only shows entries that are transferred (for example, CHARGE) and payout amounts are equal to the sum of the transferred entries.

The following example shows a V1 ListSettlements response with an entry type of OTHER and the settlement amount as 0:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
  "entries": [
    {
      "type": "CHARGE",
      "payment_id": "ZQmk5uDg0czPZ1ThYTD3dc7xuaB",
      "amount_money": {
        "currency_code": "USD",
        "amount": 662
      },
      "fee_money": {
        "currency_code": "USD",
        "amount": -28
      }
    },
    {
      "type": "OTHER",
      "amount_money": {
        "currency_code": "USD",
        "amount": -662
      },
      "fee_money": {
        "currency_code": "USD",
        "amount": 0
      }
    }
  ],
  "id": "poe_HbXoYjVE-_AQKvdp0TGnQ9fEntk",
  "status": "SENT",
  "initiated_at": "2022-06-08T23:47:34Z",
  "total_money": {
    "currency_code": "USD",
    "amount": 0
  }
}

The following example shows a ListPayouts response with the actual amount of the payout:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "id": "po_60602542-22e5-4e87-8c91-89736f9dfa1d",
  "status": "PAID",
  "location_id": "{LOCATION_ID}",
  "created_at": "2022-06-08T23:47:34Z",
  "updated_at": "2022-06-09T07:32:51.446Z",
  "amount_money": {
    "amount": 662,
    "currency_code": "USD"
  },
  "destination": {
    "type": "SQUARE_STORED_BALANCE",
    "id": "bact:cgvL1yv43VFjexample"
  },
  "version": 2,
  "type": "BATCH",
  "arrival_date": "2022-06-08"
}

The following example shows a ListPayoutEntries response with detailed information of the payout entry:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "payout_entries": [
    {
      "id": "poe_5DhstmLsgJD0x3Cym3Cnislc0KM",
      "payout_id": "po_070431e4-e351-11eb-a8bb-02420a140009",
      "effective_at": "2022-06-09T01:45:17Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 690,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 28,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 662,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "ZQmk5uDg0czPZ1ThYTD3dc7xuaB"
      }
    }
  ]
}

Link to section
Migrate V1 Settlements to the Payouts API

Link to section
ListSettlements to ListPayouts

The following example shows a request to retrieve settlements for a location ID:

curl "https://connect.squareup.com/v1/{location_id}/settlements" \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'Content-Type: application/json' | jq

The following shows the ListSettlements response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

[
  {
    "id": "3Z18MNWQ4MS57R5ESE2HXCSNJTXN",
    "status": "SENT",
    "initiated_at": "2022-03-29T16:12:31Z",
    "total_money": {
      "currency_code": "USD",
      "amount": 6259
    }
  },
  {
    "id": "3ZXJ24TPSSRD30B2BYXJ5WVS39VD",
    "status": "SENT",
    "initiated_at": "2022-03-28T06:41:51Z",
    "total_money": {
      "currency_code": "USD",
      "amount": 4733
    }
  },
  {
    "id": "3Z9A5VTRCAW15S507K5DTANAC7MS",
    "status": "SENT",
    "initiated_at": "2022-01-26T20:08:19Z",
    "total_money": {
      "currency_code": "USD",
      "amount": 3297
    }
  }
]

Example ListPayouts request

The following example shows a request to list payouts for the default location:

curl https://connect.squareup.com/v2/payouts \
  -H 'Square-Version: 2022-04-20' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'Content-Type: application/json'

The following shows the ListPayouts response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

{
  "payouts": [
    {
      "id": "po_0a295e5c-94c9-4f82-bd34-49bae1ced9ca",
      "status": "PAID",
      "location_id": "LCRS9JV5GZ9AZ",
      "created_at": "2022-03-29T16:12:31Z",
      "updated_at": "2022-03-30T01:07:22.875Z",
      "amount_money": {
        "amount": 6259,
        "currency_code": "USD"
      },
      "destination": {
        "type": "CARD",
        "id": "ccof:IpqfhXp0mDydFAiI4GB"
      },
      "version": 2,
      "type": "BATCH",
      "payout_fee": [
        {
          "amount_money": {
            "amount": 95,
            "currency_code": "USD"
          },
          "effective_at": "2022-03-29T16:12:31Z",
          "type": "TRANSFER_FEE"
        }
      ],
      "arrival_date": "2022-03-29"
    },
    {
      "id": "po_ec844d5b-39c3-4605-8f64-b14be0fceafc",
      "status": "PAID",
      "location_id": "LCRS9JV5GZ9AZ",
      "created_at": "2022-03-28T06:41:51Z",
      "updated_at": "2022-03-28T06:41:51Z",
      "amount_money": {
        "amount": 4733,
        "currency_code": "USD"
      },
      "destination": {
        "type": "CARD",
        "id": "ccof:IpqfhXp0mDydFAiI4GB"
      },
      "version": 1,
      "type": "BATCH",
      "payout_fee": [
        {
          "amount_money": {
            "amount": 72,
            "currency_code": "USD"
          },
          "effective_at": "2022-03-28T06:41:51Z",
          "type": "TRANSFER_FEE"
        }
      ],
      "arrival_date": "2022-03-28"
    },
    {
      "id": "po_4a8bbd61-8ae0-4b92-86e9-76b487b10481",
      "status": "SENT",
      "location_id": "LCRS9JV5GZ9AZ",
      "created_at": "2022-01-26T20:08:19Z",
      "updated_at": "2022-01-26T20:08:19Z",
      "amount_money": {
        "amount": 3297,
        "currency_code": "USD"
      },
      "destination": {
        "type": "CARD",
        "id": "ccof:IpqfhXp0mDydFAiI4GB"
      },
      "version": 1,
      "type": "BATCH"
    }
  ]
}

Link to section
GetSettlement to GetPayout

The following shows a GetSettlement request to retrieve a specific settlement identified by a settlement ID:

curl "https://connect.squareup.com/v1/{location_id}/settlements/{settlement_id}" \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'Content-Type: application/json' | jq

The following shows the GetSettlement response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

{
    "entries": [
        {
            "type": "CHARGE",
            "payment_id": "RKvVBhikT8f2foMXbkBNAxaoQuBZY",
            "amount_money": {
                "currency_code": "USD",
                "amount": 2397
            },
            "fee_money": {
                "currency_code": "USD",
                "amount": -103
            }
        },
        {
            "type": "CHARGE",
            "payment_id": "F2eGGWCJZYf4sm4C3g9ial4sepWZY",
            "amount_money": {
                "currency_code": "USD",
                "amount": 950
            },
            "fee_money": {
                "currency_code": "USD",
                "amount": -50
            }
        },
        {
            "type": "OTHER",
            "amount_money": {
                "currency_code": "USD",
                "amount": -50
            },
            "fee_money": {
                "currency_code": "USD",
                "amount": 0
            }
        }
    ],
    "id": "3Z9A5VTRCAW15S507K5DTANAC7MS",
    "status": "SENT",
    "bank_account_id": "ccof:IpqfhXp0mDydFAiI4GB",
    "initiated_at": "2022-01-26T20:08:19Z",
    "total_money": {
        "currency_code": "USD",
        "amount": 3297
    }
}

The following GetPayout example shows a request to get details of a specific payout identified by a payout ID:

curl https://connect.squareup.com/v2/payouts/{payout_id} \
  -H 'Square-Version: 2022-04-20' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'Content-Type: application/json'

The following shows the GetPayout response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

{
  "payout": {
    "id": "po_4a8bbd61-8ae0-4b92-86e9-76b487b10481",
    "status": "SENT",
    "location_id": "LCRS9JV5GZ9AZ",
    "created_at": "2022-01-26T20:08:19Z",
    "updated_at": "2022-01-26T20:08:19Z",
    "amount_money": {
      "amount": 3297,
      "currency_code": "USD"
    },
    "destination": {
      "type": "CARD",
      "id": "ccof:IpqfhXp0mDydFAiI4GB"
    },
    "version": 1,
    "type": "BATCH"
  }
}

Link to section
GetSettlement to ListPayoutEntries

The following example shows a request to get a list of all payout entries for a specific payout:

curl https://connect.squareup.com/v2/payouts/{payout_id}/payout-entries \
  -H 'Square-Version: 2022-04-20' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'Content-Type: application/json'

The following shows the ListPayoutEntries response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

{
  "payout_entries": [
    {
      "id": "poe_NX06xUOxO2g2R6toBgRnMKO8cg4",
      "payout_id": "po_4a8bbd61-8ae0-4b92-86e9-76b487b10481",
      "effective_at": "2022-01-26T22:07:46Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 1000,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 50,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 950,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "F2eGGWCJZYf4sm4C3g9ial4sepWZY"
      }
    },
    {
      "id": "poe_B7nRk9_gaymEbtIAuWuT7pYG3QA",
      "payout_id": "po_4a8bbd61-8ae0-4b92-86e9-76b487b10481",
      "effective_at": "2022-01-26T22:05:24Z",
      "type": "CHARGE",
      "gross_amount_money": {
        "amount": 2500,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 103,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": 2397,
        "currency_code": "USD"
      },
      "type_charge_details": {
        "payment_id": "RKvVBhikT8f2foMXbkBNAxaoQuBZY"
      }
    },
    {
      "id": "poe_lijK_kZgox8poahSCe_1T7S_i2c",
      "payout_id": "po_4a8bbd61-8ae0-4b92-86e9-76b487b10481",
      "effective_at": "2022-01-26T20:08:19Z",
      "type": "DEPOSIT_FEE",
      "gross_amount_money": {
        "amount": -50,
        "currency_code": "USD"
      },
      "fee_amount_money": {
        "amount": 0,
        "currency_code": "USD"
      },
      "net_amount_money": {
        "amount": -50,
        "currency_code": "USD"
      }
    }
  ]
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Migrate from the Square Settlements API Deprecated

This component is deprecated. See below for guidance about what to use instead.

On this page

Link to section
Migration overview

Link to section
Important dates

Link to section
Get help

Link to section
New features in the Payouts API

Link to section
Endpoints

Link to section
ListSettlements field mappings

Link to section
Path parameter mappings

Link to section
Query parameter mappings

Link to section
Response field mappings

Link to section
RetrieveSettlement field mappings

Link to section
Path parameter mappings

Link to section
Query parameter mappings

Link to section
Response field mappings

Link to section
Reporting of Square internal transfers

Link to section
Migrate V1 Settlements to the Payouts API

Link to section
ListSettlements to ListPayouts

Link to section
GetSettlement to GetPayout

Link to section
GetSettlement to ListPayoutEntries

On this page

Docs

Migrate from the Square Settlements API Deprecated This component is deprecated. See below for guidance about what to use instead.

On this page

Link to section Migration overview

Link to section Important dates

Link to section Get help

Link to section New features in the Payouts API

Link to section Endpoints

Link to section ListSettlements field mappings

Link to section Path parameter mappings

Link to section Query parameter mappings

Link to section Response field mappings

Link to section RetrieveSettlement field mappings

Link to section Path parameter mappings

Link to section Query parameter mappings

Link to section Response field mappings

Link to section Reporting of Square internal transfers

Link to section Migrate V1 Settlements to the Payouts API

Link to section ListSettlements to ListPayouts

Link to section GetSettlement to GetPayout

Link to section GetSettlement to ListPayoutEntries

On this page

Migrate from the Square Settlements API Deprecated

This component is deprecated. See below for guidance about what to use instead.

Link to section
Migration overview

Link to section
Important dates

Link to section
Get help

Link to section
New features in the Payouts API

Link to section
Endpoints

Link to section
ListSettlements field mappings

Link to section
Path parameter mappings

Link to section
Query parameter mappings

Link to section
Response field mappings

Link to section
RetrieveSettlement field mappings

Link to section
Path parameter mappings

Link to section
Query parameter mappings

Link to section
Response field mappings

Link to section
Reporting of Square internal transfers

Link to section
Migrate V1 Settlements to the Payouts API

Link to section
ListSettlements to ListPayouts

Link to section
GetSettlement to GetPayout

Link to section
GetSettlement to ListPayoutEntries