---
updatedAt: 2025-09-22T17:22:53.000Z
agentTools:
  projectIndex: https://developer.bitpay.com/llms.txt
---

# Retrieve Settlements

Facades: `merchant`

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "test",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://test.bitpay.com"
    }
  ],
  "security": [
    {}
  ],
  "paths": {
    "/settlements": {
      "get": {
        "summary": "Retrieve Settlements",
        "description": "Facades: `merchant`",
        "operationId": "retrieve-settlements",
        "parameters": [
          {
            "name": "Content-Type",
            "in": "header",
            "description": "Must be set to `application/json` for requests to the BitPay API",
            "required": true,
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          },
          {
            "name": "X-Accept-Version",
            "in": "header",
            "description": "Must be set to `2.0.0` for requests to the BitPay API",
            "required": true,
            "schema": {
              "type": "string",
              "default": "2.0.0"
            }
          },
          {
            "name": "X-Identity",
            "in": "header",
            "description": "The hexadecimal public key generated from the client private key. This header is optional for this endpoint when using the public facade, and required when using a `merchant` facade token.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Signature",
            "in": "header",
            "description": "The ECDSA signature of the full request URL concatenated with the request body, signed with your private key. This header is optional for this endpoint when using the public facade, and required when using a `merchant` facade token.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "description": "When fetching settlememts, pass a merchant facade token as a URL parameter.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dateStart",
            "in": "query",
            "description": "The start of the date window to query for settlements. Format YYYY-MM-DD",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dateEnd",
            "in": "query",
            "description": "The end of the date window to query for settlements. Format YYYY-MM-DD",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "The settlement status you want to query on",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "description": "The settlement currency you want to query on",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum results that the query will return (useful for paging results)",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of results to offset (ex. skip 10 will give you results starting with the 11th result)",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"facade\": \"merchant/settlement\",\n  \"data\": [\n    {\n      \"id\": \"KBkdURgmE3Lsy9VTnavZHX\",\n      \"accountId\": \"YJCgTf3jrXHkUVzLQ7y4eg\",\n      \"status\": \"processing\",\n      \"currency\": \"EUR\",\n      \"payoutInfo\": {\n        \"label\": \"Corporate account\",\n        \"bankCountry\": \"Netherlands\",\n        \"name\": \"Test Organization\",\n        \"bank\": \"Test\",\n        \"swift\": \"RABONL2U\",\n        \"account\": \"NL85ABNA0000000000\"\n      },\n      \"dateCreated\": \"2021-05-10T09:05:00.176Z\",\n      \"dateExecuted\": \"2021-05-10T11:52:29.681Z\",\n      \"openingDate\": \"2021-05-09T09:00:00.000Z\",\n      \"closingDate\": \"2021-05-10T09:00:00.000Z\",\n      \"openingBalance\": 1.27,\n      \"ledgerEntriesSum\": 20.82,\n      \"withholdings\": [],\n      \"withholdingsSum\": 0,\n      \"totalAmount\": 22.09,\n      \"token\": \"2gBtViSiBWSEJGo1LfaMFHoaBRzE2jek2VitKAYeenj2SRiTVSCgRvs1WTN8w4w8Lc\"\n    },\n    {\n      \"id\": \"RPWTabW8urd3xWv2To989v\",\n      \"accountId\": \"YJCgTf3jrXHkUVzLQ7y4eg\",\n      \"status\": \"processing\",\n      \"currency\": \"EUR\",\n      \"payoutInfo\": {\n        \"label\": \"Corporate account\",\n        \"bankCountry\": \"Netherlands\",\n        \"name\": \"Test Organization\",\n        \"bank\": \"Test\",\n        \"swift\": \"RABONL2U\",\n        \"account\": \"NL85ABNA0000000000\"\n      },\n      \"dateCreated\": \"2021-05-11T09:05:00.176Z\",\n      \"dateExecuted\": \"2021-05-11T11:52:29.681Z\",\n      \"openingDate\": \"2021-05-10T09:00:00.000Z\",\n      \"closingDate\": \"2021-05-11T09:00:00.000Z\",\n      \"openingBalance\": 23.27,\n      \"ledgerEntriesSum\": 20.82,\n      \"withholdings\": [\n        {\n          \"amount\": 8.21,\n          \"code\": \"W005\",\n          \"description\": \"Pending Refunds\"\n        }\n      ],\n      \"withholdingsSum\": 8.21,\n      \"totalAmount\": 35.88,\n      \"token\": \"2gBtViSiBWSEJitKAYSCgRvs1WTN8w4Go1Leenj2SRiTVFHoaBRzE2jek2VfaMw8Lc\"\n    }\n  ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "facade": {
                      "type": "string",
                      "example": "merchant/settlement"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "example": "KBkdURgmE3Lsy9VTnavZHX"
                          },
                          "accountId": {
                            "type": "string",
                            "example": "YJCgTf3jrXHkUVzLQ7y4eg"
                          },
                          "status": {
                            "type": "string",
                            "example": "processing"
                          },
                          "currency": {
                            "type": "string",
                            "example": "EUR"
                          },
                          "payoutInfo": {
                            "type": "object",
                            "properties": {
                              "label": {
                                "type": "string",
                                "example": "Corporate account"
                              },
                              "bankCountry": {
                                "type": "string",
                                "example": "Netherlands"
                              },
                              "name": {
                                "type": "string",
                                "example": "Test Organization"
                              },
                              "bank": {
                                "type": "string",
                                "example": "Test"
                              },
                              "swift": {
                                "type": "string",
                                "example": "RABONL2U"
                              },
                              "account": {
                                "type": "string",
                                "example": "NL85ABNA0000000000"
                              }
                            }
                          },
                          "dateCreated": {
                            "type": "string",
                            "example": "2021-05-10T09:05:00.176Z"
                          },
                          "dateExecuted": {
                            "type": "string",
                            "example": "2021-05-10T11:52:29.681Z"
                          },
                          "openingDate": {
                            "type": "string",
                            "example": "2021-05-09T09:00:00.000Z"
                          },
                          "closingDate": {
                            "type": "string",
                            "example": "2021-05-10T09:00:00.000Z"
                          },
                          "openingBalance": {
                            "type": "number",
                            "example": 1.27,
                            "default": 0
                          },
                          "ledgerEntriesSum": {
                            "type": "number",
                            "example": 20.82,
                            "default": 0
                          },
                          "withholdings": {
                            "type": "array"
                          },
                          "withholdingsSum": {
                            "type": "integer",
                            "example": 0,
                            "default": 0
                          },
                          "totalAmount": {
                            "type": "number",
                            "example": 22.09,
                            "default": 0
                          },
                          "token": {
                            "type": "string",
                            "example": "2gBtViSiBWSEJGo1LfaMFHoaBRzE2jek2VitKAYeenj2SRiTVSCgRvs1WTN8w4w8Lc"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```