Financial mutations

id

identifier · pattern: ^\d+$

A unique record identifier

administration_id

administration_id · pattern: ^\d+$

A unique record identifier

amount

string

code

string | null

date

string · date

message

string | null

contra_account_name

string | null

contra_account_number

string

state

string · enum

Enum values:

unprocessed

processed

Default: unprocessed

settlement_state

string · enum

Enum values:

authorised

cancelled

expired

settled

pending

refused

error

captured

Default: settled

amount_open

string

sepa_fields

object | null

batch_reference

string | null

financial_account_id

identifier · pattern: ^\d+$

A unique record identifier

currency

ISO 4217 currency code

original_amount

string | null

created_at

timestamp · date-time

updated_at

timestamp · date-time

version

financial_statement_id

identifier · pattern: ^\d+$

A unique record identifier

processed_at

string | null · date-time

account_servicer_transaction_id

string | null

POST/{administration_id}/financial_mutations/synchronization{format}

curl https://moneybird.com/api/v2/:administration_id/financial_mutations/synchronization:format \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "ids": [
    502878465407583900,
    502878465415972500
  ]
}'

Example Request Body

{
  "ids": [
    502878465407583900,
    502878465415972500
  ]
}

json

application/json

Example Responses

[
  {
    "id": "502878465415972466",
    "administration_id": 123,
    "amount": "100.0",
    "code": null,
    "date": "2026-11-04",
    "message": "Factuur",
    "contra_account_name": null,
    "contra_account_number": "",
    "state": "unprocessed",
    "settlement_state": "settled",
    "amount_open": "100.0",
    "sepa_fields": null,
    "batch_reference": null,
    "financial_account_id": "502878465388709468",
    "currency": "EUR",
    "original_amount": null,
    "created_at": "2026-11-04T14:24:58.461Z",
    "updated_at": "2026-11-04T14:24:58.461Z",
    "version": 1793802298,
    "financial_statement_id": "502878465414923889",
    "processed_at": null,
    "account_servicer_transaction_id": null,
    "payments": [],
    "ledger_account_bookings": []
  },
  {
    "id": "502878465407583849",
    "administration_id": 123,
    "amount": "100.0",
    "code": null,
    "date": "2026-11-04",
    "message": "Factuur",
    "contra_account_name": null,
    "contra_account_number": "",
    "state": "unprocessed",
    "settlement_state": "settled",
    "amount_open": "100.0",
    "sepa_fields": null,
    "batch_reference": null,
    "financial_account_id": "502878465388709468",
    "currency": "EUR",
    "original_amount": null,
    "created_at": "2026-11-04T14:24:58.454Z",
    "updated_at": "2026-11-04T14:24:58.454Z",
    "version": 1793802298,
    "financial_statement_id": "502878465407583848",
    "processed_at": null,
    "account_servicer_transaction_id": null,
    "payments": [],
    "ledger_account_bookings": []
  }
]

json

application/json

Links a financial mutation to a booking

PATCH

https://moneybird.com/api/v2

/{administration_id}/financial_mutations/{id}/link_booking{format}

Linking a booking to a financial mutation allows you to process financial mutations. Financial mutations can be linked to invoices, documents, ledger accounts and payment batches.

Depending on booking_type, the token also needs the sales_invoices scope (SalesInvoice, ExternalSalesInvoice, PaymentTransaction, PaymentTransactionBatch), the documents scope (Document, NewPurchaseInvoice, NewReceipt, PurchaseTransactionBatch), the sales_invoices, documents and settings scopes (VatDocument), or the scope of the invoice the payment belongs to (Payment). LedgerAccount needs only bank. For a PurchaseTransaction that is not paid yet, and for each such transaction in a PurchaseTransactionBatch, the token also needs the scope of the invoice the transaction pays.

Only a financial mutation with settlement_state settled, authorised or pending can be linked. Any other settlement_state answers 400.

Required scope(s)

bank

Links a financial mutation to a booking › path Parameters

administration_id

administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

id

identifier · pattern: ^\d+$ · required

A unique record identifier

format

string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Links a financial mutation to a booking › Request Body

booking_type

string · enum · required

The type of record to link the mutation to.

Enum values:

SalesInvoice

Document

LedgerAccount

PaymentTransactionBatch

PurchaseTransaction

NewPurchaseInvoice

NewReceipt

PaymentTransaction

booking_id

identifier · pattern: ^\d+$

The id of the record to link, of the type set in booking_type (e.g. the ledger account id when booking_type is LedgerAccount). Not allowed for NewPurchaseInvoice and NewReceipt — those create a new record instead of linking an existing one. To link an existing purchase invoice or receipt, use booking_type Document with the document's id.

money

