Create and send invoices
Learn how to create an invoice to collect payment.
This page is about outgoing invoices sent by an entity to its clients. For the accounts payable invoices received by an entity from its vendors, see Payables.
Overview
An invoice is a document given to the buyer by the seller to collect payment. It includes the cost of the products purchased or services rendered to the buyer.
Invoices serve as legal records if they contain the names of the seller and client, the description and price of goods or services, and the payment terms.
Create an invoice
To create an outgoing invoice, complete the following steps:
- Create a counterpart that represents the customer.
- Create one or more products to be listed in the invoice.
- Get the applicable VAT rates based on the entity's country and the counterpart's country, and choose the rates for the products that will be listed in the invoice.
- Create payment terms for the invoice.
- Create the invoice.
- Download the invoice as PDF. (Optional)
- Send the invoice via email.
1. Create a counterpart
The counterpart represents the customer purchasing your product or service. It is required for creating an invoice.
Learn how to create counterparts.
2. Create a product
The products or services to be listed in the invoice also must be created in advance, as well as their respective measure units.
Learn how to create products and measure units.
3. Get VAT rates
An invoice must specify VAT rates for its line items, even if the VAT is 0%. You can call GET /vat_rates?counterpart_id={id}
to get the possible VAT rates for sales to the given counterpart:
curl 'https://api.sandbox.monite.com/v1/vat_rates?counterpart_id=0414f...5435' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
The response includes the possible VAT rates (as a percentage multiplied by 100) and their IDs. Store the IDs somewhere as you will need them later.
{
"data": [
{
"id": "a39a2ec3-765d-4f75-9a17-585a5d22509d",
...
"value": 0,
"country": "DE"
},
{
"id": "51cefc6c-9f82-484e-ae6a-a3a89b507bea",
...
"value": 700,
"country": "DE"
},
...
]
}
Learn more about VAT rates.
4. Create payment terms
Payment terms define when the invoice is due to be paid. A common payment term is Net 30, which means the full payment is expected within 30 days. Payment terms can also include early payment discounts to encourage customers to pay upfront.
Learn how to create payment terms.
5. Create the invoice
Once the required counterpart, products, and payment terms are created, you can create the invoice for a given counterpart by calling POST /receivables
:
curl -X POST 'https://api.sandbox.monite.com/v1/receivables' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"type": "invoice",
"currency": "EUR",
"counterpart_id": "0414f84c-b039-4203-b09b-e42b49245435",
"line_items": [
{
"quantity": 1,
"product_id": "8755c86a-d630-4920-b6fd-fd2917d87dfb",
"vat_rate_id": "479155c3-0995-4689-a3cf-7482ea5132a9"
}
],
"payment_terms_id": "e2cbbb5f-15e6-4b22-a942-8f51b7a81118",
"vat_exempt": false,
"entity_bank_account": {
"iban": "9128309180391",
"bic": "18239012",
"bank_name": "Omega Bank"
}
}'
The request above is a minimal example. The request body can also include many other details about the invoice, such as a custom memo
note, fulfillment_date
(if different from the invoice date), discount
, and other fields as necessary.
The response contains the id
assigned to the created invoice, along with the calculated total (total_amount
), subtotal (subtotal
), VAT (total_vat_amount
), and other information. The invoice's due date is automatically calculated based on the creation date and payment terms, and is returned in the payment_terms.term_final.end_date
property.
{
"type": "invoice",
"id": "411dcb25-ec2c-49fc-bb2d-a72adac289b3",
"created_at": "2022-09-08T11:45:39.048015+00:00",
"updated_at": "2022-09-08T11:45:39.066711+00:00",
"document_id": null,
"currency": "EUR",
"subtotal": 5000,
"line_items": [
{
"quantity": 5,
"product": {
...
}
}
],
"total_amount": 5950,
"total_vat_amount": 950,
...
"memo": null,
"issue_date": null,
"total_amount_with_credit_notes": 5000,
"payment_terms": {
...
},
"status": "draft",
...
}
For a complete list of request and response fields, refer to the description of the
POST /receivables
endpoint.
6. Download the invoice as PDF
Monite automatically generates the PDF version of invoices. The PDF file details - URL, file size, MD5 hash, and other information - are returned in the file
field of invoice responses:
{
"type": "invoice",
...
"file": {
...
"md5": "31d1a2dd1ad3dfc39be849d70a68dac0",
"url": "https://bucketname.s3.amazonaws.com/12345/67890.pdf",
"size": 24381,
...
},
...
}
If
file
is returned asnull
, repeat the request toGET /receivables/{invoice_id}
after some time.
If you need just the PDF file link without the full invoice details, call GET /receivables/{invoice_id}/pdf_link
:
curl 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/pdf_link' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
It returns the following response:
{
"file_url": "https://bucketname.s3.amazonaws.com/12345/67890.pdf"
}
Here's how the PDF looks like:
The PDF file is updated automatically if the invoice is changed (for example, if new line items are added to a draft invoice, or if the counterpart address is changed).
Customize the PDF file
Monite provides several built-in PDF templates for receivables. The preferred template can be set in the entity settings.
7. Send the invoice via email
Once a draft invoice has been prepared, you can send it to the customer via email. To do this, call POST /receivables/{receivable_id}/send
and provide the email subject and body templates. The invoice will be attached as a PDF file to the email.
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dcb...289b3/send' \
-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!"
}'
The To
email address is taken from the Counterpart
object associated with the invoice. This address is also returned in the counterpart_contact.email
field of the Receivable
object that represents the invoice.
The From
email address is [email protected]<entity_name>.monite.com
(currently not customizable).
The {variables}
in the email content will be substituted with the corresponding values from the invoice data and counterpart data. The supported variables are:
Variable | Description |
---|---|
{amount_due} | The invoice subtotal (without VAT) formatted with the currency code. For example, 50.00 € . See also {total_value} . |
{company_email} | The email address of the counterpart. |
{company_name} | The counterpart name (either the company name or an individual's name). |
{contact_email} | The email address of the counterpart's default contact. If no contacts are defined, the counterpart's email address is used instead. Note: This variable exists only if the counterpart is an organization. |
{contact_name} | The name of the counterpart's default contact. If no contacts are defined, the counterpart name is used instead. Note: This variable exists only if the counterpart is an organization. |
{due_date} | The invoice due date, as returned by the payment_terms.term_final.end_date field of the Receivable object. |
{entity_email} | The email address of the entity that created the invoice. |
{entity_name} | The name of the entity that created the quote. |
{fulfilled_date} | Unused. Reserved for future use. |
{invoice_link} | A link to the PDF version of the invoice, as returned by the file_url property of the Receivable object. |
{invoice_number} | The invoice number, as returned by the document_id property of the Receivable object. |
{issue_date} | The date when the invoice was issued. |
{payment_link} | A secure payment link that the counterpart can use to pay the invoice. |
{total_value} | The invoice subtotal (without VAT), formatted with cents but without the currency sign. For example, 50.00 . See also {amount_due} . |
A 200 OK
response from POST /receivables/{receivable_id}/send
means the email was successfully sent from the Monite email server.
Sending an invoice changes its status from
draft
toissued
, and theissued_date
field is automatically set to the current date and time. Issued invoices can no longer be edited.
Resend an invoice
To resend an already issued invoice, you can call POST /receivables/{receivable_id}/send
again, optionally with different subject_text
and body_text
templates.
Resending an invoice does not change its
status
orissued_date
.
Monite also automatically sends payment reminder notifications to the counterpart one day before each payment target.
Further actions
Mark the invoice as partially paid
If the customer paid the invoice partially, you can move the invoice to the partially_paid
status and update the remaining amount_due
. To do this, call POST /receivables/{receivable_id}/mark_as_partially_paid
with the request body containing the new amount_due
(remaining amount to be paid, in minor units) and an optional comment
explaining how the payment was made.
amount_due
must be greater than 0 and less than the total invoice amount specified bytotal_amount_with_credit_notes
.- The specified
comment
(if any) will be saved to the invoice'scomment
field and overwrite any previously existingcomment
.
curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/mark_as_partially_paid' \
-H 'X-Monite-Entity-Id: ENTITY_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"amount_due": 1950,
"comment": "Payment of 40 EUR was received on 2022/10/25 by a wire transfer."
}'
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.
- You can call
POST /receivables/{receivable_id}/mark_as_partially_paid
multiple times for the same invoice to reflect multiple partial payments.- To set the
amount_due
to 0, callPOST /receivables/{invoice_id}/mark_as_paid
instead to mark the invoice as fully paid (see below).amount_due
can be not only decreased but also increased to reflect reversed payments and chargebacks.
Mark the invoice as paid
If the counterpart has paid the invoice in full, you can mark the 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 explains 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-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 the invoice as uncollectible
If the 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-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."
}'
List all invoices
To get a list of all invoices generated by an entity, call GET /receivables?type=invoice
:
curl 'https://api.sandbox.monite.com/v1/receivables?type=invoice' \
-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 21 days ago