Payable 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:
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 calling POST /payables/{payable_id}/cancel
:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/cancel' \
-H 'X-Monite-Version: 2023-03-14' \
-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",
...
}
Start approval
Current status: new
Once an uploaded payable has been validated, the approval process is started by calling POST /payables/{payable_id}/submit_for_approval
:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/submit_for_approval' \
-H 'X-Monite-Version: 2023-03-14' \
-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",
...
}
The counterpart auto-linking and auto-creation may happen during this transition.
Confirm for payment
Current status: new
, approval_in_progress
To confirm that a payable is ready to be paid, call POST /payables/{payable_id}/approve_payment_operation
:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/approve_payment_operation' \
-H 'X-Monite-Version: 2023-03-14' \
-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 calling POST /payables/{payable_id}/reject
:
curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/reject' \
-H 'X-Monite-Version: 2023-03-14' \
-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",
...
}
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
, call POST /payables/{payable_id}/mark_as_paid
. 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-03-14' \
-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 2 months ago