> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.monite.com/v-2024-05-25/accounts-payable/approvals/manual-transition/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server. # Manual status transition ## 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](../../references/glossary#payable) can transition from status to status: ![All the possible status transitions for a Payable](/_fern-img/f2c6ee2fe4c693d6086c8dd2902590fed3820bfda740e4440cd53753e1ec569d.webp) Once a [payable is uploaded](../payables/collect), its status is set to either `draft` (if any of the [essential fields](../payables/index#statuses) 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](../payables/index#statuses), 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` When a manual approval/rejection is triggered, any pending approval requests linked to the payable are automatically cancelled. 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](../../references/glossary#entity-user) review can be canceled by sending a `POST` request to the `/payables/{payable_id}/cancel` endpoint: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/cancel' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' ``` The successful response reflects the new status of the payable: ```json { ... "status": "canceled", ... } ``` > **Info** > > To use the `/payables/{payable_id}/cancel` endpoint with an [entity user token](../../entities/users#get-entity-user-token), this entity user must have a [role](../../entities/users#create-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: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/submit_for_approval' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' ``` The successful response reflects the new status of the payable: ```json { ... "status": "approve_in_progress", ... } ``` Once the payable is sent for approval, it cannot be updated anymore. The counterpart [auto-linking](../../common/counterparts/index#auto-linking) and [auto-creation](../../common/counterparts/index#auto-creation) may happen during this transition. If the `payable.enforce_approval_policy_id` is set, the system applies only the specified policy. The enforced policy runs regardless of whether the payable matches its trigger conditions, and policy priority is ignored - only the specified policy is considered. ## 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: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/approve_payment_operation' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \ ``` The successful response reflects the new status of the payable: ```json { ... "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: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/reject' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \ ``` The successful response reflects the new status of the payable: ```json { ... "status": "rejected", ... } ``` ## Reopen **Current status:** `rejected`, `waiting_to_be_paid` A payable in the `rejected` and `waiting_to_be_paid` statuses 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: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/payables/{payable_id}/reopen' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \ ``` The successful response reflects the new status of the payable: ```json { ... "status": "new", ... } ``` > **Info** > > * To use the `/payables/{payable_id}/reopen` endpoint with an [entity user token](../../entities/users#get-entity-user-token), this entity user must have a [role](../../entities/users#create-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: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/payables/411dc6eb...6289b3/mark_as_partially_paid' \ -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 '{ "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`: ```json { "partner_metadata": {}, "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "marked_as_paid_with_comment": null, "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": "hello@example.com", "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](../payables/index#statuses). * 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](../../entities/users#get-entity-user-token), this entity user must have a [role](../../entities/users#create-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: ```sh curl -X 'POST https://api.sandbox.monite.com/v1/payables/{payable_id}/mark_as_paid' \ -H 'X-Monite-Version: 2024-05-25' \ -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: ```json { .... "currency": "EUR", "total_amount": 1500, "due_date": "2023-12-18", "payment_terms": { "name": "2/10, 1/20, net 30", "term_1": { "number_of_days": 10, "discount": 200 }, "term_2": { "number_of_days": 20, "discount": 100 }, "term_final": { "number_of_days": 30 } }, "suggested_payment_term": { "date": "2023-07-25", "discount": 200 }, "issued_at": "2023-12-18", "payable_origin": "upload", "was_created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "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", .... } ``` > **Info** > > * To use the `/payables/{payable_id}/mark_as_paid` endpoint with an [entity user token](../../entities/users#get-entity-user-token), this entity user must have a [role](../../entities/users#create-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. > Learn how to manually change the status of the payables and move them through the workflow until their payment.