Manage credit notes

Learn how to manage your credit notes.

Roles and permissions

To create and manage credit notes using an entity user token, this entity user must have a role with the payables permission.

If a partner-level token is used, no special permissions are needed.

Change credit note status

You can manually change the status of the credit notes and move them through the lifecycle until their application. See the credit notes lifecycle for more information.

Alternatively, we recommend that you implement approval policies to manage the credit notes transitions.

Create a credit note

To create a new credit note, call POST /payable_credit_notes. You can provide the base64-encoded contents of the original invoice file in the field base64_encoded_file:

1curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes' \
2  -H 'accept: application/json' \
3  -H 'X-Monite-Version: 2024-01-31' \
4  -H 'X-Monite-Entity-Id: ENTITY_ID' \
5  -d '{
6    "based_on": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
7    "based_on_document_id": "DE12312",
8    "counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
9    "counterpart_address_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
10    "counterpart_bank_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
11    "counterpart_vat_id_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
12    "base64_encoded_file": "string",
13    "file_name": "invoice.pdf",
14    "document_id": "DE2287",
15    "description": "string",
16    "due_date": "2024-10-29",
17    "issued_at": "2024-10-29",
18    "currency": "EUR",
19    "subtotal": 1250,
20    "tax": 2000,
21    "tax_amount": 250,
22    "total_amount": 15000,
23    "discount": 500,
24    "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
25    "tag_ids": [
26      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
27    ]
28  }'
Requirements and considerations
  • The fields payable_id, document_id, issued_at, and amount are mandatory.
  • The issued_at field cannot be a future date.
  • The issued_at must be after or equal to the payables’s issued_at.
  • All the amount fields in the credit notes and line items must be greater than 0.
  • A credit note cannot be linked to a canceled payable.

List all credit notes

To list all credit notes, call GET /payable_credit_notes. You can sort and filter the results by the amount, status, and other fields. For the full list of available sort and filter parameters, see the GET /payable_credit_notes endpoint:

1curl -X GET 'https://api.sandbox.monite.com/v1/payable_credit_notes' \
2     -H 'X-Monite-Version: 2024-01-31' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

The data array in the response contains a list of related credit notes, if any:

1{
2  "data": [
3    {
4      "type": "credit_note",
5      "id": "9c9f4b57-009e-43ef-a784-d0d8ceab2bf2",
6      ...
7    }
8  ],
9  "prev_pagination_token": null,
10  "next_pagination_token": null
11}

Find all credit notes of a payable

To check if there are credit notes linked to a specific payable, call GET /payable_credit_notes?based_on={payable_id}:

1curl -X GET 'https://api.sandbox.monite.com/v1/payable_credit_notes?based_on={payable_id}' \
2     -H 'X-Monite-Version: 2024-01-31' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

Update a credit note

Credit notes in the draft and new statuses can be updated, for example, to provide additional details or fix the information extracted by OCR. To update a credit note, call PATCH /payable_credit_notes/{payable_credit_notes_id} with the request body containing the new field values. For example, to update the description field:

1curl -X PATCH 'https://api.sandbox.monite.com/v1/payable_credit_notes/{payable_credit_notes_id}' \
2     -H 'X-Monite-Version: 2024-01-31' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN' \
5     -H 'Content-Type: application/json' \
6     -d '{
7       "description": "New description of the payable"
8     }'

Delete a credit note

Credit notes in any status can be deleted by calling the DELETE /payable_credit_notes/{payable_credit_notes_id} endpoint:

1curl -X DELETE 'https://api.sandbox.monite.com/v1/payable_credit_notes/{payable_credit_notes_id}' \
2     -H 'X-Monite-Version: 2024-01-31' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

This action is irreversible, and once deleted, credit notes can no longer be accessed.