---
title: "List settlements"
method: GET
path: "/settlements"
tags: ["Settlements API"]
---

# List settlements

`GET /settlements`

## Request

- Base URL: `https://api.mollie.com/v2`
- URL: `https://api.mollie.com/v2/settlements`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://my.mollie.com/oauth2/authorize`
    - Token URL: `https://api.mollie.com/oauth2/tokens` scopes: `settlements.read`

Retrieve a list of all your settlements.

The results are paginated.

> 🔑 Access with
>
> [Advanced access token with **settlements.read**](/reference/authentication)
>
> [OAuth access with **settlements.read**](/reference/authentication)

## Query parameters

- `from` string
- `limit` integer, nullable
- `balanceId` string, nullable
- `year` string, nullable
- `month` string, nullable
- `currencies` string, nullable

## Response `200`

A list of settlement objects. For a complete reference of the settlement object, refer to the [Get settlement endpoint](get-settlement) documentation.

- object
  - `count` integer, required: The number of items in this result set. If more items are available, a `_links.next` URL will be present in the result as well. The maximum number of items per result set is controlled by the `limit` property provided in the request. The default limit is 50 items.
  - `_embedded` object, required
    - `settlements` object[], required: An array of settlement objects. For a complete reference of the settlement object, refer to the [Get settlement endpoint](get-settlement) documentation.
      - `resource` string, required: Indicates the response contains a settlement object. Will always contain the string `settlement` for this endpoint.
      - `id` string, required: The identifier uniquely referring to this settlement.
      - `createdAt` string: The entity's date and time of creation, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      - `reference` string, nullable: The settlement's bank reference, as found in your Mollie account and on your bank statement.
      - `settledAt` string, nullable: The date on which the settlement was settled, in ISO 8601 format. For an [open settlement](get-open-settlement) or for the [next settlement](get-next-settlement), no settlement date is available.
      - `status` string, required: The status of the settlement. Possible values: `open` `pending` `processing` `processing-at-bank` `paidout` `failed`
      - `amount` object, required: The total amount of the settlement.
        - `currency` string, required: A three-character ISO 4217 currency code.
        - `value` string, required: A string containing an exact monetary amount in the given currency.
      - `balanceId` string, required: The balance token that the settlement was settled to.
      - `invoiceId` string, nullable: The ID of the oldest invoice created for all the periods, if the invoice has been created yet.
      - `periods` object: For bookkeeping purposes, the settlement includes an overview of transactions included in the settlement. These transactions are grouped into 'period' objects — one for each calendar month. For example, if a settlement includes funds from 15 April until 4 May, it will include two period objects. One for all transactions processed between 15 April and 30 April, and one for all transactions between 1 May and 4 May. Period objects are grouped by year, and then by month. So in the above example, the full `periods` collection will look as follows: `{"2024": {"04": {...}, "05": {...}}}`. The year and month in this documentation are referred as `<year>` and `<month>`. The example response should give a good idea of what this looks like in practise.
        - `<year>` object
          - `<month>` object
            - `costs` object[]: An array of cost objects, describing the fees withheld for each payment method during this period.
              - …
            - `revenue` object[]: An array of revenue objects containing the total revenue for each payment method during this period.
              - …
            - `invoiceId` string, nullable: The ID of the invoice created for this period, if the invoice has been created already.
            - `invoiceReference` string, nullable: The invoice reference, if the invoice has been created already.
      - `_links` object, required: An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.
        - `self` object, required: In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
          - `href` string, required: The actual URL string.
          - `type` string, required: The content type of the page or endpoint the URL points to.
        - `payments` object: The API resource URL of the [payments](list-payments) included in this settlement.
          - `href` string, required: The actual URL string.
          - `type` string, required: The content type of the page or endpoint the URL points to.
        - `captures` object: The API resource URL of the [captures](list-captures) included in this settlement.
          - `href` string, required: The actual URL string.
          - `type` string, required: The content type of the page or endpoint the URL points to.
        - `refunds` object: The API resource URL of the [refunds](list-refunds) deducted from this settlement.
          - `href` string, required: The actual URL string.
          - `type` string, required: The content type of the page or endpoint the URL points to.
        - `chargebacks` object: The API resource URL of the [chargebacks](list-chargebacks) deducted from this settlement.
          - `href` string, required: The actual URL string.
          - `type` string, required: The content type of the page or endpoint the URL points to.
        - `invoice` object, nullable: The API resource URL of the [invoice](list-invoices).
          - `href` string: The actual URL string.
          - `type` string: The content type of the page or endpoint the URL points to.
  - `_links` object, required: Links to help navigate through the lists of items. Every URL object will contain an `href` and a `type` field.
    - `self` object, required: The URL to the current set of items.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.
    - `previous` object, nullable, required: The previous set of items, if available.
      - `href` string: The actual URL string.
      - `type` string: The content type of the page or endpoint the URL points to.
    - `next` object, nullable, required: The next set of items, if available.
      - `href` string: The actual URL string.
      - `type` string: The content type of the page or endpoint the URL points to.
    - `documentation` object, required: In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.

## Other responses

- `400`: The request contains issues. For example, if the specified `from` value is not a valid ID.
- `404`: No entity with this ID exists.
- `429`: Rate Limit has been reached.

---

[API](https://skmtc.dev/mollie/apis/business-operations.md) - [All operations](https://skmtc.dev/mollie/apis/business-operations/llms.txt) - [OpenAPI document](https://skmtc.dev/mollie/apis/business-operations/revisions/d51d76f4e5d9?raw)