> This page is for version v2024-05-25 (default).
> For other versions, use one of these documentation indexes:
> - v2024-05-25 (default): https://docs.monite.com/v-2024-05-25/llms.txt
> - v2024-01-31: https://docs.monite.com/v2024-01-31/llms.txt
> - v2023-09-01: https://docs.monite.com/v2023-09-01/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.monite.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server.

# Credit note lifecycle (accounts payable)

> **Info**
>
> This guide covers credit notes in accounts payable. Monite also supports [credit notes for accounts receivable](/accounts-receivable/credit-notes).

## Overview

Each credit note is allocated with a status that indicates its progress throughout the credit note lifecycle, from its creation until its application.

![Credit note lifecycle](/_fern-img/212de78117b0a10b35fa60cbab4a76352ee89659d070994694c96f208600db2e.webp)

## Credit note statuses \[#statuses]

Check out below a detailed explanation of the credit note statuses and the credit note approval process:

### Draft

**Status value:** `draft`

This is the initial status for all uploaded credit notes that have any of the required fields set as `null` during their creation. The required fields are:

* `currency`
* `document_id`
* `issued_at`
* `based_on`
* `tax_amount`
* `total_amount`
* `subtotal`

A draft credit note is not approved yet and can still be edited.

> **Info**
>
> Only one draft credit note can exist per payable. Before you can create the second draft credit note for the same payable, you need to apply (or delete) the previous draft credit note.

---

#### Customize the list of required fields \[#required-fields]

You can change and customize the list of required fields that are necessary to move a credit note to the `new` state by sending a `PUT` request to the [`/payable_credit_notes/validations`](/api/credit-notes/put-payable-credit-notes-validations) endpoint passing the new list of required fields as an array of strings:

```sh
curl -X PUT 'https://api.sandbox.monite.com/v1/payable_credit_notes/validations' \
     -H 'X-Monite-Version: 2024-05-25' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -d '{
       "required_fields": [
         "description",
         "tax"
       ]
      }'
```

The successful `200` response returns the new list of required fields:

```json
{
  "required_fields": ["description", "tax"]
}
```

* A successful request overwrites the existing list of required fields and replaces them with the newly defined array of required fields.
* If a composed field is specified, e.g. `line_items`, a minimum of one item will be required.
* It is possible to specify fields of different levels, e.g. `line_items.subtotal`.
* If the custom required fields list is not specified, the default validation is applied.
* To list the current required fields, send a `GET` request to the [`/payable_credit_notes/validations`](/api/credit-notes/get-payable-credit-notes-validations) endpoint.
* To remove the custom required fields and return the validation to the default one, send a `POST` request to the [`/payable_credit_notes/validations/reset`](/api/credit-notes/post-payable-credit-notes-validations-reset) endpoint. The default behavior will be applied to the future payables created.
* Credit notes that have already passed the `new` status will not be affected by newly updated required fields.

#### Validate mandatory fields

To understand what information is missing to move a credit note from `draft` to the `new` state, send a `POST` request to the [`/payable_credit_notes/{credit_note_id}/validate`](/api/credit-notes/get-payable-credit-notes-id-validate) endpoint:

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/{credit_note_id}/validate' \
  -H 'X-Monite-Version: 2024-05-25' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -d ''
```

The successful `200` response returns the fields that need to be filled for the transition:

```json
{
  "id": "d1d5da69-9c1b-42fc-a1d2-9dcc4c3c691f",
  "validation_errors": [
    {
      "loc": ["tax_amount"],
      "msg": "none is not an allowed value",
      "type": "type_error.none.not_allowed"
    },
    {
      "loc": ["line_items"],
      "msg": "ensure this value has at least 1 items",
      "type": "value_error.list.min_items",
      "ctx": {
        "limit_value": 1
      }
    }
  ]
}
```

### New

**Status value:** `new`

If the credit note already contains all essential fields (`currency`, `document_id`, `issued_at`, `based_on`, `tax_amount`, `total_amount`, and `subtotal`), its initial status is directly set to `new`.

Only credit notes in the `new` status can be sent for approval. To do this, call `POST /payable_credit_notes/{credit_note_id}/submit_for_approval`:

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/{credit_note_id}/submit_for_approval' \
    -H 'X-Monite-Version: 2024-05-25' \
    -H 'X-Monite-Entity-Id: ENTITY_ID' \
    -H 'Authorization: Bearer ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -d ''
```

The successful response indicates that the status of the credit note has changed to `approve_in_progress`. Once the credito note is sent for approval, it cannot be updated anymore.

The entity users can also directly [approve the credit note](#approve-in-progress) from the `new` status.

---

### Canceled

**Status value:** `canceled`

The `canceled` credit notes are the ones that were not validated during the entity user review.

For example, if the entity user uploads the wrong file or the document is not compliant with regulations, this credit note can be canceled before being sent for approval.

To cancel a credit note, call `POST /payable_credit_notes/{credit_note_id}/cancel`:

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/{credit_note_id}/cancel' \
  -H 'accept: application/json' \
  -H 'X-Monite-Version: 2024-05-25' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -d ''
```

There is no possible status change when a credit note is canceled.

---

### Approve in progress

**Status value:** `approve_in_progress`

After the initial validation, the credit note is ready to be approved by an entity user. To do this, call `POST /payable_credit_notes/{credit_note_id}/approve`:

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/{credit_note_id}/approve' \
  -H 'accept: application/json' \
  -H 'X-Monite-Version: 2024-05-25' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -d ''
```

---

### Rejected

**Status value:** `rejected`

The credit notes that are refused during the `approve_in_progress` status. By adding a reason for the refusal, the entity user who uploaded the payable knows what went wrong. To do this, call `POST /payable_credit_notes/{credit_note_id}/reject`:

```sh
curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/{credit_note_id}/reject' \
  -H 'accept: application/json' \
  -H 'X-Monite-Version: 2024-05-25' \
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
  -d ''
```

There is no possible status change when a credit note is rejected.

---

### Approved

**Status value:** `approved`

This status indicates that the credit note has been approved by all the required approvers and is ready to be applied.

---

### Applied

**Status value:** `applied`

Entity users can access all applied credit notes to view any details and export these documents for accounting reasons.