The booking amount, in the administration's base currency. This is the field that carries the amount for most booking types; when linking a payment to an invoice it is the base-currency counterpart of price. For booking_type LedgerAccount send the amount here — price is ignored.

Whether to send a positive or a negative amount depends on booking_type:

`booking_type`	Amount
`SalesInvoice`, `ExternalSalesInvoice`, `Document`	Always positive. The payment direction is taken from the financial mutation, so refunds and credit notes also take a positive amount, whichever way the money moved
`LedgerAccount`	Positive books in the same direction as the mutation, negative against it. Splitting a mutation over several bookings takes one request per part: an outgoing mutation of -95 consisting of 100 in costs and 5 received back takes one request with `100` and one with `-5`. One exception: once an incoming mutation has more booked than its own amount (its open amount went negative), positive and negative swap — a positive amount then books against the mutation
`VatDocument`	The amount as it appears on the VAT return: positive when VAT is payable, negative for a refund
`NewPurchaseInvoice`, `NewReceipt`	Positive when the mutation is outgoing (a purchase you paid), negative when it is incoming (money received back)
`Payment`, `PaymentTransaction`, `PaymentTransactionBatch`, `PurchaseTransactionBatch`, `PurchaseTransaction`	Ignored — the amount comes from the record being linked

money

Amount in the booking's own currency, used when linking a payment to an invoice. The same positive/negative rules apply as for price_base (see the table there). For a foreign-currency invoice both price and price_base are required; otherwise price_base alone is enough. Only used when booking_type is SalesInvoice, ExternalSalesInvoice, Document or VatDocument; every other booking type takes its amount from price_base or ignores it.

description

string

payment_batch_identifier

string

project_id

identifier · pattern: ^\d+$

Should be a valid project id.

mark_open_sepa_transaction_as_paid

boolean | string

Links a financial mutation to a booking › Responses

The financial mutation from the request, with its payments and ledger_account_bookings. Linking to a cash-control ledger account can also book a second mutation; that mutation is not in the response.

For booking_type PaymentTransactionBatch the link is made in the background, so the response shows the mutation before the link.

id

identifier · pattern: ^\d+$

A unique record identifier

administration_id

administration_id · pattern: ^\d+$

A unique record identifier

amount

string

code

string | null

date

string · date

message

string | null

contra_account_name

string | null

contra_account_number

string

state

string · enum

Enum values:

unprocessed

processed

Default: unprocessed

settlement_state

string · enum

Enum values:

authorised

cancelled

expired

settled

pending

refused

error

captured

Default: settled

amount_open

string

sepa_fields

object | null

batch_reference

string | null

financial_account_id

identifier · pattern: ^\d+$

A unique record identifier

currency

ISO 4217 currency code

original_amount

string | null

created_at

timestamp · date-time

updated_at

timestamp · date-time

version

financial_statement_id

identifier · pattern: ^\d+$

A unique record identifier

processed_at

string | null · date-time

account_servicer_transaction_id

string | null

PATCH/{administration_id}/financial_mutations/{id}/link_booking{format}

curl https://moneybird.com/api/v2/:administration_id/financial_mutations/:id/link_booking:format \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "booking_type": "NewReceipt",
  "price_base": -100
}'

Example Request Body

{
  "booking_type": "NewReceipt",
  "price_base": -100
}

json

application/json

Example Responses

{
  "id": "502878465447429758",
  "administration_id": 123,
  "amount": "100.0",
  "code": null,
  "date": "2026-11-04",
  "message": "Factuur",
  "contra_account_name": null,
  "contra_account_number": "",
  "state": "processed",
  "settlement_state": "settled",
  "amount_open": "0.0",
  "sepa_fields": null,
  "batch_reference": null,
  "financial_account_id": "502878465439041146",
  "currency": "EUR",
  "original_amount": null,
  "created_at": "2026-11-04T14:24:58.491Z",
  "updated_at": "2026-11-04T14:24:58.520Z",
  "version": 1793802298,
  "financial_statement_id": "502878465446381181",
  "processed_at": "2026-11-04T14:24:58.519Z",
  "account_servicer_transaction_id": null,
  "payments": [
    {
      "id": "502878465470498441",
      "administration_id": 123,
      "invoice_type": "Document",
      "invoice_id": "502878465462109831",
      "financial_account_id": "502878465439041146",
      "user_id": "502878423469786213",
      "payment_transaction_id": null,
      "transaction_identifier": null,
      "price": "-100.0",
      "price_base": "-100.0",
      "payment_date": "2026-11-04",
      "credit_invoice_id": null,
      "financial_mutation_id": "502878465447429758",
      "ledger_account_id": "502878465442186875",
      "linked_payment_id": null,
      "manual_payment_action": null,
      "created_at": "2026-11-04T14:24:58.514Z",
      "updated_at": "2026-11-04T14:24:58.514Z"
    }
  ],
  "ledger_account_bookings": []
}

