MOmollie
Settlements API

Get next settlement

Changed on

Retrieve the details of the current settlement, that has not yet been paid out.

For a complete reference of the settlement object, refer to the Get settlement endpoint documentation.

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

get/v2/settlements/next

Request

  • Base URL
    https://api.mollie.com
  • URL
    https://api.mollie.com/v2/settlements/next
  • 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 next settlement object. For a complete reference of the settlement object, refer to the Get settlement endpoint documentation.

resourcestring required

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

id'next' required

The identifier uniquely referring to this settlement.

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": "next",
  "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"
    },
    "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