HomeGuidesRecipesAPI ExplorerForumSupport
Partner Portal
Partner Portal

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: 2024-01-31' \
     -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",
         "counterpart_billing_address_id": "796d1f1d-f345-4888-849c-6cbcfbd39982",
         "payment_terms_id": "f7c577590-2680-462a-a2b4-7c564f65449d",
         "entity_vat_id_id": "96d1f1df7b7-462a-4888-98dc160a656f6d",
         "entity_bank_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      }'

When updating an invoice's counterpart, you must also provide the new counterpart's counterpart_billing_address_id in the request object to update the counterpart_billing_address object.

Update invoice line items

You can modify an invoice's line items to add, remove, or update the products and product details on the invoice. To update an invoice's line items, send a PUT request to the /receivables/{receivable_id}/line_items endpoint. In the request body, use the data field to specify an array of the invoice's new line items.

curl -X PUT 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/line_items' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "data": [
         {
           "quantity": 2,
           "product_id": "fb2cc78f-3396-42e1-a69f-04b1931e4a84",
           "vat_rate_id": "8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
           "discount": {
             "type": "amount",
             "amount": 0
           }
         },
         {
           "quantity": 4,
           "product_id": "d1bc6df0-1571-457c-8407-7cf42aceb5dd",
           "vat_rate_id":"8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
           "discount": {
             "type":"amount",
             "amount":0
           }
         }
       ]
     }'

A successful request overwrites the invoice's existing line items and replaces them with the newly defined array of line item objects.

Preview an invoice's email

After creating an invoice, you can preview an invoice's email before issuing it. This step can be used when troubleshooting email template layouts for an invoice to ensure that the final presentation aligns with your template design.

To preview an invoice's template, send a POST request to the /receivables/{receivable_id}/preview endpoint. The language field determines the language of the email template used to preview the invoice. If a value is not provided, it defaults to en.

curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/preview' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "subject_text": "New invoice #{invoice_number}",
       "body_text": "Dear {contact_name},\n\nThank you for your business!\nPlease pay the balance of {amount_due} (invoice #{invoice_number}) by {due_date}.\n\nFor any questions or concerns, please don’t hesitate to get in touch with us at {entity_email}. We look forward to serving you again and wish you all the best!",
       "language": "en"
     }

The values of the subject_text and body_text fields will replace the subject_text and body_template variables if they were used when creating your custom templates. For more information, see Create and manage email templates and Variables list.

📘

Only invoices in the draft, issued, overdue, and partially_paid statuses can be previewed. Attempting to preview an invoice in any other status will return a 409 Conflict error.

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 assigns a payment page dedicated to the specific invoice and updates the invoice's QR code destination to point to that payment page.

The process of connecting payment links to an invoice varies slightly between using Monite's payment links or your custom payment links. However, the payment_page_url field on the invoice object determines the payment link embedded in the invoice PDF's QR code.

Using Monite's payment links

Before using Monite's payment link, you must first create a payment link connected to the invoice. To connect a payment link to an invoice, send a POST request to the /payment_links endpoint.

In the request body, include the object.id field representing the invoice 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: 2024-01-31' \
     -H 'X-Monite-Entity-Id: 7884aa8a-34c7-4c78-87d2-4d1c6b8c6936' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "object": {
         "type": "receivable",
         "id": "411dc6eb-3bf4-465b-8dfe-f6b5ec6289b3"
       },
       "recipient": {
         "type": "entity", 
         "id": "7884aa8a-34c7-4c78-87d2-4d1c6b8c6936"
       },
       "payment_methods": [
         "card", "sepa_debit", "sepa_credit"
       ],
       "return_url": "https://monite.com"
     }'

A successful request generates and returns the payment link for the invoice in the object.id field. The payment link generated can be found on the payment_page_url field of the invoice object.

📘

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 throw an error.

Using external payment links

If you use custom payment rails, you can connect an external payment link to an invoice. To do this, provide your custom invoice payment link in the payment_page_url field when creating or updating an invoice:

curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "invoice": {
         "payment_page_url": "https://pay.example.com/497f374d-39b6-4506-bad1-689ed0fc5627"
        }
      }'

📘

When using external payment links, the payment_page_url field can only be updated for invoices in the draft status. Attempting to connect an external payment link after issuing an invoice will throw an error.

Record payments on an invoice

When using external payment rails, you must manually send all invoice payment information to Monite. This can be either one complete or multiple partial payments. To send information about a payment, make a POST request to the payment_records endpoint as shown:

curl -X POST 'https://api.sandbox.monite.com/v1/payment_records' \
     -H 'X-Monite-Version: 2024-01-31' \
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "entity_user_id": "2724e6bf-17b8-4462-b2ed-7d3e16c4a133",
       "payment_intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
       "object": {
         "id": "1877d46f-2f16-484d-a44a-b537b30c2f34",
         "type": "receivable"
       },
       "paid_at": "2023-10-16T11:59:54.789Z",
       "amount": 500,
       "currency": "EUR"
     }'

A successful request contains details of the payment record created and includes details of the invoice's updated status. Monite automatically reconciles and transitions the invoice to the appropriate status. For more information, see Create a payment record and Invoice reconciliation.

📘

Notes

  • This endpoint can be used for invoices in the issued, partially_paid, and overdue statuses.
  • The amount field must always be less than or equal to the current value of the invoice's amount_due 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: 2024-01-31' \
     -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."
     }'

After marking an invoice as paid, you can also create a payment record for the invoice to keep track of the payment history. For more information, see Payment records.

📘

  • Only invoices in the issued, overdue, and partially_paid statuses can be marked paid.
  • A successful request to the endpoint returns a 200 OK response. Attempting to call this endpoint on an invoice in paid status will have no effect on the invoice; all texts in the comment field will also be ignored.

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: 2024-01-31' \
     -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.

curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/clone' \
     -H 'X-Monite-Version: 2024-01-31' \
     -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: 2024-01-31' \
     -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: 2024-01-31' \
     -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: 2024-01-31' \
     -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 17 days ago