json

application/json

Unlinks a booking from a financial mutation

DELETE

https://moneybird.com/api/v2

/{administration_id}/financial_mutations/{id}/unlink_booking{format}

Unlinks a booking from a financial mutation.

To unlink a Payment, the token also needs the scope of the invoice the payment belongs to: sales_invoices for (external) sales invoices, documents for purchase invoices and receipts, or sales_invoices, documents and settings for VAT documents.

Required scope(s)

bank

Unlinks a booking from a financial mutation › path Parameters

administration_id

administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

id

identifier · pattern: ^\d+$ · required

A unique record identifier

format

string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Unlinks a booking from a financial mutation › Request Body

booking_type

string · enum · required

Can be Payment or LedgerAccountBooking.

Enum values:

Payment

LedgerAccountBooking

booking_id

identifier · pattern: ^\d+$ · required

A unique record identifier

Unlinks a booking from a financial mutation › Responses

A financial mutation

id

identifier · pattern: ^\d+$

A unique record identifier

administration_id

administration_id · pattern: ^\d+$

A unique record identifier

amount

string

code

string | null

date

string · date

message

string | null

contra_account_name

string | null

contra_account_number

string

state

string · enum

Enum values:

unprocessed

processed

Default: unprocessed

settlement_state

string · enum

Enum values:

authorised

cancelled

expired

settled

pending

refused

error

captured

Default: settled

amount_open

string

sepa_fields

object | null

batch_reference

string | null

financial_account_id

identifier · pattern: ^\d+$

A unique record identifier

currency

ISO 4217 currency code

original_amount

string | null

created_at

timestamp · date-time

updated_at

timestamp · date-time

version

financial_statement_id

identifier · pattern: ^\d+$

A unique record identifier

processed_at

string | null · date-time

account_servicer_transaction_id

string | null

DELETE/{administration_id}/financial_mutations/{id}/unlink_booking{format}

curl https://moneybird.com/api/v2/:administration_id/financial_mutations/:id/unlink_booking:format \
  --request DELETE \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "booking_type": "Payment",
  "booking_id": 502878466762343550
}'

Example Request Body

{
  "booking_type": "Payment",
  "booking_id": 502878466762343550
}

json

application/json

Example Responses

{
  "id": "502878466683700336",
  "administration_id": 123,
  "amount": "100.0",
  "code": null,
  "date": "2026-11-04",
  "message": "Factuur",
  "contra_account_name": null,
  "contra_account_number": "",
  "state": "unprocessed",
  "settlement_state": "settled",
  "amount_open": "100.0",
  "sepa_fields": null,
  "batch_reference": null,
  "financial_account_id": "502878466675311724",
  "currency": "EUR",
  "original_amount": null,
  "created_at": "2026-11-04T14:24:59.670Z",
  "updated_at": "2026-11-04T14:24:59.774Z",
  "version": 1793802299,
  "financial_statement_id": "502878466682651759",
  "processed_at": null,
  "account_servicer_transaction_id": null,
  "payments": [],
  "ledger_account_bookings": []
}

json

application/json

Get a financial mutation by id

GET

https://moneybird.com/api/v2

/{administration_id}/financial_mutations/{id}{format}

Returns a single financial mutation in the administration.

Required scope(s)

bank

Get a financial mutation by id › path Parameters

administration_id

administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

id

identifier · pattern: ^\d+$ · required

A unique record identifier

format

string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

Get a financial mutation by id › Responses

A financial mutation

id

identifier · pattern: ^\d+$

A unique record identifier

administration_id

administration_id · pattern: ^\d+$

A unique record identifier

amount

string

code

string | null

date

string · date

message

string | null

contra_account_name

string | null

contra_account_number

string

state

string · enum

Enum values:

unprocessed

processed

Default: unprocessed

settlement_state

string · enum

Enum values:

authorised

cancelled

expired

settled

pending

refused

error

captured

Default: settled

amount_open

string

sepa_fields

object | null

batch_reference

string | null

financial_account_id

identifier · pattern: ^\d+$

A unique record identifier

currency

ISO 4217 currency code

original_amount

string | null

created_at

timestamp · date-time

updated_at

timestamp · date-time

version

financial_statement_id

identifier · pattern: ^\d+$

A unique record identifier

processed_at

string | null · date-time

account_servicer_transaction_id

string | null

financial_mutation_response[]

GET/{administration_id}/financial_mutations/{id}{format}

