Manage invoices

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.

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3' \
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
       "invoice": {
8
         "currency": "USD",
9
         "counterpart_id": "782b6f0f-0177-475c-b1e4-98dc160a656f",
10
         "counterpart_billing_address_id": "796d1f1d-f345-4888-849c-6cbcfbd39982",
11
         "payment_terms_id": "f7c577590-2680-462a-a2b4-7c564f65449d",
12
         "entity_vat_id_id": "96d1f1df7b7-462a-4888-98dc160a656f6d",
13
         "entity_bank_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
14
         "entity": {
15
            "logo": "https://new-entity-logo.com/icon-192x192.png",
16
            "email": "example@email.com"
17
          }
18
        }
19
     }'

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.

1
curl -X PUT 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/line_items' \
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
       "data": [
8
         {
9
           "quantity": 2,
10
           "product_id": "fb2cc78f-3396-42e1-a69f-04b1931e4a84",
11
           "vat_rate_id": "8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
12
           "discount": {
13
             "type": "amount",
14
             "amount": 0
15
           }
16
         },
17
         {
18
           "quantity": 4,
19
           "product_id": "d1bc6df0-1571-457c-8407-7cf42aceb5dd",
20
           "vat_rate_id":"8d4c2c10-f7d7-4d7c-a1f5-5f3a9d56371e",
21
           "discount": {
22
             "type":"amount",
23
             "amount":0
24
           }
25
         }
26
       ]
27
     }'

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.

1
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/preview' \
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
       "subject_text": "New invoice #{invoice_number}",
8
       "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!",
9
       "language": "en"
10
     }

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.

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.

1
curl -X POST 'https://api.sandbox.monite.com/v1/payment_links' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: 7884aa8a-34c7-4c78-87d2-4d1c6b8c6936' \
4
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "object": {
8
         "type": "receivable",
9
         "id": "411dc6eb-3bf4-465b-8dfe-f6b5ec6289b3"
10
       },
11
       "recipient": {
12
         "type": "entity",
13
         "id": "7884aa8a-34c7-4c78-87d2-4d1c6b8c6936"
14
       },
15
       "payment_methods": [
16
         "card", "sepa_debit", "sepa_credit"
17
       ],
18
       "return_url": "https://example.com/where-to-redirect-after-payment"
19
     }'

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.

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:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3' \
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
       "invoice": {
8
         "payment_page_url": "https://pay.example.com/497f374d-39b6-4506-bad1-689ed0fc5627"
9
        }
10
      }'

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, call POST /payment_records:

1
curl -X POST 'https://api.sandbox.monite.com/v1/payment_records' \
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
       "payment_intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
8
       "object": {
9
         "id": "1877d46f-2f16-484d-a44a-b537b30c2f34",
10
         "type": "receivable"
11
       },
12
       "paid_at": "2024-08-26T11:59:54.789Z",
13
       "amount": 500,
14
       "currency": "EUR"
15
     }'

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.

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 body containing the following fields:

• paid_at - Date and time of the payment. This value will be saved to the paid_at field of the invoice object. If omitted, it defaults to the date and time of the /mark_as_paid request.
• comment - Additional notes about the paid invoice. For example, which payment method was used. This comment will be saved to the comment field of the invoice object.

1
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/mark_as_paid' \
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
       "paid_at": "2024-08-26T00:00:00Z",
8
       "comment": "Paid on 2024/08/26 by a wire transfer."
9
     }'

Alternatively, you can use POST /payment_records to record a full payment for the invoice, as shown above. The main differences from /mark_as_paid are that you need to provide the payment amount in the request and that a payment record will be created to reflect the payment. To get the amount due for use in the /payment_record request, you can use the amount_to_pay field of the invoice object.

Customize invoice number

Invoice numbers are customized in the entity settings. Customizing an invoice number will affect all invoices subsequently issued by the entity. The document_id on previously issued invoices will not be affected by this change. To customize invoice numbering, make a PATCH request to the /entities/{entity_id}/settings endpoint as shown:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/entities/5b031d0c...44df31ebf0db/settings' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN' \
4
     -H 'Content-Type: application/json' \
5
     -d '{
6
      "document_ids": {
7
        "include_date": true,
8
        "min_digits": 3,
9
        "document_type_prefix": {
10
          "invoice": "INV",
11
        },
12
        "next_number": {
13
          "invoice": "20",
14
         }
15
       }
16
     }'

For more information on customizing invoice numbering, see Document number customization.

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.

1
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/mark_as_uncollectible' \
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
       "comment": "An optional comment explaining why the invoice was deemed uncollectible."
8
     }'

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.

1
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/clone' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

A successful request returns an object with the newly cloned invoice details.

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.

1
curl -X DELETE 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/cancel' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -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:

1
GET /receivables?based_on={invoice_id}&limit=1&status=issued

List all invoices

To get a list of all invoices generated by an entity, call GET /receivables?type=invoice:

1
curl -X GET 'https://api.sandbox.monite.com/v1/receivables?type=invoice' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -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=2024-01-01T00%3A00%3A00 - get all invoices created on or after January 1, 2024.

Retrieve an invoice

To get information about a specific invoice, call GET /receivables/{receivable_id} and provide the invoice ID.