Manage payables

Learn how to manage your payables.

Change payable status

You can manually change the status of the payables and move them through the lifecycle until their payment. See Manual transition for more information.

Alternatively, we recommend that you implement approval policies to manage the payables transitions.

/*

Get payables analytics

You can obtain aggregated statistics for the total number and sum total amount of all existing payables, along with the breakdown per payable status. To do this, send a GET request to the /payables/analytics endpoint.

The results can be filtered by a specific time period, counterpart, or other search filters. For the full list of available sort and filter parameters, see the GET /payables/analytics endpoint.

For example, to get statistics about all payables in the approve_in_progress and waiting_to_be_paid statuses, call GET /payables/analytics?status__in=approve_in_progress&status__in=waiting_to_be_paid:

1curl -X GET 'https://api.sandbox.monite.com/v1/payables/analytics?status__in=approve_in_progress&status__in=waiting_to_be_paid&id__in=' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

The successful response contains the total number and sum total amount of all existing payables:

1{
2  "count": 35,
3  "data": [
4    {
5      "count": 22,
6      "status": "approve_in_progress",
7      "sum_total_amount": 12566
8    },
9    {
10      "count": 13,
11      "status": "waiting_to_be_paid",
12      "sum_total_amount": 22688
13    }
14  ],
15  "sum_total_amount": 35254
16}

Some other examples of statistics:

  • GET /payables/analytics?created_at__gte=2023-10-01T14%3A48%3A00Z&created_at__lte=2023-10-31T14%3A48%3A00Z - Get statistics about all payables for a specific period.
  • GET /payables/analytics?counterpart_name=Acme%20Inc. - Get statistics about all payables for a specific counterpart. */

List all payables

It is possible to view all the payables in the Monite space. To allow the right level of access to the authorized users, Monite allows certain entity users to view them but not change uploads.

To list all payables, call GET /payables. You can sort and filter the results by the amount, status, and other fields. For the full list of available sort and filter parameters, see the GET /payables endpoint.

Some examples:

  • GET /payables?search_text=Acme%20Inc. - applies the icontains condition to search for the text “Acme Inc.” in the document_id and counterpart_name fields in the payables.
  • GET /payables?counterpart_name=Acme%20Inc. - get all payables issued to Acme Inc.
  • GET /payables?amount__gte=15000 - get all payables where the total amount is 150$ or more.
  • GET /payables?status__in=draft&status__in=new - get all draft and new payables.
  • GET /payables?created_at__gte=2022-01-01T00%3A00%3A00 - get all payables created on or after January 1, 2022.
  • GET /payables?&ocr_status=error - get all payables that have failed to be recognized by the OCR.
  • GET /payables?tag_ids=df715ea3-e8a9-44d0-845c-2beceeb5589e - get all payables containing a specific tag.

Sample request to fetch 100 payables:

1curl -X GET 'https://api.sandbox.monite.com/v1/payables?order=asc&limit=100' \
2     -H 'X-Monite-Version: 2024-05-25' \
3     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4     -H 'Authorization: Bearer ACCESS_TOKEN'

The successful response returns a paged series of all payables that the entity has access to. For example:

1{
2  "data": [
3    {
4      "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
5      "entity_id": "b0ff50d0-cdea-42fd-9461-1b3799b65bcf",
6      "marked_as_paid_with_comment": null,
7      "marked_as_paid_by_entity_user_id": null,
8      "status": "new",
9      "source_of_payable_data": "ocr",
10      "currency": "EUR",
11      "total_amount": 9900,
12      "description": null,
13      "due_date": "2022-06-30",
14      "partner_metadata": {},
15      ...,
16    }
17  ],
18  "prev_pagination_token": null,
19  "next_pagination_token": "bGltaXQ9MiZmaXJzdF9vaWQ9MSZuZXh0X3Rva2VuPTQ="
20}

The prev_pagination_token and next_pagination_token fields in the response are pagination tokens.

Retrieve a payable

Once a payable is uploaded, the entity and entity users can review the information extracted from the payable by the OCR system.

To retrieve a payable, call GET /payables/{payable_id}:

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

The successful response contains the payable attributes:

1{
2  "id": "aa314fdd-a763-4920-a8c8-6285fc1745c0",
3  "entity_id": "b0ff50d0-cdea-42fd-9461-1b3799b65bcf",
4  "marked_as_paid_with_comment": null,
5  "marked_as_paid_by_entity_user_id": null,
6  "amount_due": 9900,
7  "amount_paid": 0,
8  "amount_to_pay": 9900,
9  "status": "new",
10  "total_amount": 9900,
11  "source_of_payable_data": "ocr",
12  "currency": "EUR",
13  "description": null,
14  "due_date": "2023-07-15",
15  "partner_metadata": {},
16  "payment_terms": {
17    "name": "2/10, 1/20, net 30",
18    "term_1": {
19      "number_of_days": 10,
20      "discount": 200
21    },
22    "term_2": {
23      "number_of_days": 20,
24      "discount": 100
25    },
26    "term_final": {
27      "number_of_days": 30
28    }
29  },
30  "suggested_payment_term": {
31    "date": "2023-07-25",
32    "discount": 200
33  },
34  "issued_at": "2023-06-15",
35  "counterpart_bank_id": "DEUTDE2HXXX",
36  "counterpart_id": "8737964a-5246-47f4-8243-8728a2be1e75",
37  "counterpart_bank_account_id": "ee415e8a-4368-4ef8-b192-d25b8e86ad0f",
38  "counterpart_address_id": "d0f2899d-e2b1-4b95-8411-2ed1a9063bce",
39  "counterpart_vat_id_id": "c0d3ca66-bdfa-4cdb-aceb-633d4dfe4f11",
40  "counterpart_account_id": "123456789012",
41  "counterpart_name": "Acme Inc.",
42  "counterpart_address": {
43    "country": "DE",
44    "city": "Berlin",
45    "postal_code": "10115",
46    "state": "BE",
47    "line1": "Flughafenstrasse 52",
48    "line2": "Floor 2"
49  },
50  "payable_origin": "upload",
51  "created_by_role_id": "6ba5a3b8-82c6-4aaa-b010-03bc4128b342",
52  "was_created_by_user_id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
53  "currency_exchange": {
54    "default_currency_code": "EUR",
55    "rate": 10.0,
56    "total": 0
57  },
58  "file": {
59    "id": "2d14935e-505b-4863-a082-b6a340acabbc",
60    "created_at": "2021-11-25T05:10:35.211432+00:00",
61    "file_type": "payables",
62    "name": "file name",
63    "region": "eu-central-1",
64    "md5": "623470039566983ed5e5945f769ea873",
65    "mimetype": "image/png",
66    "url": "https://monite-payables.com/2d14935e.../669bab57c57f.png",
67    "size": 49463,
68    "previews": [],
69    "pages": []
70  },
71  "tags": [
72    {
73      "name": "Marketing",
74      "id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5",
75      "created_at": "2022-09-07T16:35:18.484507+00:00",
76      "updated_at": "2022-09-07T16:35:18.484507+00:00",
77      "created_by_entity_user_id": "ea837e28-509b-4b6a-a600-d54b6aa0b1f5"
78    }
79  ],
80  "created_at": "2021-11-25T05:10:35.211432+00:00",
81  "updated_at": "2021-11-25T05:10:35.211447+00:00",
82  "ocr_request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
83  "ocr_status": "success",
84  "other_extracted_data": {
85    "total": 52649,
86    "currency": "EUR",
87    "line_items": [
88      {
89        "unit": "items",
90        "quantity": 0.25,
91        "unit_price": 38500,
92        "description": "Open Space - monthly rent",
93        "total_excl_vat": 9625,
94        "vat_percentage": 1900,
95        "line_item_ocr_id": "65391e037952904f8af4dbb2_0_cb9bdddf14bd17bf789a24f9d99a94bf"
96      },
97      {
98        "unit": "m",
99        "quantity": 1.0,
100        "unit_price": 38500,
101        "description": "Open Space - extra requests",
102        "total_excl_vat": 38500,
103        "vat_percentage": 700,
104        "line_item_ocr_id": "65391e037952904f8af4dbb2_1_3332ec854a09518fccd73598795147e7"
105      }
106    ],
107    "document_id": "202008476",
108    "tax_payer_id": "DE 302071443",
109    "payment_terms": null,
110    "counterpart_name": "Mindspace Germany GmbH",
111    "document_due_date": "2021-02-01",
112    "counterpart_address": null,
113    "counterpart_account_id": "DE 57550104000595963377",
114    "document_issued_at_date": "2021-02-01",
115    "counterpart_address_object": {
116      "city": "Berlin",
117      "line1": "Wittestr . 30 , Haus F",
118      "line2": null,
119      "state": null,
120      "country": null,
121      "postal_code": "13509",
122      "original_country_name": null
123    }
124  },
125  "approval_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
126  "document_id": "DE2287",
127  "subtotal": 9000,
128  "tax": 1000,
129  "sender": "hello@example.com"
130}

Update a payable

Payables in the draft and new statuses can be updated, for example, to provide additional details or fix the information extracted by OCR. To update a payable, send a PATCH request to the /payables/{payable_id} endpoint with the request body containing the new field values. For example, to update the description field:

1curl -X PATCH 'https://api.sandbox.monite.com/v1/payables/{payable_id}' \
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       "description": "New description of the payable"
8     }'

Delete a payable

Payables in any status can be deleted by calling the DELETE /payables/{payable_id} endpoint:

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

This action is irreversible, and once deleted, payables can no longer be accessed.