Manage credit notes (accounts payable)

Learn how to manage your credit notes.

This guide covers credit notes in accounts payable. Monite also supports credit notes for accounts receivable.

Overview

There are two ways to create a credit note:

When a credit note is created from a PDF, PNG, or JPEG file, Monite’s OCR service automatically extracts the credit note information from the file and a new credit note is created with the extracted data fields accordingly. The file property of the credit note contains the file metadata and the link to access the original source file.

You can configure Monite to automatically link credit notes which have a payable reference to the appropriate payable during the credit note creation based on the following criteria:

  • The field based_on_document_id of the credit note must be equal to the document_id of the payable.
  • The payable needs to be under waiting_to_be_paid, partially_paid, or paid statuses.
  • The payable must not be linked to any other credit note.
  • Both credit note and payable must have the same value for the counterpart_id field.

If the credit note field based_on_document_id corresponds to multiple payables with the same document_id and counterpart_id, the credit note is created but not auto-linked to any payable.

To enable this feature, send a PATCH request to the /settings endpoint, setting the payable.allow_credit_note_autolinking field to true:

1curl -X PATCH 'https://api.sandbox.monite.com/v1/settings' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5     -d '{
6        "payable": {
7          "allow_credit_note_autolinking": true
8        }
9      }'

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.

Create a credit note from data

To create a new credit note, call POST /payable_credit_notes:

1curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes' \
2  -H 'accept: application/json' \
3  -H 'X-Monite-Version: 2024-05-25' \
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 document_id, issued_at, and total_amount are mandatory.
  • The issued_at field cannot be a future date.
  • All the amount fields in the credit notes and line items must be greater than 0, except the total_amount field, which is optional.
  • A credit note cannot be linked to a canceled payable.

Upload files via API

You can upload credit notes in the PDF, PNG, or JPG format to Monite by calling POST /payable_credit_notes/upload_from_file. The maximum file size is 10 MB:

1curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/upload_from_file' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN' \
5     -H 'Content-Type: multipart/form-data' \
6     -F 'file=@pdf-invoice.pdf;type=application/pdf'

The successful response contains the credit note ID and other fields:

1{
2  "id": "123e4567-e89b-12d3-a456-426614174000",
3  "created_at": "2024-01-15T14:30:00Z",
4  "updated_at": "2024-01-15T14:30:00Z",
5  "based_on": "123e4567-e89b-12d3-a456-426614174000",
6  "based_on_document_id": "INV-2287",
7  "counterpart_address_id": "123e4567-e89b-12d3-a456-426614174000",
8  "counterpart_bank_account_id": "123e4567-e89b-12d3-a456-426614174000",
9  "counterpart_id": "123e4567-e89b-12d3-a456-426614174000",
10  "counterpart_vat_id_id": "123e4567-e89b-12d3-a456-426614174000",
11  "created_by_external_user_id": "ext_user_123",
12  "created_by_external_user_name": "John Doe",
13  "created_by_user_id": "123e4567-e89b-12d3-a456-426614174000",
14  "currency": "EUR",
15  "currency_exchange": {
16    "default_currency_code": "string",
17    "rate": 0,
18    "total": 0
19  },
20  "description": "Credit note for returned items from invoice INV-2287",
21  "document_id": "CN-2287",
22  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
23  "file_id": "123e4567-e89b-12d3-a456-426614174000",
24  "file_url": "string",
25  "issued_at": "2024-01-15",
26  "ocr_request_id": "123e4567-e89b-12d3-a456-426614174000",
27  "ocr_status": "processing",
28  "origin": "SAP",
29  "project_id": "123e4567-e89b-12d3-a456-426614174000",
30  "sender": "supplier@example.com",
31  "source_of_data": "user_specified",
32  "status": "submitted_for_approval",
33  "subtotal": 1000,
34  "tags": [
35    {
36      "id": "123e4567-e89b-12d3-a456-426614174000",
37      "name": "Department A",
38      "category": "department"
39    }
40  ],
41  "tax": 20,
42  "tax_amount": 200,
43  "total_amount": 1200
44}

You will also receive a webhook indicating that this credit note resource has been created:

1{
2  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
3  "created_at": "2024-03-04T20:06:48.593225+00:00",
4  "action": "credit_note.created_from_file_upload",
5  "api_version": "2024-05-25",
6  "entity_id": "en-your0000-enti-ty00-1D3799b65bcf",
7  "description": "Action has been performed on the credit note: created_from_file_upload.",
8  "object": {
9    "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0"
10  },
11  "object_type": "credit_note",
12  "webhook_subscription_id": "c7f37127-44e5-494a-833a-21e60585f187"
13}

Note that at this stage the credit note resource is incomplete and waiting for the results of the OCR service, which automatically scans the details from the uploaded credit note and maps the information from the credit note to the corresponding data field in the system. Its status is set as processing.

To cancel the OCR process, call POST /payable_credit_notes/{id}/cancel_ocr. The credit note status will be changed to canceled.

When the OCR scanning is finished (this might take up to 5-7 minutes), you will receive the credit_note.ocr_finished webhook event.

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.

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-05-25' \
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-05-25' \
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-05-25' \
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-05-25' \
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.