Credit notes

Overview

A credit note, also known as a credit memo, is a legal document used to reduce the amount owed on an invoice after it was issued. Entities would typically use credit notes in the following cases:

An issued invoice contains a mistake (for example, wrong product or quantity).
The order needs to be changed after the invoice has been issued.
The order was canceled by the entity or the customer (counterpart).

Credit notes can be used to partially reduce the invoice amount as well as fully cancel an invoice.

Multiple credit notes can be issued for the same invoice. However, the total amount credited cannot exceed the invoice amount.

Use cases

The Monite API supports the following use cases for credit notes:

Reduce quantities of line items.
Example: an invoice was issued for 10 laptops, but only 8 were actually delivered. A credit note can "cancel" the remaining 2 laptops that were not delivered.
Reduce the price of some or all units within a line item. (Essentially applying a discount.)
Example: A product was mistakenly billed as € 210 instead of € 200. A credit note can correct the price back to € 200.
Credit the full remaining amount of an invoice. This cancels an unpaid invoice, or marks a partially paid invoice as paid.

📘
Credit notes cannot add new line items or increase the unit quantity and price in line items. Instead, the entity should issue a new invoice for the additional amount.

Considerations and limitations

Credit notes can be created only for invoices in the issued, partially_paid, and overdue statuses. Crediting paid invoices is not supported.
Credit notes for overdue and partially paid invoices can be used to reduce only the quantity of line items, but not the unit prices.
If a credit note cancels the full remaining amount of an invoice:
- issued and unpaid overdue invoices are automatically moved to the canceled status,
- partially_paid and partially paid overdue invoices are automatically moved to the paid status.
Changing line item VAT rates via credit notes is not supported.
If the original invoice contained any form of discounts or special deductions, you can only issue a credit note once. Partial adjustments of discounted invoices via credit notes are not supported.
If an invoice includes several line items for the same product, credit notes cannot be used to update those specific line items. However, other line items on the invoice can be updated.
If a counterpart's address or contact information was changed after an invoice was issued, you can provide the updated counterpart address or contact information via a credit note. However, the updated information will only appear in the credit note; the information in the original invoice is not changed.

📘
Permissions
To create and manage credit notes using an entity user token, this entity user must have a role with the receivables permission.
If a partner-level token is used, no special permissions are needed.

Credit note lifecycle

Credit notes can have one of two statuses, draft or issued.

Draft credit notes can be deleted. Deleted documents can no longer be accessed via the API.

Draft

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

Draft credit notes can be either issued or deleted.

📘
Only one draft credit note can exist per invoice. Before you can create the second draft credit note for the same invoice, you need to issue (or delete) the previous draft credit note.

Issued

This status indicates that the credit note has been finalized and issued to a counterpart.

Ways to create a credit note

There are two ways to create credit notes:

Create a credit note directly. Use this to manually adjust the credited amount (for example, to credit a partial amount).
Cancel an invoice. If the entity setting receivable_edit_flow is "compliant", a new credit note will be automatically created and issued for the remaining invoice amount.

📘
Credit notes are not automatically sent to counterparts. Use POST /receivables/{credit_note_id}/send to send credit notes via email.

Create a credit note manually

For the full remaining invoice amount

To create a credit note, call 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: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "credit_note",
       "based_on": "c50265da-fddc-4d04-8318-6a449ad84726"
     }'

This creates a draft credit note with a copy of invoice data. The response contains the id assigned to the credit note. The based_on and based_on_document_id properties of the credit note point to the original invoice:

{
  "id": "ad69dcf0-6fcf-47eb-9628-e7430683bb52",
  ...
  "based_on": "c50265da-fddc-4d04-8318-6a449ad84726",
  "based_on_document_id": "INV-0004",
  ...
  "status": "draft",
  ...
}

Full credit note response

{
    "id": "ad69dcf0-6fcf-47eb-9628-e7430683bb52",
    "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": "invoice-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
}

📘
By default, a newly created credit note cancels the full remaining amount of an invoice. If this is what you need, you can proceed to issue the credit note.

For a partial amount

The first step is the same as when creating a full amount credit note - call 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: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "credit_note",
       "based_on": "c50265da-fddc-4d04-8318-6a449ad84726"
     }'

This returns the id assigned to the created draft credit note:

{
  "id": "ad69dcf0-6fcf-47eb-9628-e7430683bb52",
  ...
  "based_on": "c50265da-fddc-4d04-8318-6a449ad84726",
  "based_on_document_id": "INV-0004",
  ...
  "status": "draft",
  ...
}

The next step is to adjust the line item quantities and prices as needed. To do this, call PATCH /receivables/{credit_note_id} and provide the updated values. The general PATCH request format for credit notes is as follows.

⚠️
The line items object
The following list provides additional information about the line items object and its subfields.

The structure of the line_item field in credit note PATCH requests differs from that in invoice objects.

The quantity field represents the number of products you want to remove or apply a discount via the credit note. This number must always be less than or equal to the current total on the invoice object.

The price_diff field defines the discount on the product. It represents the amount to be deducted from the current price on the invoice.

The old_price field defines the price of a previously discounted product. This field should only be used when applying a further discount on a product item.

curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_ID' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "credit_note": {         
         "line_items": {
           "PRODUCT_ID_1": {
             "quantity": 5,      
             "price_diff": 100
           },
           "PRODUCT_ID_2": {
             "quantity": 3,
             "price_diff": 200
           },
           ...
         }
         "memo": "Optional message to display on the credit note",
         "partner_metadata": { ... }
       }
     }'

Example 1: Reduce line item quantity

Consider an invoice line item object with product ID 9ccaf14e-c14d-48eb-8801-4217d52b6114, the price is 500 (5 EUR), and the quantity is 10.

To reduce the product quantity from 10 to 8, update the credit note data as follows:

curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_ID' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "credit_note": {
         "line_items": {
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": { 
             "quantity": 2  
           }
         }
       }
     }'

Example 2: Reduce the unit price of a line item

Consider an invoice line item object with product ID 9ccaf14e-c14d-48eb-8801-4217d52b6114, the price is 500 (5 EUR), and the quantity is 10.

To reduce the unit price from 500 (5 EUR) to 400 (4 EUR), update the credit note data as follows:

curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_ID' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "credit_note": {
         "line_items": {
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {  
             "quantity": 10,    
             "price_diff": 100 
           }
         }
       }
     }'

A successful request applies a 100 EUR discount to all ten products on the invoice line item.

Example 3: Reduce the price of some units within a line item

Consider an invoice line item object with product ID 9ccaf14e-c14d-48eb-8801-4217d52b6114, the price is 500 (5 EUR), and the quantity is 10.

Suppose you want to reduce the price of 2 units from 500 (5 EUR) to 400 (4 EUR). The other 8 units should keep the original price. To achieve this, update the credit note data as follows:

curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_ID' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "credit_note": {
         "line_items": {
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {  
             "quantity": 2,     
             "price_diff": 100  
           }
         }
       }
     }'

A successful request applies a 100 EUR discount to two of the ten products on the invoice line item. No change applies to the remaining 8 products on the invoice line item.

Example 4: Apply a further discount to an already discounted item

Consider an invoice line item object with product ID 9ccaf14e-c14d-48eb-8801-4217d52b6114, the price is 500 (5 EUR), and the quantity is 10.

Suppose you had already reduced the price of 2 items from 500 (5 EUR) to 400 (4 EUR). Now, you want to further reduce the price of 2 units from 400 (4 EUR) to 200 (2 EUR). To achieve this, update the credit note data as follows:

curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_ID' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "credit_note": {
         "line_items": {
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {  
             "quantity": 2,     
             "price_diff": 200,
             "old_price": 400
           }
         }
       }
     }'

Issue a 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/ad69dc...b52/issue' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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 CN-<number> and is stored in the document_id field for tracking purposes.
The issue_date is set to the current date.
The credit note becomes read-only and can no longer be edited.

Issuing a credit note also updates the reconciliation amounts on an invoice and may trigger a status change on the invoice.

If needed, additional credit notes can be created for the same invoice if it still has a remaining amount due.

📘
Note
Issuing a credit note does not automatically send it to the counterpart. See the Send a credit note via email section below to learn how to send credit notes.

Download a credit note as PDF

Monite automatically generates the PDF version of credit notes. The PDF file details—URL, file size, MD5 hash, and other information—are returned in the file object property in the credit note response:

{
  "type": "credit_note",
  ...
  "file": {
    ...
    "md5": "31d1a2dd1ad3dfc39be849d70a68dac0",
    "url": "https://bucketname.s3.amazonaws.com/<random_UUID_1>/<random_UUID_2>.pdf",
    "size": 24381,
    ...
  },
  ...
}

