Manage credit notes

Learn how to manage your credit notes.

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.

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. 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-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 payable_id, document_id, issued_at, and total_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, 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.