Manage invoices
Learn how to manage invoices and change invoice statuses.
Update an invoice
All newly created invoices start in the draft
status. You can edit draft invoices before issuing them to a counterpart.
To edit a draft invoice, send a PATCH
request to the /receivables/{receivable_id}
endpoint with the request body containing the updated properties. You can update counterpart data, payment terms, invoice memo, existing line items data, and other details.
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3' \
-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 '{
"invoice": {
"currency": "USD",
"counterpart_id": "782b6f0f-0177-475c-b1e4-98dc160a656f",
"contact_id": "796d1f1d-f345-4888-849c-6cbcfbd39982",
"payment_terms_id": "f7bc5590-2680-462a-a2b4-7c564f65449d",
"entity_vat_id_id": "f7b796d1f1d-462a-4888-98dc160a656f6d",
"line_items": [
{
"quantity": 2,
"price": 7000
}
]
}
}'
When updating an invoice's counterpart, you must also provide the new counterpart's contact_id
in the request body to update the counterpart_contact
object.
Update invoice line items
New products cannot be added when updating an invoice. You can only update the data of existing line items on the invoice.
To update a line item, you must identify and target the line item's position in the line_items
array. For example, the following snippet shows how to update price
and quantity
values of the third line item on an invoice:
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3' \
-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 '{
"invoice": {
"line_items": [
{},
{},
{
"quantity": 2,
"price": 4000
}
]
}
}'
Connect an invoice to a payment link
All created invoices have an assigned QR code. By default, all invoices' QR codes point to the Monite homepage. Connecting a payment link to an invoice automatically generates a payment page dedicated to the specific invoice and updates the invoice's QR code destination to point to the newly created payment page.
You can connect a payment link to an invoice by making a POST
request to the /payment_links
endpoint. In the request body, you must include the object.id
field representing the invoice's ID. For more information about connecting a payment link to an invoice, see Payment links.
curl -X POST 'https://api.sandbox.monite.com/v1/payment_links' \
-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 '{
"return_url": "https://monite.com",
"recipient": {
"type": "entity",
"id": "7884aa8a-34c7-4c78-87d2-4d1c6b8c6936"
},
"payment_methods": [
"card", "sepa_debit", "sepa_credit"
],
"object": {
"id": "411dc6eb-3bf4-465b-8dfe-f6b5ec6289b3",
"type": "receivable"
}
}'
You can only generate payment links for invoices in the
issued
andoverdue
statuses. Attempting to create a payment link for an invoice in any other status will return an error.
Mark an invoice as partially paid
If the counterpart has paid the invoice partially, you can move the invoice to the partially_paid
status and provide the amount paid by updating the amount_paid
field on the invoice object. To do this, send a POST
request to the /receivables/{receivable_id}/mark_as_partially_paid
endpoint as shown:
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/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 '{
"anount_paid": 4500,
"comment": "Payment of 25 EUR was received on 2023/07/25. Total amount paid is now 45 EUR."
}'
The amount_paid
field in the request body represents the total amount in minor units that was paid toward the invoice. You can update this field continuously to reflect multiple partial payments—or payment reversals—by sending a POST
request to the same endpoint. The comment
field is optional, but if provided, it will be saved to the invoice object's comment
field and overwrite any previously existing comment
in that invoice.
Notes
- This endpoint can be used for invoices in the
issued
,partially_paid
, andoverdue
statuses. Issued invoices are moved to thepartially_paid
status, whereas invoices in thepartially_paid
andoverdue
statuses remain in those statuses.- The
amount_paid
field can also be decreased to reflect reversed payments and chargebacks.- The
amount_paid
field must always be less than the current value of the invoice'samount_to_pay
field.
Mark an invoice as paid
If the counterpart has paid an invoice in full, you can mark this invoice as paid by calling POST /receivables/{receivable_id}/mark_as_paid
. Optionally, you can provide a JSON request body with the comment
field that provides additional information about the paid invoice. For example, how and when the payment was made. This comment will be saved to the comment
field of the invoice object.
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/mark_as_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 '{
"comment": "Paid on 2022/10/25 by a wire transfer."
}'
Only invoices in the
issued
,overdue
, andpartially_paid
statuses can be marked paid.
Mark an invoice as uncollectible
If an invoice is overdue and the counterpart cannot pay it due to insolvency, you can write off this invoice as uncollectible. To do this, call POST /receivables/{receivable_id}/mark_as_uncollectible
. This will change the invoice status
to "uncollectible".
Optionally, you can provide a JSON request body with the comment
field containing an arbitrary comment. This comment will be saved to the comment
field of the invoice object.
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/mark_as_uncollectible' \
-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 '{
"comment": "An optional comment explaining why the invoice was deemed uncollectible."
}'
Clone an invoice
You can clone an invoice of any status by sending a POST
request to the /receivables/{receivable_id}/clone
endpoint. Cloning an invoice copies the updated entity and counterpart information associated with the invoice. To clone an invoice, send a POST
request to the /receivables/{receivable_id}/clone
endpoint as shown:
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/clone' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
A successful request returns an object with the newly cloned invoice details.
All newly cloned invoices will have a
draft
status regardless of the status of the original invoice they were cloned from. Therefore, all previously updated values related to issuing and paying the original invoice will be reset.
Delete an invoice
Draft invoices can be deleted by calling DELETE /receivables/{receivable_id}
. It's important to note that this action is irreversible, and once deleted, invoices can no longer be accessed.
curl -X DELETE 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
Only invoices in the
draft
status can be deleted successfully. Attempting to delete an invoice with any other status will fail.
Cancel an invoice
Invoices in the "issued" and "overdue" statuses can be canceled if they have not been paid in full yet. For example, an entity may want to cancel an invoice if it was issued by mistake or if some data in the invoice is missing or incorrect. Depending on the entity settings (mentioned below), canceling an invoice can automatically create and issue a credit note for this invoice.
To cancel an invoice, call POST /receivables/{invoice_id}/cancel
:
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/cancel' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
A successful request will return the 204 status code. Additionally, if the entity setting receivable_edit_flow
is "compliant", a new credit note is automatically created and issued for the remaining invoice amount. Note that credit notes are not automatically sent to counterparts, but the entity can send the documents manually.
To find the created credit note, you can call:
GET /receivables?based_on={invoice_id}&limit=1&status=issued
Notes
- Canceled invoices cannot be reissued. If the reason for cancelling was to fix missing or incorrect data in the invoice, the entity will need to create a new invoice with the corrected data.
- An invoice cannot be canceled if a draft credit note exists for this invoice and the entity setting
receivable_edit_flow
is "compliant".- Another way to cancel an invoice is to manually create and issue a credit note for the remaining invoice amount. In this case, the invoice status is changed to "canceled" automatically.
List all invoices
To get a list of all invoices generated by an entity, call GET /receivables?type=invoice
:
curl -X GET 'https://api.sandbox.monite.com/v1/receivables?type=invoice' \
-H 'X-Monite-Version: 2023-06-04' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
You can sort and filter the results by the amount, counterpart name, and other fields. For the full list of available sort and filter parameters, see the description of the GET /receivables
endpoint.
Some examples:
GET /receivables?type=invoice&counterpart_name=Acme%20Inc.
- get all invoices issued to Acme Inc.GET /receivables?type=invoice&amount__gte=15000
- get all invoices where the total amount is €150 or more.GET /receivables?type=invoice&status__in=draft&status__in=issued
- get all draft and issued invoices.GET /receivables?type=invoice&created_at__gte=2022-01-01T00%3A00%3A00
- get all invoices created on or after January 1, 2022.
Retrieve an invoice
To get information about a specific invoice, call GET /receivables/{receivable_id}
and provide the invoice ID.
Updated 23 days ago