MOmollie
Settlements API

Get settlement

Changed on

Retrieve a single settlement by its ID.

To lookup settlements by their bank reference, replace the ID in the URL by a reference. For example: 1234567.2404.03.

A settlement represents a transfer of your balance funds to your external bank account.

Settlements will typically include a report that details what balance transactions have taken place between this settlement and the previous one.

For more accurate bookkeeping, refer to the balance report endpoint or the balance transactions endpoint.

get/v2/settlements/{settlementId}

Request

  • Base URL
    https://api.mollie.com
  • URL
    https://api.mollie.com/v2/settlements/{settlementId}
  • Auth
    • HTTP bearer
    • or OAuth 2
      Authorization code: https://my.mollie.com/oauth2/authorize
      Token URL: https://api.mollie.com/oauth2/tokens scopes: settlements.read

Headers

idempotency-keystring
Example:123e4567-e89b-12d3-a456-426

A unique key to ensure idempotent requests. This key should be a UUID v4 string.

Response

The settlement object.

resourcestring required

Indicates the response contains a settlement object. Will always contain the string settlement for this endpoint.

idstring required
createdAtstring

The entity's date and time of creation, in ISO 8601 format.

referencestring nullable

The settlement's bank reference, as found in your Mollie account and on your bank statement.

settledAtstring nullable

The date on which the settlement was settled, in ISO 8601 format.

For an open settlement or for the next settlement, no settlement date is available.

status'open' | 'pending' | 'processing' | 'processing-at-bank' | 'paidout' | 'failed' required

The status of the settlement.

balanceIdstring required
invoiceIdstring
periodsobject

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.

Example response

{
  "resource": "settlement",
  "id": "stl_5B8cwPMGnU",
  "createdAt": "2024-03-20T09:13:37+00:00",
  "reference": "07049691.2406.01",
  "settledAt": "2025-03-31T12:54:39+00:00",
  "status": "paidout",
  "amount": {
    "currency": "EUR",
    "value": "10.00"
  },
  "balanceId": "bal_gVMhHKqSSRYJyPsuoPNFH",
  "invoiceId": "inv_aHbjjdrUdm",
  "_links": {
    "self": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "payments": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "captures": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "refunds": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "chargebacks": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "invoice": {
      "href": "https://...",
      "type": "application/hal+json"
    },
    "documentation": {
      "href": "https://...",
      "type": "application/hal+json"
    }
  }
}

Changes

  • 7eb5bf6b29ddRevision changes
    • warning

      added the new processing enum value to the //////// response property for the response status

  • 66dee9998c09Revision changes
    • warning

      added the new wero enum value to the ///////// response property for the response status

    • warning

      added the new wero enum value to the ///////// response property for the response status