Error when retrieving settlements (v1)


a user of our application cannot sync his settlements when trying to get settlements by id.
The errors look like that :
{“status_code”:500,“type”:“internal_server_error”,“message”:“Error: getaddrinfo ENOTFOUND”,“request_id”:“3ZDX9V22WMBR8YSCZXBY12E3434N”}

Do you know what kind of error it is and how to resolve it ?


:wave: What’s the application ID and the location_id that’s returning this error.

application ID : bcyVPjLx7yWuN49MPEgbbw
location ID : 05Q4X3BFJPTDN

Thanks for providing the credentials. I took a look at our logs and I’m not seeing that error. That endpoint doesn’t take a request_id. What is the request that’s being sent to Square that’s returning this error?

after getting the list of settlements,
it’s a batch to retrieve the settlements by id
(FYI I tried also with the application we use for testing : app ID : K6B28yo6zeWi1SYCmg14WQ using our user’s credentials, same error)
a first POST to
with POST CONTENT the lists of GET requests like that :
“requests”: [
“method”: “GET”,
“relative_path”: “/v1/me/settlements/3ZDX9V22WMBR8YSCZXBY12E3434N”,
“access_token”: ACCESS_TOKEN,
“request_id”: “3ZDX9V22WMBR8YSCZXBY12E3434N”

Batching and v1/me are retired with Square. You should be calling the Settlements API with the settlement_id directly. :slightly_smiling_face:

Do you plan to have a doc for migrating to the new API for settlements like payments and refunds ?

Yes, we will definitely have a migration guide when the replacement comes out for Settlements API. :slightly_smiling_face:

:wave: Hi all! We’re excited to unveil the v2/payouts API in beta! This API will replace the v1/settlements API, which will be retired in 2023.You can use the Payouts API to automatically reconcile sellers’ bank deposits or debits with their payments taken with Square in production and sandbox. You can retrieve a list of payouts or individual payouts and compare their amounts with the deposit or debit amounts on the bank statement. You can also list all of the payout entries associated with a payout so you can reconcile at a transaction level in your accounting system.

To get started visit the Payouts API documentation page. Feel free to ask questions or provide feedback here! :slightly_smiling_face:


the Payouts API introduces new types for the payout entries, and some I don’t know how to manage them (expense or receipt). Can you help me with them please ? :

those I guess are receipts :

  • App fee refund
  • app fee revenue
  • automatic savings (?)
  • subscription fee refund

those I guess are expenses :

  • automatic savings reversed (?)
  • fee
  • third party fee
  • tax on fee
  • deposit fee

those I guess depends on the amount (positive or negative) :

  • other adjustment
  • reserve hold
  • release adjustment
  • reserve release

those I don’t know :

  • dispute
  • escheatment
  • subscription fee paid
  • initial balance change
  • money transfer
  • money transfer reversal
  • open dispute

Don’t hesitate to tell me if I make mistakes and what are the correct categories (expenses, receipts or both depending on the amount)

Thank you for your help

The payout types with the Payouts API are:

  • ADJUSTMENT -A manual adjustment applied to the seller’s account by Square.
  • APP_FEE_REFUND -A refund for an application fee on a payment.
  • APP_FEE_REVENUE -Revenue generated from an application fee on a payment.
  • AUTOMATIC_SAVINGS -An automatic transfer from the payment processing balance to the Square Savings account. These are, generally, proportional to the seller’s sales.
  • AUTOMATIC_SAVINGS_REVERSED -An automatic transfer from the Square Savings account back to the processing balance. These are, generally, proportional to the seller’s refunds.
  • CHARGE - A credit card payment capture.
  • DEPOSIT_FEE - Any fees involved with deposits such as instant deposits.
  • DISPUTE - The balance change due to a dispute event.
  • ESCHEATMENT - An escheatment entry for remittance.
  • FEE - The Square processing fee.
  • FREE_PROCESSING - Square offers free payments processing for a variety of business scenarios, including seller referrals or when Square wants to apologize (for example, for a bug, customer service, or repricing complication). This entry represents a credit to the seller for the purposes of free processing.
  • HOLD_ADJUSTMENT - An adjustment made by Square related to holding a payment.
  • INITIAL_BALANCE_CHANGE - An external change to a seller’s balance. Initial, in the sense that it causes the creation of the other activity types, such as hold and refund.
  • MONEY_TRANSFER - The balance change from a money transfer.
  • MONEY_TRANSFER_REVERSAL - The reversal of a money transfer.
  • OPEN_DISPUTE - The balance change for a chargeback that has been filed.
  • OTHER - Any other type that does not belong in the rest of the types.
  • OTHER_ADJUSTMENT - Any other type of adjustment that does not fall under existing types.
  • PAID_SERVICE_FEE - A fee paid to a third-party merchant.
  • PAID_SERVICE_FEE_REFUND - A fee paid to a third-party merchant.
  • REDEMPTION_CODE - Repayment for a redemption code.
  • REFUND - A refund for an existing card payment.
  • RELEASE_ADJUSTMENT - An adjustment made by Square related to releasing a payment.
  • RESERVE_HOLD - Fees paid for funding risk reserve.
  • RESERVE_RELEASE - Fees released from risk reserve.
  • RETURNED_PAYOUT - An entry created when Square receives a response for the ACH file that Square sent indicating that the settlement of the original entry failed.
  • SQUARE_CAPITAL_PAYMENT - A capital merchant cash advance (MCA) assessment. These are, generally, proportional to the merchant’s sales but can be issued for other reasons related to the MCA.
  • SQUARE_CAPITAL_REVERSED_PAYMENT - A capital merchant cash advance (MCA) assessment refund. These are, generally, proportional to the merchant’s refunds but can be issued for other reasons related to the MCA.
  • SUBSCRIPTION_FEE - A fee charged for subscription to a Square product.
  • SUBSCRIPTION_FEE_PAID_REFUND - A Square subscription fee that has been refunded.
  • SUBSCRIPTION_FEE_REFUND - The refund of a previously charged Square product subscription fee.
  • TAX_ON_FEE - The tax paid on fee amounts.
  • THIRD_PARTY_FEE - Fees collected by a third-party platform.
  • THIRD_PARTY_FEE_REFUND - Refunded fees from a third-party platform.

not really helping since I already knew that list.
But with a colleague of mine, we managed to determine if a payout entry type should be considered as an expense, a receipt or both (depending on the amount sign)

But, one is troublesome : Escheatment : we don’t know how escheatment works, so we don’t know how to treat it. Please can you provide an explanation how it works and if it should be considered an expense or a receipt ?

thank you


When you say “receipt” does that mean that you’re receiving funds vs an expense where funds would be exiting the account? :slightly_smiling_face:

yes, exactly, that’s what I mean