Credit note lifecycle (accounts payable)

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

Customize the list of 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 endpoint passing the new list of required fields as an array of strings:

1
curl -X PUT 'https://api.sandbox.monite.com/v1/payable_credit_notes/validations' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -d '{
6
       "required_fields": [
7
         "description",
8
         "tax"
9
       ]
10
      }'

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

1
{
2
  "required_fields": ["description", "tax"]
3
}

• 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 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 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 endpoint:

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

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

1
{
2
  "id": "d1d5da69-9c1b-42fc-a1d2-9dcc4c3c691f",
3
  "validation_errors": [
4
    {
5
      "loc": ["tax_amount"],
6
      "msg": "none is not an allowed value",
7
      "type": "type_error.none.not_allowed"
8
    },
9
    {
10
      "loc": ["line_items"],
11
      "msg": "ensure this value has at least 1 items",
12
      "type": "value_error.list.min_items",
13
      "ctx": {
14
        "limit_value": 1
15
      }
16
    }
17
  ]
18
}

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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/{credit_note_id}/submit_for_approval' \
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 ''

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

1
curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/{credit_note_id}/cancel' \
2
  -H 'accept: application/json' \
3
  -H 'X-Monite-Version: 2024-05-25' \
4
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
5
  -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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/{credit_note_id}/approve' \
2
  -H 'accept: application/json' \
3
  -H 'X-Monite-Version: 2024-05-25' \
4
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
5
  -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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/payable_credit_notes/{credit_note_id}/reject' \
2
  -H 'accept: application/json' \
3
  -H 'X-Monite-Version: 2024-05-25' \
4
  -H 'X-Monite-Entity-Id: ENTITY_ID' \
5
  -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.