Status transitions
Learn how to change the status of the payables and move them through the workflow until their payment.
Overview
The chart below shows all the different ways that a payable can transition from status to status:

All the possible status transitions for a Payable.
Once a payable is uploaded, its status is set to either draft
(if any of the essential fields are missing) or new
(if the uploaded payable already contains all essential fields during its creation).
After a payable in the draft
status has all essential fields filled out, its status automatically changes to new
.
This payable then needs to go through additional approval statuses before it is cleared for payment:
approval_in_progress
waiting_to_be_paid
The allowed status transitions depend on the current status of a payable.
Cancel a payable
Current status: new
, approval_in_progress
A payable that is not confirmed during the entity user review can be canceled by sending a POST
request to the /payables/{payable_id}/cancel
endpoint:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/cancel' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
The successful response reflects the new status of the payable:
{
...
"status": "canceled",
...
}
Note
To use the
/payables/{payable_id}/cancel
endpoint with an entity user token, this entity user must have a role that includes thecancel
permission.
Start approval
Current status: new
After an uploaded payable has been validated, the approval process can be started by sending a POST
request to the /payables/{payable_id}/submit_for_approval
endpoint:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/submit_for_approval' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN'
The successful response reflects the new status of the payable:
{
...
"status": "approval_in_progress",
...
}
Once the payable is sent for approval, it cannot be updated anymore. The counterpart auto-linking and auto-creation may happen during this transition.
Confirm for payment
Current status: new
, approval_in_progress
After the payable is approved by all the required approvers, it is ready to be sent for payment. To confirm that a payable is ready to be paid, send a POST
request to the /payables/{payable_id}/approve_payment_operation
endpoint:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/approve_payment_operation' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
The successful response reflects the new status of the payable:
{
...
"status": "waiting_to_be_paid",
...
}
Reject
Current status: approval_in_progress
If an approver finds any mismatch or discrepancies in the payable, they can decline it by sending a POST
request to the POST /payables/{payable_id}/reject
endpoint:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/reject' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
The successful response reflects the new status of the payable:
{
...
"status": "rejected",
...
}
Reopen
Current status: rejected
A payable in the rejected
status can be moved back to new
. It makes it possible to fix any mismatch or discrepancies in the payable and then send it for approval again, repeating this process as many times as necessary.
To reopen a payable, send a POST
request to the POST /payables/{payable_id}/reopen
endpoint:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/reopen' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
The successful response reflects the new status of the payable:
{
...
"status": "new",
...
}
Notes
- To use the
/payables/{payable_id}/reopen
endpoint with an entity user token, this entity user must have a role that includes thereopen
permission.- Reopening a payable triggers the webhook
payable.reopened
.
Mark as partially paid
If the payable is partially paid, its status is moved to partially_paid
. To mark a payable as partially_paid
, send a POST
request to the /payables/{payable_id}/mark_as_partially_paid
endpoint with the request body containing the new amount_paid
(value of the partial payment, in minor units). The value of the amount_paid
field must be the sum of all payments made, not only the last one:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/411dc6eb...6289b3/mark_as_partially_paid' \
-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 '{
"amount_paid": 300
}'
The successful response contains information about the payable, including the amount_due
field, which represents the remaining amount to be paid. This field is automatically calculated by the result of total
- amount_paid
:
{
"partner_metadata": {},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"marked_as_paid_with_comment": "Was paid partly in the end of the month.",
"marked_as_paid_by_entity_user_id": "71e8875a-43b3-434f-b12a-54c84c176ef3",
"amount_due": 700,
"amount_paid": 300,
"amount_to_pay": 1000,
"status": "draft",
"source_of_payable_data": "ocr",
"currency": "EUR",
"amount": 1000,
"description": "Restock office supplies",
"due_date": "2023-08-23",
"payment_terms": {..},
"issued_at": "2023-08-23",
"payable_origin": "upload",
"was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"currency_exchange": {
"default_currency_code": "EUR",
"rate": 10.0,
"total": 0
},
"file": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"created_at": "2023-08-23T08:17:59.671Z",
"file_type": "payables",
"name": "invoice.pdf",
"region": "eu-central-1",
"md5": "31d1a2dd1ad3dfc39be849d70a68dac0",
"mimetype": "application/pdf",
"url": "https://bucketname.s3.amazonaws.com/12345/67890.pdf",
"size": 24381,
"previews": [],
"pages": []
},
"tags": [
{
"name": "Marketing",
"id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
"created_at": "2022-09-07T16:35:18.484507+00:00",
"updated_at": "2022-09-07T16:35:18.484507+00:00",
"created_by_entity_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
}
],
"created_at": "2023-08-23T08:17:59.671Z",
"updated_at": "2023-08-23T08:17:59.671Z",
"other_extracted_data": {...},
"approval_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"document_id": "DE2287",
"subtotal": 1250,
"tax": 1900,
"sender": "[email protected]",
"line_items": [..],
"ocr_request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"counterpart_bank_id": "DEUTDE2HXXX",
"counterpart_account_id": "123456789012",
"counterpart_name": "Acme Inc.",
"counterpart_tax_id": "DE12345678",
"counterpart_address": {
"country": "DE",
"city": "Berlin",
"postal_code": "10115",
"state": "BE",
"line1": "Flughafenstrasse 52",
"line2": null
},
"counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"counterpart_bank_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"counterpart_address_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"counterpart_vat_id_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"counterpart": {..},
"counterpart_raw_data": {..}
}
Notes
- This endpoint can be used for payables in the
waiting_to_be_paid
status.- The
amount_paid
must be greater than 0 and less than the total payable amount specified by theamount
field.- Make a
POST
request to/payables/{payable_id}/mark_as_paid
to mark the payable as fully paid.- The
amount_paid
can be either increased or decreased to reflect reversed payments and chargebacks.- You can make
POST
requests to/payables/{payable_id}/mark_as_partially_paid
multiple times for the same payable to reflect multiple partial payments, always setting the sum of all payments made.
Mark as paid
Current status: waiting_to_be_paid
Payables can be paid using the payment channels offered by Monite or through external payment channels. In the latter case, the invoice is not automatically marked as paid
in the system and needs to be converted to the paid
status manually.
To mark a payable as paid
, send a POST
request to the /payables/{payable_id}/mark_as_paid
endpoint. Optionally, it is possible to pass the comment
field in the request body, to describe how and when the invoice was paid:
curl -X 'POST https://api.sandbox.monite.com/v1/payables/{payable_id}/mark_as_paid' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
-d '{"comment": "Optional text that describes how and when the invoice was paid."}'
The successful response contains the ID of the user who marked the invoice as paid, the new status of the payable, and the comment:
{
...
"marked_as_paid_with_comment": "Optional text that describes how and when the invoice was paid.",
"marked_as_paid_by_entity_user_id": "71e8875a-43b3-434f-b12a-54c84c176ef3",
"status": "paid",
...
}
Updated 9 days ago