> This page is for version v2024-05-25 (default). > For other versions, use one of these documentation indexes: > - v2024-05-25 (default): https://docs.monite.com/v-2024-05-25/llms.txt > - v2024-01-31: https://docs.monite.com/v2024-01-31/llms.txt > - v2023-09-01: https://docs.monite.com/v2023-09-01/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.monite.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server. # Create and send invoices > **Info** > > This page is about outgoing invoices sent by an to its clients. For the accounts payable invoices received by an entity from its vendors, see [Payables](../../accounts-payable/payables/collect). 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. ## ⚠️ Considerations \[#considerations] Monite provides the ability to enable invoice issuers from supported countries to meet legal and tax requirements for issuing valid invoices. To enable invoice issuers outside of supported countries to create invoices, Monite provides default non-customized templates for non-supported countries that meet internationally recognized invoice standards, which can be utilized if the invoice issuer provides the applicable VAT rates via the `tax_rate_value` field in the invoice line item object. For a full list of supported countries, see [Regulatory compliance](../regulatory-compliance/index). ## Prerequisite: Specify the required entity information \[#Prerequisite] To be able to create and issue invoices, an entity must have the following information specified. ### Tax ID and/or VAT ID An invoice needs to specify the tax ID and/or VAT ID of the entity (seller). Depending on an entity's jurisdiction, it may have both tax ID and VAT ID, or only one of them. #### Check if tax ID or VAT ID is required Use the [`GET /receivables/required_fields`](/api/receivables/get-receivables-required-fields) endpoint to check whether invoices from the given entity to a specific counterpart require the tax ID and/or VAT ID of each party. The endpoint takes into account the transaction type (e.g. B2B or B2C) and the countries of each party (i.e. whether it's local or cross-border sales) to determine the required fields for invoice compliance. If the counterpart already exists, use: ``` GET /receivables/required_fields ? counterpart_id = <...> & counterpart_billing_address_id = <...> [ & entity_vat_id_id = <...> ] ``` If you are making this check before creating the counterpart for an invoice, use: ``` GET /receivables/required_fields ? counterpart_country = & counterpart_type = [ & entity_vat_id_id = <...> ] ``` > **Tip** > > If the entity already has a [VAT ID](../../entities/vat-ids), include it in the request parameters. The response indicates whether the `tax_id` and/or VAT ID are required for the current entity and the specified counterpart: ```json {5, 9, 15, 19} { "counterpart": { "tax_id": { "description": "...", "required": false }, "vat_id": { "description": "...", "required": true } }, "entity": { "tax_id": { "description": "...", "required": false }, "vat_id": { "description": "...", "required": true } }, ... } ``` If an entity was initially created without tax and VAT IDs, make sure to update entity information to add these values: * Tax ID is specified by the `tax_id` field in the Entity object. * VAT IDs can be added by using [`POST /entities/{entity_id}/vat_ids`](/api/entity-vat-ids/post-entities-id-vat-ids). For details, see [Manage entity VAT IDs](../../entities/vat-ids). You will need to specify the relevant VAT ID in the `entity_vat_id_id` field when creating an invoice. For more information, see [Entity tax ID and VAT IDs](../../entities/index). ### Bank account An invoice also needs to specify the entity bank account to which the payment should be made. This bank account must be able to accept the currency reflected on the invoice. To learn how to add entity bank accounts, see [Manage bank accounts](../../entities/bank-accounts). You will need to provide the ID of the appropriate bank account in the `entity_bank_account_id` field when creating an invoice. ## Create an invoice \[#create] To create an outgoing invoice, complete the following steps: 1. Create a [counterpart](../../common/counterparts/index) 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. Configure payment reminders and overdue reminders for the invoice. (Optional) 6. Create the invoice. > **Info** > > **Create an invoice based on a quote** > > You can also create an invoice based on an issued quote. For more information, see [Create an invoice based on a quote](../quotes/manage#create-invoice-from-quote). ### 1. Create a counterpart \[#create-counterpart] The counterpart represents the customer purchasing your product or service. It is required for creating an invoice. Learn how to [create counterparts](../../common/counterparts/index#create). ### 2. Create a product \[#create-product] The products or services to be listed in the invoice also must be created in advance. Depending on the entity's country, measure units may be required for products before the invoice can be issued. Learn how to [create products and measure units](../products#create-a-product). > **Info** > > **Product currencies on invoices** > > Currencies of products added as line items on an invoice must always match the invoice's base currency. You can create products in multiple currencies to match the invoice's base currency. For more information, see [Create a product](../products#create-a-product). ### 3. Get VAT rates \[#get-vat-rates] > **Warning** > > **Exception for non-supported countries, US, and Pakistan** > > Invoice issuers in certain non-supported countries, US, and Pakistan, do not need to display applicable VAT rates vis-à-vis their counterparties when creating an invoice. However, Monite enables such invoice issuers to provide the applicable VAT rates directly to the recipient by using the `tax_rate_value` field in the invoice line item object. For a full list of supported countries, see [Regulatory compliance](../regulatory-compliance/countries). 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: ```sh curl -X GET 'https://api.sandbox.monite.com/v1/vat_rates?counterpart_id=0414f...5435' \ -H 'X-Monite-Version: 2024-05-25' \ -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. ```json { "data": [ { "id": "a39a2ec3-765d-4f75-9a17-585a5d22509d", ... "value": 0, "country": "DE" }, { "id": "51cefc6c-9f82-484e-ae6a-a3a89b507bea", ... "value": 700, "country": "DE" }, ... ] } ``` The `GET /vat_rates` endpoint returns all VAT rates applicable to the entity's [VAT IDs](../../entities/vat-ids). If the entity VAT ID is not present, the request will return only a 0% VAT rate for the entity's country in the response. > **Info** > > If a counterpart is exempt from paying VAT, you can provide the reason for exemption via the optional `vat_exemption_rationale` field on the invoice object. For example, depending on the location, counterparts in healthcare and education services may be exempt from paying VATs. You can assign a 0% VAT rate on the invoice line item and provide the reason for exemption via the `vat_exemption_rationale` field. The reason provided will also be displayed on the invoice PDF. Learn more about [VAT rates](../vat-rates). ### 4. Create payment terms \[#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](../../common/payment-terms). ### 5. Create the invoice \[#create-invoice] Once the required counterpart, products, and payment terms are created, you can create the invoice for a given counterpart by calling [`POST /receivables`](/api/receivables/post-receivables) endpoint with the `type` field in the payload set to `invoice`: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/receivables' \ -H 'X-Monite-Version: 2024-05-25' \ -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, "counterpart_billing_address_id": "7482ea513-4689-d630-782b6f0fs3", "entity_vat_id_id": "cb6c1c38-fdae-48f8-8e51-2d50d116b882", "counterpart_vat_id_id": "782b6f0f-0177-475c-b1e4-98dc160a656f", "entity_bank_account_id": "5624cca65c3e-8f18-4021-bdd1-3f548c1b" }' ``` 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](/api/receivables/post-receivables) as necessary. > **Info** > > **Notes** > > * US entities cannot use the `vat_rate_id` on the `line_items` object when creating invoices. US entities must provide custom VAT rate values using the `tax_rate_value` field on the `line_item` object. > * When UK entities create invoices that fall under the Northern Ireland Protocol, the `entity_vat_id_id` field must point to a VAT ID object with `type`=`"eu_vat"`. [Learn how to configure VAT IDs](../../entities/vat-ids#multiple) for UK entities that operate under the NI Protocol. > * If the entity has [invoice payment reminders](payment-reminders) enabled (that is, [entity setting](/api/entities/get-entities-id-settings) `reminder.enabled` is `true`), the invoice payload MUST include `payment_reminder_id`. 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 `due_date` field on the invoice response object. ```json { "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_before_vat": 5000 } ], "total_amount": 5950, "total_vat_amount": 950, ... "memo": null, "issue_date": null, "total_vat_amounts": [ { "id": "479155c3-0995-4689-a3cf-7482ea5132a9", "value": 1900, "amount": 950, } ], "due_date": "2024-06-03", "total_amount_with_credit_notes": 5950, "amount_due": 5950, "amount_paid": 0, "payment_terms": { ... }, "status": "draft", ... } ``` For a complete list of request and response fields, refer to the description of the `POST /receivables` [endpoint](/api/receivables/post-receivables). #### Auto-calculated amounts Monite automatically calculates the subtotal, total, and VAT amounts for the entire invoice and individual line items. These amounts are included in responses from the `/receivables*` endpoints. You can display these amounts in your application and use them in your business logic. * `line_items[i].total_before_vat` - line item amount including the discount but excluding VAT. * `line_items[i].total_after_vat` - line item amount including the discount and VAT. * `subtotal` - invoice subtotal as a sum of line item subtotals. VAT and invoice-level discount are not included, but line item discounts are included. * `subtotal_after_vat` - a sum of `subtotal` and `total_vat_amount`. In other words, it is the invoice subtotal including VAT and line item discounts, but excluding invoice-level discount. * `discounted_subtotal` - invoice subtotal after invoice-level discount. VAT is not included. * `total_vat_amount` - total VAT amount for the entire invoice. * `total_vat_amounts` - a list of VAT rates used in the invoice, along with the calculated total VAT amounts for each rate. * `total_withholding_tax` - if `withholding_tax_rate` is provided, the total withholding tax is calculated as the specified percentage of the `discounted_subtotal`. * `total_amount` - total invoice amount including VAT and all discounts (except [payment term](../../common/payment-terms) discounts). It's the sum of `discounted_subtotal` and `total_vat_amount`, minus `total_deduction_amount` and `total_withholding_tax` (if any). * `total_amount_with_credit_notes` - this is `total_amount` minus the amounts of all credit notes issued for this invoice. The value is updated whenever a new credit note is issued for this invoice. * `total_deduction_amount` - the sum of all deductions that are appplied after VAT (not to be confused with discounts). * `amount_due` - the remaining amount to be paid for this invoice. Initially, it equals the `total_amount_with_credit_notes` value and is automatically adjusted with each payment made towards the invoice. After the invoice is fully paid, the `amount_due` becomes 0. * `amount_paid` - the total amount paid towards an invoice. The initial value starts at 0 and can be continually updated for partially paid invoices. For more information, see [Record payments on an invoice](manage#record-payment). * `amount_to_pay` - this is `amount_due` adjusted to reflect the currently effective discount (if any) defined by the payment terms. Payment terms discounts take effect once the invoice has been issued. If you [create a payment link](../../payments/payment-links) for the invoice, this is the amount displayed on the payment page. > **Info** > > All monetary amounts are specified in [minor currency units](../../references/currencies#minor-units), such as cents or pence. ## Download the invoice as PDF \[#download-pdf] After creating invoices, you can download the invoice as a PDF or send it to the customer via email. Monite automatically generates the PDF version of invoices in the counterpart language and the entity language, and returns links to these files in the `file_url` and `original_file_url` fields of invoice responses: ```json { "type": "invoice", ... // Counterpart's version of a PDF invoice "file_language": "nl", "file_url": "https://bucketname.s3.amazonaws.com//.pdf", ... // Entity's version of a PDF invoice "original_file_language": "en", "original_file_url": "https://bucketname.s3.amazonaws.com//.pdf", ... } ``` > **Info** > > If `file_url` or `original_file_url` is `null`, repeat the request to `GET /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`: ```sh curl -X GET 'https://api.sandbox.monite.com/v1/receivables/411dc6eb...6289b3/pdf_link' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` It returns the following response: ```json { "file_url": "https://bucketname.s3.amazonaws.com//.pdf", "original_file_url": "https://bucketname.s3.amazonaws.com//.pdf" } ``` Here's how the PDF looks like: ![A PDF invoice](/_fern-img/89baf2726b4c171f00523dc0721a355df8e0f834e94287a81d2c472ab215996d.webp) 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). ## Invoice customization \[#customization] Monite allows entities to modify specific entity information on an invoice. This includes providing a different entity logo, website, and contact information on the invoice object. You can only do this after creating the invoice by updating the invoice using the [`PATCH /receivables/{receivable_id}`](./manage#update-an-invoice) endpoint. > **Info** > > Modifying the entity information on the Invoice object only affects the entity information on that specific invoice. The entity's existing or newly created invoices will retain the original entity information. ### PDF localization Monite provides several built-in PDF templates for receivables. The language on the invoice's PDF depends on the language of the invoice's counterpart. If the counterpart language is absent, the invoice's PDF will be created in the entity's language. Updating the invoice's counterpart language or changing the invoice's counterpart to a counterpart with a different language will also update the invoice's PDF translation. For more information, see [PDF localization](../../advanced/pdf-templates#localization). Monite formats delimiters and decimal separators on amounts displayed on the PDFs based on the entity's country. Entities can [change their default template](../../advanced/pdf-templates#default) or customize their chosen templates anytime. For more information, see [PDF templates](../../advanced/pdf-templates). ## Verify the invoice \[#verify] Before a newly created invoice can be issued to a counterpart, certain required information must be present on the invoice. This includes information about the entity, counterpart, line items, and VAT rates. To trigger regulatory checks for an invoice and check that an invoice contains all required information, call `POST /receivables/{receivable_id}/verify`: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dcb...289b3/verify' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' ``` The `errors` object in the response shows all the missing information required on the invoice. If the invoice has all required information filled in, all response fields have the `null` value. The `warnings` object in the response represents possible faulty configurations on the invoice. For example, a mismatch between payment terms and payment reminders: ```json { "errors": { "counterpart": null, "entity": null, "products": null, "receivable": null, "vat_rates": null }, "warnings": { "payment_reminders": "The due date on one or more of the invoice's payment term's tier comes before the scheduled reminder date for the corresponding tier. Review the reminders configuration for the invoice." } } ``` If some of the required invoice fields are missing, the response contains a list of the missing fields. For example, the following response means that the entity tax ID, the counterpart tax ID, and measure unit ID on the invoice's second line item are missing. To make the invoice valid, you will need to update the corresponding entity and counterpart objects and provide their `tax_id`. ```json { "errors": { "counterpart": ["tax_id"], "entity": ["tax_id"], "products": [ { "line_item_number": 2, "missing_fields": ["measure_unit_id"] } ], "receivable": null, "vat_rates": null }, "warnings": { "payment_reminders": null } } ``` ## Send the invoice via email \[#send-via-email] Once a draft invoice has been finalized, you can send it to the counterpart via email. The invoice will be attached as a PDF file to the email. You can also preview the invoice's email before sending it; for more information, see [Preview an invoice's email](manage#preview-invoice-email). To send an invoice, call [`POST /receivables/{receivable_id}/send`](/api/receivables/post-receivables-id-send) and provide the `subject_text` and `body_text`. The language of the email template used is determined by the counterpart's `language`. Aside from the counterpart's default email address, Monite also allows you to provide a list of email addresses to send the invoice using the `recipients` field. If the `recipients` field is not provided, the invoice email is sent only to the counterpart's email address. ```sh curl -X POST 'https://api.sandbox.monite.com/v1/receivables/411dcb...289b3/send' \ -H 'X-Monite-Version: 2024-05-25' \ -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!", "recipients": { "to": ["dana@example.com"], "cc": ["support@example.com", "sales@example.com"], "bcc": ["exec@example.com"] } }' ``` > **Info** > > **Notes** > > * 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](../../advanced/email-templates/manage) and [Variables list](../../advanced/variables#list). Both the subject and body texts can include [variables](../../advanced/variables) as placeholders for invoice-specific and counterpart-specific data. > * You can opt to attach the invoice's PDF to the email sent to the counterpart. To do this, you must update the value of the `mail.attach_documents_as_pdf` field to `true` in your Monite partner settings. For more information, see [Update partner settings](/api/partner-settings/patch-settings). 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. All invoice emails are sent from the `noreply@monite.com` email address by default. You can customize the email domain name—`@exampleCompany.com`— by [configuring a mailbox](../../advanced/mailboxes) for the entity. You can also customize the email sender name and username by updating your Monite partner settings. For more information, see [Update partner settings](/api/partner-settings/patch-settings). A `200 OK` response from `POST /receivables/{receivable_id}/send` means the email was successfully sent from the Monite email server. > **Info** > > **Notes** > > * Sending a `draft` invoice changes its [status](./index) to `issued`, and the `issued_date` field is automatically set to the current date and time. Issued invoices can no longer be edited. > * Invoices in the `uncollectible` status cannot be sent via email. All other statuses can be sent. #### Resend an invoice \[#resend] To resend an already issued invoice, you can call `POST /receivables/{receivable_id}/send` again, optionally with different `subject_text` and `body_text` templates. Monite also automatically sends [payment reminders](payment-reminders) to the counterpart before the invoice due date and each payment term. > **Info** > > Resending an invoice does not change its `status` or `issued_date`. ## See also * [E-invoicing](../../e-invoicing/accounts-receivable) - learn how to send invoices through an e-invoicing network.