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.

Roles and 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.

Use cases

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.

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.

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.

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.

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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/receivables' \
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
       "type": "credit_note",
8
       "based_on": "c50265da-fddc-4d04-8318-6a449ad84726"
9
     }'

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:

1
{
2
  "id": "ad69dcf0-6fcf-47eb-9628-e7430683bb52",
3
  ...
4
  "based_on": "c50265da-fddc-4d04-8318-6a449ad84726",
5
  "based_on_document_id": "INV-0004",
6
  ...
7
  "status": "draft",
8
  ...
9
}

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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/receivables' \
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
       "type": "credit_note",
8
       "based_on": "c50265da-fddc-4d04-8318-6a449ad84726"
9
     }'

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

1
{
2
  "id": "ad69dcf0-6fcf-47eb-9628-e7430683bb52",
3
  ...
4
  "based_on": "c50265da-fddc-4d04-8318-6a449ad84726",
5
  "based_on_document_id": "INV-0004",
6
  ...
7
  "status": "draft",
8
  ...
9
}

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.

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_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
       "credit_note": {
8
         "line_items": {
9
           "PRODUCT_ID_1": {
10
             "quantity": 5,
11
             "price_diff": 100
12
           },
13
           "PRODUCT_ID_2": {
14
             "quantity": 3,
15
             "price_diff": 200
16
           },
17
           ...
18
         }
19
         "memo": "Optional message to display on the credit note",
20
         "partner_metadata": { ... }
21
       }
22
     }'

Notes:

• The structure of the line_items 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.

Example 1: Reduce line item quantity

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

To reduce the product quantity from 10 to 8 (in other words, to remove 2 items), update the credit note data as follows:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_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
       "credit_note": {
8
         "line_items": {
9
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {
10
             "quantity": 2
11
           }
12
         }
13
       }
14
     }'

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 5 EUR (500 in minor units), and the quantity is 10.

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

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_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
       "credit_note": {
8
         "line_items": {
9
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {
10
             "quantity": 10,
11
             "price_diff": 100
12
           }
13
         }
14
       }
15
     }'

A successful request applies a discount of 1 EUR (100 in minor units) to all 10 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 5 EUR (500 in minor units), and the quantity is 10.

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

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_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
       "credit_note": {
8
         "line_items": {
9
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {
10
             "quantity": 2,
11
             "price_diff": 100
12
           }
13
         }
14
       }
15
     }'

A successful request applies a discount of 1 EUR (100 in minor units) to 2 of the 10 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 5 EUR (500 in minor units), and the quantity is 10.

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

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/CREDIT_NOTE_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
       "credit_note": {
8
         "line_items": {
9
           "9ccaf14e-c14d-48eb-8801-4217d52b6114": {
10
             "quantity": 2,
11
             "price_diff": 200,
12
             "old_price": 400
13
           }
14
         }
15
       }
16
     }'

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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/ad69dc...b52/issue' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -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.

Download a credit note as PDF

Monite automatically generates the PDF version of credit notes in the counterpart language and the entity language, and returns links to these files in the file_url and original_file_url fields of credit note responses:

1
{
2
  "type": "credit_note",
3
  ...
4
  // Counterpart's version of a PDF credit note
5
  "file_language": "nl",
6
  "file_url": "https://bucketname.s3.amazonaws.com/<random_UUID_1>/<random_UUID_2>.pdf",
7
  ...
8
  // Entity's version of a PDF credit note
9
  "original_file_language": "en",
10
  "original_file_url": "https://bucketname.s3.amazonaws.com/<random_UUID_3>/<random_UUID_4>.pdf",
11
  ...
12
}

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

1
curl -X GET 'https://api.sandbox.monite.com/v1/receivables/ad69dc...b52/pdf_link' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

It returns the following response:

1
{
2
  "file_url": "https://bucketname.s3.amazonaws.com/<random_UUID_1>/<random_UUID_2>.pdf",
3
  "original_file_url": "https://bucketname.s3.amazonaws.com/<random_UUID_3>/<random_UUID_4>.pdf"
4
}

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. The language of the email template used is determined by the counterpart’s language.

Monite also allows you to provide a list of email addresses to which you can send the credit note. You can also include other email addresses to which you can send a copy or a blind copy of the credit note, as shown:

1
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/ad69dc...b52/send' \
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
       "subject_text": "Credit note {credit_note_number} from {entity_name}",
8
       "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!",
9
       "recipients": {
10
         "to": ["dana@example.com"],
11
         "cc": ["support@example.com", "sales@example.com"],
12
         "bcc": ["exec@example.com"]
13
       }
14
     }'

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 noreply@monite.com 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.

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}:

1
curl -X GET 'https://api.sandbox.monite.com/v1/receivables?based_on=INVOICE_ID' \
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
}