Credit notes

Overview

A credit note is a document typically issued when there is a discrepancy between the invoice and the goods received. This may occur when a product is faulty, damaged, or not as described, or when there is an overpayment by the buyer.

📘
Credit notes can be created for invoices that include discounts only if the value of the discount equals to the full value of the invoice.

Credit note lifecycle

Credit notes move through different statuses during their lifecycle:

Draft

This is the initial status for all new credit notes. A draft credit note is not issued yet and can be edited anytime.

Draft credit notes can transition to issued or deleted.

📘
There can be only one draft credit note per invoice. Before you can create the second draft credit note for the same invoice, you'll need to issue (or cancel) the previous credit note.

Issued

Indicates that the credit note has been finalized and issued to a counterpart.

Create a credit note

You can create credit notes for invoices in the issued state. Calling POST /receivables and specify the invoice ID in the based_on field in the request body:

curl -X POST 'https://api.sandbox.monite.com/v1/receivables' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
	   -H 'Authorization: Bearer ACCESS_TOKEN' \
	   -H 'Content-Type: application/json' \
	   -d '{
	     "type": "credit_note",
	     "based_on": "{invoice_id}"
	   }'

The successful response contains the information about the created credit note:

{
    "id": "9c9f4b57-009e-43ef-a784-d0d8ceab2bf2",
    "created_at": "2023-04-17T12:58:51.608547+00:00",
    "updated_at": "2023-04-17T12:58:51.608562+00:00",
    "document_id": null,
    "currency": "EUR",
    "subtotal": 150,
    "line_items": [
        {
            "quantity": 1.0,
            "product": {
                "name": "potato",
                "type": "product",
                "description": "Orange potato",
                "price": {
                    "currency": "EUR",
                    "value": 150
                },
                "measure_unit_id": "8054a1d1-8bdc-4eaa-8ec4-7de290a72c97",
                "smallest_amount": 1.0,
                "ledger_account_id": null,
                "id": "26c0f554-5d53-40b7-bd46-bb88f0a8a36b",
                "entity_id": "e1f7dd6e-5726-488b-83f6-7dd2b2613254",
                "entity_user_id": null,
                "created_at": "2023-04-17T12:52:44.835115+00:00",
                "updated_at": "2023-04-17T12:52:44.835124+00:00",
                "vat_rate": {
                    "id": "8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
                    "created_at": "2023-03-24T05:32:17.923094+00:00",
                    "updated_at": "2023-04-06T17:45:16.773977+00:00",
                    "value": 0,
                    "country": "DE",
                    "valid_until": null,
                    "valid_from": null,
                    "status": "active",
                    "created_by": "monite"
                },
                "measure_unit": {
                    "name": "kg",
                    "description": "kilogram",
                    "id": "8054a1d1-8bdc-4eaa-8ec4-7de290a72c97",
                    "created_at": "2023-04-17T12:52:40.780963+00:00",
                    "updated_at": "2023-04-17T12:52:40.780978+00:00"
                }
            },
            "discount": null,
            "total_before_vat": 150
        }
    ],
    "entity_address": {
        "country": "DE",
        "city": "Berlin",
        "postal_code": "10115",
        "state": "BE",
        "line1": "Flughafenstrasse 52",
        "line2": null
    },
    "entity": {
        "phone": null,
        "logo": null,
        "email": "[email protected]",
        "name": "Stracke, Balistreri and Gulgowski",
        "vat_id": "000000000",
        "type": "organization"
    },
    "entity_user_id": null,
    "counterpart_id": "155f6af7-ce95-441c-8032-a66145044833",
    "counterpart_tax_id": "DE12345678",
    "counterpart_type": "organization",
    "counterpart_address": {
        "country": "DE",
        "city": "Berlin",
        "postal_code": "10115",
        "state": "",
        "line1": "Flughafenstrasse 52",
        "line2": ""
    },
    "counterpart_contact": {
        "first_name": "Schmitt - Brown",
        "last_name": "",
        "email": "[email protected]",
        "phone": "1234567890",
        "title": null,
        "address": {
            "country": "DE",
            "city": "Berlin",
            "postal_code": "10115",
            "state": "",
            "line1": "Flughafenstrasse 52",
            "line2": ""
        }
    },
    "counterpart_name": "Schmitt - Brown",
    "file_url": null,
    "file": {
        "id": "5595ffea-9d4d-433d-8d56-a8232b424b6e",
        "created_at": "2023-04-17T12:56:02.815173+00:00",
        "file_type": "receivables",
        "name": "receivables.pdf",
        "region": "eu-central-1",
        "md5": "69e7f4d350f3b445247c01e5870acb12",
        "mimetype": "application/pdf",
        "url": "https://monite-file-saver-receivables-eu-central-1-sandbox.s3.amazonaws.com/5595ffea-9d4d-433d-8d56-a8232b424b6e/2227ce4b-e734-44be-90be-c86a2cd0e362.pdf",
        "size": 127988,
        "previews": [],
        "pages": []
    },
    "commercial_condition_description": "",
    "total_amount": 150,
    "total_vat_amount": 0,
    "entity_bank_account": {
        "iban": "DE91100000000123456789",
        "bic": "DEABCD11",
        "bank_name": "Omega Bank",
        "display_name": "Omega Bank",
        "is_default": false
    },
    "vat_exempt": false,
    "vat_exemption_rationale": "",
    "based_on": "7e79dba5-4769-4a9c-9596-93af4859b53e",
    "based_on_document_id": "receivable-00002",
    "memo": null,
    "issue_date": null,
    "counterpart_shipping_address": null,
    "counterpart_billing_address": null,
    "counterpart_business_type": null,
    "discount": null,
    "discounted_subtotal": 150,
    "total_vat_amounts": [
        {
            "id": "8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
            "value": 0,
            "amount": 0
        }
    ],
    "type": "credit_note",
    "status": "draft",
    "purchase_order": null
}

Issue the credit note

Once the credit note details have been finalized, you can mark the credit note as issued. To do this, call POST /receivables/{credit_note_id}/issue:

curl -X POST 'https://api.sandbox.monite.com/v1/receivables/{credit_note_id}/issue' \
     -H 'X-Monite-API-Version: 2023-06-04' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'

When a credit note is issued, the following happens:

The credit note status is changed to issued.
A document number is generated for the credit note in the format #receivable-<number> and is stored in the document_id field for tracking purposes.
based_on and based_on_document_id fields of the credit notes are updated to point to the related invoice.
The issue_date is set to the current date.
The total_amount_with_credit_notes field of the related invoice is updated to reflect the credited amount.
The credit note becomes read-only and can no longer be edited.

If the credit note amount equals the due amount on the related invoice (so that the invoice total_amount_with_credit_notes becomes 0), the invoice status is automatically changed to canceled.

List all credit notes

To list all credit notes, call GET /receivables?type=credit_note.

Find all credit notes for an invoice

To check if there are credit notes issued for a specific invoice, call GET /receivables?based_on={invoice_id}:

curl 'https://api.sandbox.monite.com/v1/receivables?based_on={invoice_id}' \
     -H 'X-Monite-Version: 2023-06-04' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'

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

{
  "data": [
    {
      "type": "credit_note",
      "id": "{credit_note_id}",
      ...
    }
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}