Learn how to migrate from using the deprecated V1 Settlements API to using the Square Payouts API.
Settlements V1 Migration

Migrate from the Square Settlements API

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.

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 Slack, 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 does not 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 are not 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
ListSettlementsListPayouts
RetrieveSettlementGetPayout 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 parameterListPayouts path parameterNotes
location_idN/Alocation_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 parameterListPayouts query parameterNotes
ordersort_order
begin_timebegin_timeNo longer requires ISO 8601 format for the date time. Now requires RFC 3339 format.
end_timeend_timeNo longer requires ISO 8601 format for the date time. Now requires RFC 3339 format.
limitlimit
statusstatusNew status type: PAID indicates that the payout has successfully completed.
batch_tokencursor
N/Alocation_idThe ID of the location associated with the payout.

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
itemspayoutsThe requested list of payouts. For more information, see Payouts.
bank_account_iddestinationBanking destinations include bank accounts, Square checking accounts, or debit cards. For more information, see Destination.
entriesN/AA new ListPayoutEntries endpoint retrieves a list of all payout entries for a specific payout.
initiated_atcreated_atThe timestamp of when the payout was created and submitted for deposit to the seller's banking destination, in RFC 3339 format.
statusstatusNew status type: PAID indicates that the payout has succeeded.
total_moneyamount_moneyThe amount of money involved in the payout.
N/Alocation_idThe ID of the location associated with the payout.
N/Aarrival_dateThe calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout is due to arrive in the seller’s banking destination.
N/Apayout_feeA list of processing fees and any taxes on the fees assessed by Square for this payout.
N/AtypeIndicates whether the payout is a BATCH or SIMPLE type.
N/Aupdated_atThe timestamp of when the payout was last updated, in RFC 3339 format.
N/AversionThe 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 parametersGetPayout and ListPayoutEntries path parameters
location_idN/A
settlement_idpayout_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 parametersListPayoutEntries query parameters
N/Asort_order
N/Acursor
N/Alimit

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/ApayoutThe requested payout.
N/Alocation_idThe ID of the location associated with the payout.
statusstatusNew status type: PAID indicates that the payout has succeeded.
total_moneyamount_moneyThe amount of money involved in the payout.
initiated_atcreated_atThe timestamp of when the payout was created and submitted for deposit to the seller's banking destination, in RFC 3339 format.
bank_account_iddestinationBanking destinations include bank accounts, Square checking accounts, or debit cards. For more information, see Destination.
entriesN/AA new ListPayoutEntries endpoint retrieves a list of all payout entries for a specific payout.
N/Aarrival_dateThe calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout is due to arrive in the seller’s banking destination.
N/Apayout_feeA list of processing fees and any taxes on the fees assessed by Square for this payout.
N/AtypeIndicates whether the payout is a BATCH or SIMPLE type.
N/Aupdated_atThe timestamp of when the payout was last updated, in RFC 3339 format.
N/AversionThe 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_moneynet_amount_moneyThe net proceeds from this transaction after any fees.
fee_moneyfee_amount_moneyThe amount of Square fees associated with this payout entry.
N/Agross_amount_moneyThe amount of money involved in this payout entry.
N/Apayout_idThe ID of the payout entry associated payout.
N/Aeffective_atThe timestamp of when the payout entry affected the balance, in RFC 3339 format.
N/Atype_{entry type}_detailsThe 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:

  • 1
  • 2
  • 3
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:

  • 1
  • 2
  • 3
  • 4
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:

  • 1
  • 2
  • 3
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:

  • 1
  • 2
  • 3
  • 4
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:

  • 1
  • 2
  • 3
  • 4
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.

On this page