curl https://moneybird.com/api/v2/:administration_id/financial_mutations/:id:format \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "id": "502878465239811628",
  "administration_id": 123,
  "amount": "100.0",
  "code": null,
  "date": "2026-11-04",
  "message": "Factuur",
  "contra_account_name": null,
  "contra_account_number": "",
  "state": "unprocessed",
  "settlement_state": "settled",
  "amount_open": "100.0",
  "sepa_fields": null,
  "batch_reference": null,
  "financial_account_id": "502878465226180136",
  "currency": "EUR",
  "original_amount": null,
  "created_at": "2026-11-04T14:24:58.294Z",
  "updated_at": "2026-11-04T14:24:58.294Z",
  "version": 1793802298,
  "financial_statement_id": "502878465239811627",
  "processed_at": null,
  "account_servicer_transaction_id": null,
  "payments": [
    {
      "id": "502878465290143293",
      "administration_id": 123,
      "invoice_type": "SalesInvoice",
      "invoice_id": "502878465277560377",
      "financial_account_id": "502878465226180136",
      "user_id": 1,
      "payment_transaction_id": null,
      "transaction_identifier": null,
      "price": "80.0",
      "price_base": "80.0",
      "payment_date": "2026-11-04",
      "credit_invoice_id": null,
      "financial_mutation_id": "502878465239811628",
      "ledger_account_id": "502878465289094716",
      "linked_payment_id": null,
      "manual_payment_action": null,
      "created_at": "2026-11-04T14:24:58.341Z",
      "updated_at": "2026-11-04T14:24:58.341Z"
    }
  ],
  "ledger_account_bookings": [
    {
      "id": "502878465262880309",
      "administration_id": 123,
      "financial_mutation_id": "502878465239811628",
      "ledger_account_id": "502878465261831732",
      "project_id": null,
      "description": "Ledger account booking",
      "price": "20.0",
      "created_at": "2026-11-04T14:24:58.316Z",
      "updated_at": "2026-11-04T14:24:58.316Z"
    }
  ]
}

json

application/json

List all financial mutations

GET

https://moneybird.com/api/v2

/{administration_id}/financial_mutations{format}

Returns the financial mutations that match the filter. When more than 100 financial mutations match, the request fails with a 400 response. Use a smaller period or the synchronize API to get more.

Required scope(s)

bank

List all financial mutations › path Parameters

administration_id

administration_id · pattern: ^\d+$ · required

The unique identifier of the administration

A unique record identifier

format

string · pattern: ^(.(json|xml))?$ · required

The format in which the response is given, can be empty to use the default format

Default: .json

List all financial mutations › query Parameters

filter

string

Filters are key:value terms separated by commas (e.g. period:this_year,state:unprocessed). Any filter you pass replaces the defaults below entirely, so include every key you need. Available filters:

Filter	Type	Default	Description
period	`String`	`this_year`	A named period (`this_week`, `prev_week`, `next_week`, `this_month`, `prev_month`, `next_month`, `this_quarter`, `prev_quarter`, `next_quarter`, `this_year`, `prev_year`, `next_year`) or a custom range (`201301..201302`, `20130101..20130131`). A custom period must have a start and an end date. It must not be longer than 10 years and must be between `20000101` and `21000101`. For one month, use `202401..202401`, not `202401`. Without `period`, the filter does not limit the dates. The default `this_year` applies only when you send no `filter`.
state	`String`	`all`	`all`, `unprocessed`, `processed` or `auto_booked`
mutation_type	`String`	`all`	`all`, `debit` or `credit`
financial_account_id	`Integer`		Restrict to a single financial account
amount_from	`String`		Lower bound on the absolute mutation amount (negative input is treated as positive)
amount_to	`String`		Upper bound on the absolute mutation amount

Multiple values for state and mutation_type can be combined with a pipe, e.g. state:unprocessed|processed.

Default: period:this_year

List all financial mutations › Responses

A list of financial mutations

id

identifier · pattern: ^\d+$

A unique record identifier

administration_id

administration_id · pattern: ^\d+$

A unique record identifier

amount

string

code

string | null

date

string · date

message

string | null

contra_account_name

string | null

contra_account_number

string

state

string · enum

Enum values:

unprocessed

processed

Default: unprocessed

settlement_state

string · enum

Enum values:

authorised

cancelled

expired

settled

pending

refused

error

captured

Default: settled

amount_open

string

sepa_fields

object | null

batch_reference

string | null

financial_account_id

identifier · pattern: ^\d+$

A unique record identifier

currency

ISO 4217 currency code

original_amount

string | null

created_at

timestamp · date-time

updated_at

timestamp · date-time

version

financial_statement_id

identifier · pattern: ^\d+$

A unique record identifier

processed_at

string | null · date-time

account_servicer_transaction_id

string | null