📘
If file is returned as null, repeat the request to GET /receivables/{credit_note_id} after some time.

If you need just the PDF file link without the full credit note details, call GET /receivables/{credit_note_id}/pdf_link:

curl -X GET 'https://api.sandbox.monite.com/v1/receivables/ad69dc...b52/pdf_link' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'

It returns the following response:

{
  "file_url": "https://bucketname.s3.amazonaws.com/<random_UUID_1>/<random_UUID_2>.pdf"
}

📘
The PDF file is updated automatically if the credit note data is changed.

Customize the PDF file

Monite provides several built-in PDF templates for receivables. Entities can change their default template or customize their chosen templates at any time. For more information, see PDF templates.

Send a credit note via email

Both draft and issued credit notes can be sent via email. Sending a draft credit note also automatically issues it.

To send a credit note to a counterpart via email, call POST /receivables/{credit_note_id}/send and provide the email subject and body text. Both the subject and body texts can include variables as placeholders for various credit note data and counterpart-specific data. The credit note will be attached as a PDF file to the email.

curl -X POST 'https://api.sandbox.monite.com/v1/receivables/ad69dc...b52/send' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "subject_text": "Credit note {credit_note_number} from {entity_name}",
       "body_text": "Dear {contact_name},\n\nThank you for your business!\nAs discussed, we are sending you the credit note {credit_note_number} to reduce the amount due on the invoice {based_on_document_id} ({based_on_amount_due}) by {amount_due}.\n For any questions or concerns, please do not hesitate to contact us at {entity_email}. We look forward to serving you again and wish you all the best!"
     }'

📘
The subject_text and body_text fields are email template variables that represent the email subject and body. For more information, see Create and manage email templates.

The To email address is taken from the Counterpart object associated with the credit note. This address is also returned in the counterpart_contact.email field of the Receivable object that represents the credit note.

All credit note emails are sent from the [email protected] email address by default. You can customize the email domain name—@exampleCompany.com— by configuring a mailbox for the entity. You can also customize the email sender name and username by updating your Monite partner settings. For more information, see Update partner settings.

A 200 OK response from POST /receivables/{credit_note_id}/send means the email was successfully sent from the Monite email server.

Resend a credit note

To resend a credit note, you can call POST /receivables/{credit_note_id}/send again, optionally with different subject_text and body_text templates.

📘
Note
Resending a credit note does not change its issued_date.

Miscellaneous

List all credit notes

To list all credit notes, call GET /receivables?type=credit_note. You can optionally filter the returned results by the credit note status or other parameters.

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 -X GET 'https://api.sandbox.monite.com/v1/receivables?based_on=INVOICE_ID' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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": "9c9f4b57-009e-43ef-a784-d0d8ceab2bf2",
      ...
    }
  ],
  "prev_pagination_token": null,
  "next_pagination_token": null
}

Credit notes

Overview

Use cases

📘

Considerations and limitations

📘
Permissions

Credit note lifecycle

Draft

📘

Issued

Ways to create a credit note

📘

Create a credit note manually

For the full remaining invoice amount

📘

For a partial amount

⚠️
The line items object

Example 1: Reduce line item quantity

Example 2: Reduce the unit price of a line item

Example 3: Reduce the price of some units within a line item

Example 4: Apply a further discount to an already discounted item

Issue a credit note

📘
Note

Download a credit note as PDF

📘

📘

Customize the PDF file

Send a credit note via email

📘

Resend a credit note

📘
Note

Miscellaneous

List all credit notes

Find all credit notes for an invoice

Overview

Use cases

📘

Considerations and limitations

📘Permissions

Credit note lifecycle

Draft

📘

Issued

Ways to create a credit note

📘

Create a credit note manually

For the full remaining invoice amount

📘

For a partial amount

⚠️The line items object

Example 1: Reduce line item quantity

Example 2: Reduce the unit price of a line item

Example 3: Reduce the price of some units within a line item

Example 4: Apply a further discount to an already discounted item

Issue a credit note

📘Note

Download a credit note as PDF

📘

📘

Customize the PDF file

Send a credit note via email

📘

Resend a credit note

📘Note

Miscellaneous

List all credit notes

Find all credit notes for an invoice

📘
Permissions

⚠️
The line items object

📘
Note

📘
Note