HomeGuidesRecipesAPI ExplorerForumSandboxSupport

Manage invoices

Learn how to manage invoices and change invoice statuses.

Suggest Edits

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 and overdue 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, and overdue statuses. Issued invoices are moved to the partially_paid status, whereas invoices in the partially_paid and overdue 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's amount_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, and partially_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