Create and send invoices

📘

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:

1. Create a counterpart that represents the customer.
2. Create one or more products to be listed in the invoice.
3. 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.
4. Create payment terms for the invoice.
5. Create the invoice.
6. Download the invoice as PDF. (Optional)
7. 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 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 response contains the id assigned to the created invoice, along with the calculated subtotal (total_amount), VAT (total_vat_amount), and other information. The total price can be calculated as a sum of total_amount and total_vat_amount. 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",
  "total_amount": 5000,
  "line_items": [
    {
      "quantity": 5,
      "product": {
        ...
      }
    }
  ],
  "total_vat_amount": "950",
  ...
  "memo": null,
  "issue_date": null,
  "total_amount_with_credit_notes": 5000,
  "payment_terms": {
    ...
  },
  "status": "draft",
  "payment_reminder_id": null,
  "recurrence_id": null
}

📘

For the complete list of parameters and their descriptions, refer to the POST /receivables endpoint.

6. Download the invoice as PDF

After creating the invoice, you can generate a PDF version of this invoice that can be emailed to the counterpart. To generate a PDF, call GET /receivables/{receivable_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' 

The response contains a string with the link to download the generated PDF file:

"https://<subdomain>.s3.amazonaws.com/<unique_id>"

This link is also saved to the file_url property of the Receivable object that corresponds to this invoice.

Here's how the PDF looks like:

📘

The PDF file is not 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). To re-generate the PDF file after the changes, call GET /receivables/{receivable_id}/pdf_link again.

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 {company_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:

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 to issued, and the issued_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 or issued_date.

Monite also automatically sends payment reminder notifications to the counterpart one day before each payment target.

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.