Manual status transition

Learn how to manually change the status of the payables and move them through the workflow until their payment.

Overview

Users can manually control the transit of a payable across its lifecycle by displaying approve/reject buttons to the approvers. 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
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:

  1. approve_in_progress
  2. waiting_to_be_paid

The allowed status transitions depend on the current status of a payable. They are:

Cancel a payable

Current status: draft, new

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:

1curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/cancel' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

The successful response reflects the new status of the payable:

1{
2  ...
3  "status": "canceled",
4  ...
5}

To use the /payables/{payable_id}/cancel endpoint with an entity user token, this entity user must have a role that includes the cancel 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:

1curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/submit_for_approval' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

The successful response reflects the new status of the payable:

1{
2  ...
3  "status": "approve_in_progress",
4  ...
5}

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

1curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/approve_payment_operation' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \

The successful response reflects the new status of the payable:

1{
2  ...
3  "status": "waiting_to_be_paid",
4  ...
5}

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:

1curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/reject' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \

The successful response reflects the new status of the payable:

1{
2  ...
3  "status": "rejected",
4  ...
5}

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:

1curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/reopen' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \

The successful response reflects the new status of the payable:

1{
2  ...
3  "status": "new",
4  ...
5}
  • To use the /payables/{payable_id}/reopen endpoint with an entity user token, this entity user must have a role that includes the reopen permission.
  • Reopening a payable triggers the webhook payable.reopened.

Mark as partially paid

Current status: waiting_to_be_paid, 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:

1curl -X POST 'https://api.sandbox.monite.com/v1/payables/411dc6eb...6289b3/mark_as_partially_paid' \
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       "amount_paid": 300
8     }'

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:

1{
2  "partner_metadata": {},
3  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
4  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
5  "marked_as_paid_with_comment": null,
6  "marked_as_paid_by_entity_user_id": "71e8875a-43b3-434f-b12a-54c84c176ef3",
7  "amount_due": 700,
8  "amount_paid": 300,
9  "amount_to_pay": 1000,
10  "status": "draft",
11  "source_of_payable_data": "ocr",
12  "currency": "EUR",
13  "amount": 1000,
14  "description": "Restock office supplies",
15  "due_date": "2023-08-23",
16  "payment_terms": {..},
17  "issued_at": "2023-08-23",
18  "payable_origin": "upload",
19  "was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
20  "currency_exchange": {
21    "default_currency_code": "EUR",
22    "rate": 10.0,
23    "total": 0
24  },
25  "file": {
26    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
27    "created_at": "2023-08-23T08:17:59.671Z",
28    "file_type": "payables",
29    "name": "invoice.pdf",
30    "region": "eu-central-1",
31    "md5": "31d1a2dd1ad3dfc39be849d70a68dac0",
32    "mimetype": "application/pdf",
33    "url": "https://bucketname.s3.amazonaws.com/12345/67890.pdf",
34    "size": 24381,
35    "previews": [],
36    "pages": []
37  },
38  "tags": [
39    {
40      "name": "Marketing",
41      "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
42      "created_at": "2022-09-07T16:35:18.484507+00:00",
43      "updated_at": "2022-09-07T16:35:18.484507+00:00",
44      "created_by_entity_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
45    }
46  ],
47  "created_at": "2023-08-23T08:17:59.671Z",
48  "updated_at": "2023-08-23T08:17:59.671Z",
49  "other_extracted_data": {...},
50  "approval_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
51  "document_id": "DE2287",
52  "subtotal": 1250,
53  "tax": 1900,
54  "sender": "hello@example.com",
55  "line_items": [..],
56  "ocr_request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
57  "counterpart_bank_id": "DEUTDE2HXXX",
58  "counterpart_account_id": "123456789012",
59  "counterpart_name": "Acme Inc.",
60  "counterpart_tax_id": "DE12345678",
61  "counterpart_address": {
62    "country": "DE",
63    "city": "Berlin",
64    "postal_code": "10115",
65    "state": "BE",
66    "line1": "Flughafenstrasse 52",
67    "line2": null
68  },
69  "counterpart_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
70  "counterpart_bank_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
71  "counterpart_address_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
72  "counterpart_vat_id_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
73  "counterpart": {..},
74  "counterpart_raw_data": {..}
75}

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 the amount field.
  • Make a POST request to /payables/{payable_id}/mark_as_paid to mark the payable as fully paid.
  • 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.
  • To use the /payables/{payable_id}/mark_as_partially_paid endpoint with an entity user token, this entity user must have a role that includes the pay permission for payables.
  • The amount_to_pay field is automatically calculated based on the amount_due less the percentage described in the payment_terms.discount value.

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:

1curl -X 'POST https://api.sandbox.monite.com/v1/payables/{payable_id}/mark_as_paid' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5     -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:

1{
2  ....
3  "currency": "EUR",
4  "total_amount": 1500,
5  "due_date": "2023-12-18",
6  "payment_terms": {
7    "name": "2/10, 1/20, net 30",
8    "term_1": {
9      "number_of_days": 10,
10      "discount": 200
11    },
12    "term_2": {
13      "number_of_days": 20,
14      "discount": 100
15    },
16    "term_final": {
17      "number_of_days": 30
18    }
19  },
20  "suggested_payment_term": {
21    "date": "2023-07-25",
22    "discount": 200
23  },
24  "issued_at": "2023-12-18",
25  "payable_origin": "upload",
26  "was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
27  "marked_as_paid_with_comment": "Optional text that describes how and when the invoice was paid.",
28  "marked_as_paid_by_entity_user_id": "71e8875a-43b3-434f-b12a-54c84c176ef3",
29  "status": "paid",
30  ....
31}
  • To use the /payables/{payable_id}/mark_as_paid endpoint with an entity user token, this entity user must have a role that includes the pay permission for payables.
  • The amount_to_pay field is automatically calculated based on the amount_due less the percentage described in the payment_terms.discount value.