Create and send quotes
Learn how to create a quote and send a formal offer.
Overview
A quote is a formal offer that details how much a product or service will cost. Quotes are similar to invoices. The difference is that a quote is given to a potential customer before they decide to purchase, whereas an invoice is issued after the delivery of products or services to the customer.
Quotes have an expiry date by which the quote should be accepted or declined.
Prerequisites
To be able to create quotes, an entity must have either the tax_id
or vat_id
or both specified. If an entity was initially created without tax_id
and vat_id
, update the entity and add these values.
Create a quote
A typical quote workflow includes the following steps:
- Create a counterpart that represents the customer.
- Create one or more products to be listed in the quote.
- 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 quote.
- Create the quote.
1. Create a counterpart
The counterpart represents the customer (organization or individual) purchasing your products or services.
Learn how to create counterparts.
2. Create a product
The products to be listed in the quote must also be created in advance. Depending on the entity’s country, measure units may be required for products before the quote can be issued.
Learn how to create products and measure units.
As an example, here is a representation of a sample t-shirt product:
The associated measure unit is “pieces” (items):
3. Get VAT rates
Exception for non-supported countries, US, and Pakistan
Quote issuers in certain non-supported countries, US, and Pakistan, do not need to retrieve applicable VAT rates vis-à-vis their counterparties when creating a quote. However, Monite enables such quote issuers to provide the applicable VAT rates directly to the recipient by using the tax_rate_value
field in the quote line item object. For a full list of supported countries, see Supported sountries.
A quote 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:
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.
The GET /vat_rates
endpoint returns all VAT rates applicable to the entity’s 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.
If a counterpart is exempt from paying VAT, you can provide the reason for exemption via the optional vat_exemption_rationale
field on the quote 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 quote line item and provide the reason for exemption via the vat_exemption_rationale
field. The reason provided will also be displayed on the quote’s PDF.
4. Create the quote
Once the counterpart and products have been created, you can create the quote for a given counterpart by calling POST /receivables
with the type
field in the request body set to quote
.
The request body must contain the counterpart ID, line items (products, their quantities, and VAT rates), and quote expiration date, among other information. The subtotal, total, and VAT amount are not specified in the request - they will be calculated automatically based on the product price, quantity, and VAT rates.
The example below creates a quote for five items of a produc
Notes
- US entities cannot use the
vat_rate_id
on theline_items
object when creating quotes. US entities must provide custom VAT rate values using thetax_rate_value
field on theline_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 withtype="eu_vat"
. Learn how to configure VAT IDs for UK entities that operate under the NI Protocol.
The successful 201 Created
response contains the id
assigned to the created quote, along with the calculated total (total_amount
), subtotal (subtotal
), VAT (total_vat_amount
), and other information.
For the complete list of quote data fields and their descriptions, refer to the /receivables
endpoint.
Auto-calculated amounts
Monite automatically calculates the subtotal, total, and VAT amounts for the entire quote 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.subtotal
- quote subtotal as a sum of line item subtotals. VAT and quote-level discounts are not included, but line-item discounts are included.discounted_subtotal
- quote subtotal after the quote-level discount. VAT is not included.total_vat_amount
- total VAT amount for the entire quote.total_vat_amounts
- a list of VAT rates used in the document, along with the calculated total VAT amounts for each rate.total_withholding_tax
- ifwithholding_tax_rate
is provided, the total withholding tax is calculated as the specified percentage of thediscounted_subtotal
.total_amount
- total quote amount after all discounts, VAT, and other taxes. It’s the sum ofdiscounted_subtotal
andtotal_vat_amount
, minustotal_withholding_tax
(if any).
All monetary amounts are specified in minor currency units, such as cents or pence.
After creating invoices, you can download the invoice as a PDF or send it to the customer via email.
Download the quote as PDF
Monite automatically generates PDFs for quotes and provides several built-in PDF templates. The counterpart’s PDF is returned in the file_url
field in the quote’s response:
The file_url
field returns the quote’s PDF in the counterpart’s language—file_language
. Monite also provides a copy of the quote’s PDF in the entity’s language—original_file_language
. This can be accessed using the original_file_url
field on the quote object. The PDF’s language on the original_file_url
field depends on the entity’s defined language in the entity settings.
If file_url
or original_file_url
field is returned as null
, retry the request to GET /receivables/{quote_id}
after some time.
You can also retrieve only the quote’s entity and counterpart PDFs by calling GET /receivables/{quote_id}/pdf_link
:
It returns the following response:
Here’s how the PDF looks like:
The PDF file is updated automatically if the quote is changed (for example, if new line items are added to a draft quote, or if the counterpart address is changed).
PDF localization
Monite provides several built-in PDF templates for quotes. The language on the quote’s PDF depends on the language of the quote’s counterpart. If the counterpart language is absent, the quote’s PDF will be created in the entity’s language. Updating the quote’s counterpart’s language or changing the quote’s counterpart to a counterpart with a different language will also update the quote’s PDF translation. For more information, see PDF 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 or customize their chosen templates anytime. For more information, see PDF templates.
Verify the quote
Before a newly created quote can be issued to a counterpart, certain required information must be present on the quote. This includes information about the entity, counterpart, line items, and VAT rates on the quote. To trigger regulatory checks for a quote and check that a quote contains all required information, send a POST
request to the receivables/{receivable_id}/verify
endpoint as shown:
A successful response returns an object containing the missing information required on the quote. The errors
object in the response shows all the missing information required on the quote. If the quote has all required information filled in, all response fields have the null
value. For example, the following example shows the response for a quote without entity tax ID and counterpart tax ID information.
Send the quote via email
Once a draft quote has been finalized, you can send it to the counterpart via email. The quote will be attached as a PDF file to the email. You can also preview the quote’s email before sending it; for more information, see Preview a quote’s email.
To send a quote, call POST /receivables/{receivable_id}/send
and provide the subject_text
and body_text
. The language
field determines the language of the email template used to send the quote. If a value is not provided, it defaults to en
.
Aside from the counterpart’s default email address, Monite also allows you to provide a list of email addresses to which you can send the invoice using the recipients
field. If the recipients
field is not provided, the quote email is sent only to the counterpart’s email address.
Notes:
- The values of the
subject_text
andbody_text
fields will replace thesubject_text
andbody_template
variables if they were used when creating your custom templates. For more information, see Create and manage email templates and Variables list. Both the subject and body texts can include variables as placeholders for quote-specific and counterpart-specific data. - You can also opt to attach the quote’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 totrue
in your partner settings. For more information, see Update partner settings.
The To
email address is taken from the Counterpart
object associated with the quote. This address is also returned in the counterpart_contact.email
field of the Receivable
object that represents the quote.
All quote 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 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.
A 200 OK
response from POST /receivables/{quote_id}/send
means the email was successfully sent from the Monite email server.
Notes
- Sending a
draft
quote changes its status toissued
. Issued quotes can no longer be edited. - Only quotes in the
draft
,issued
, andaccepted
statuses can be sent via email. Attempting to send a quote in thedeleted
,expired
, ordeclined
status will return an error.
Resend the quote
To resend an already issued quote, you can call POST /receivables/{quote_id}/send
again, optionally with different subject_text
and body_text
templates.
Resending a quote does not change its status
.