Recurring invoices
Learn how to create and manage recurring invoices in Monite.
Overview
With Monite, you can set up monthly recurring invoices to bill an entity’s customers the same amount every month. This is useful, for example, when implementing subscriptions or monthly service bills.
Recurring invoices can be issued on the first or last day of the month. They can be configured to be automatically sent to the predefined recipients.
Create a recurring invoice
1. Create a draft invoice
Start by creating the base invoice that will be used as the template for recurring invoices. You will need the invoice id
for use in subsequent API calls. Keep this invoice in the draft
status.
Verify the invoice data to make sure the invoice can be issued successfully.
Each invoice can have only one recurrence schedule associated with it.
2. Set up the recurrence
Next, configure the recurrence schedule for the base invoice. Call POST /recurrences
and specify the base invoice ID, start month and year, end month and year, and the day of month (first or last) on which the recurring invoices will be issued.
To enable automatic invoice sending, also provide the recipients
list and the subject_text
and body_text
for the email message.
Notes:
-
Months -
start_month
andend_month
- are represented numerically, with 1 for January and 12 for December. -
end_month
andend_year
are required for the recurrence schedule. Currently, invoices cannot be infinitely recurring. However, you can extend a recurrence when it is reaching its end date. -
The first recurring invoice will be issued on the next matching date that follows the start date or the current date depending on whichever one comes later.
For example, if the current date is September 8 and you create a recurrence with September as the
start_month
andday_of_month
= “first_day”, the first recurring invoice will be issued on October 1. No invoice will be issued in September because September 1 has already passed.
When a recurrence schedule is created, the status of the base invoice is changed from "draft"
to "recurring"
. Monite also calculates the scheduled issue dates for all instances of the recurring invoice, and returns these dates in the iterations
list in the response from POST /recurrences
:
The issued_invoice_id
fields in the iterations list have the null
value because the instances of the recurring invoice will be created on their scheduled issue dates. The issued_invoice_id
values will be automatically generated and populated on each issue date.
Auto-sending of recurring invoices
Monite automatically sends recurring invoices to recipients if the recurrence configuration includes the following values:
subject_text
- email subject text.body_text
- the text inserted in the email body. If you use custom email templates, this text substitutes the{{body_template}}
variable in thereceivables_invoice
email template.recipients
- the list of invoice recipients (To, CC, BCC).
recipients
can be omitted if the base invoice has the counterpart contact email specified in the counterpart_contact.email
field.
If both the recurrence’s recipients
and the invoice’s counterpart_contact.email
are defined, recurring invoices will be sent to all of these email addresses.
Disable auto-sending
To disable automatic sending of a recurring invoice, call PATCH /recurrences/{recurrence_id}
and set either subject_text
or body_text
or both to null
. Store the old values somewhere in case you need to undo the change.
You can still send recurring invoice instances on demand by calling POST /receivables/{invoice_id}/send
or through other means.
How recurring invoices are generated
When a recurring invoice is due to be issued, Monite creates a copy of the base invoice with the following additional values:
based_on
- set to the ID of the base invoice.document_id
- an auto-generated invoice document number based on the entity’s document customization settings.issue_date
- set to the current date.status
- starts as “draft” but then immediately changed to “issued”.
The invoice due date is calculated automatically based on the payment terms of the base invoice, and is returned in the due_date
field on the invoice response object. For example, if the issue date is 2024-08-01 and the payment terms are Net 10, the due_date
is set to 2024-08-11.
The ID of the new invoice is saved to the iterations[].issued_invoice_id
field in the Recurrence
object.
Monite then issues this invoice and, if automatic sending is enabled, sends it to the specified recipients.
The status of the corresponding recurrence iteration is set to one of the following:
"completed"
- the invoice was successfully issued and, optionally, sent to the recipients."send_failed"
- the invoice was issued but could not be sent to the recipients. You can callGET /receivables/{invoice_id}/mails
to check for email sending errors and then resend this invoice."issue_failed"
- the invoice cound not be issued and remains in thedraft
status. Normally this should never happen. You can verify the invoice data to see if there are any errors and then re-issue the invoice. If the base invoice’s data is no longer valid or sufficient, you will need to recreate both the base invoice and the recurrence configuration.
interations[].status
) in the recurrence configuration.The current_iteration
in the recurrence configuration is then incremented to reflect the next pending invoice.
The response from GET /recurrence/{recurrence_id}
will then look like this:
If the created invoice is the last one according to the schedule, the recurrence status is changed from "active"
to "completed"
to indicate that no future invoices will be created:
Manage recurring invoices
View all recurring invoices
Use GET /recurrences
to get a list of base invoice IDs and their recurrence schedule.
The invoice_id
fields in the response specify the base invoice IDs, and the iterations[i].issued_invoice_id
fields contain the IDs of the existing recurring invoices that have been generated from the base invoices:
You can then use GET /receivable/{receivable_id}
to fetch the details for a specific invoice ID, such as the total amount, line items, and so on.
Update the invoice details
Once a recurring invoice has been configured, the invoice details (such as line items) cannot be changed. If you need to update the invoice details, you must cancel the current recurring invoice and create a new one.
Change the end date
You can change the end date of a recurrence schedule to a later or earlier date.
To do this, send the new end_month
and/or end_year
in a PATCH /recurrences/{recurrence_id}
request:
The response will reflect the updated pending iterations. If the end date has been extended, additional iterations are added. If the end date has been moved ealier, excess pending iterations are removed.
Change the invoice issue day
You can change the day of the month on which the recurring invoices will be issued. Currently, it can be either the first or last day of the month. Changing the day affects the issue date of future invoices only, it does not affect already issued invoices.
The response will reflect the new scheduled issue_at
dates for the future iterations
of the recurring invoice.
You can change day_of_month
together with end_month
and end_year
in the same PATCH request.
Changing day_of_month
from “last_day” to “first_day” for an active recurring invoice usually results in no iteration in the current month. This can happen even if you make the change on the first day of a month.
Example: Consider a recurring invoice series that started in June and is issued on the last day of a month. On August 5, the day_of_month
is changed from “last_day” to “first_day”. As a result, no invoice will be issued in August - because the first day of August has already passed. The next invoice will be issued on September 1.
Cancel a recurring invoice
You may want to cancel a recurring invoice, for example, if an entity’s customer cancels their order or subscription. To do this, call POST /recurrences/{recurrence_id}/cancel
:
This prevents future invoices from being generated, but existing issued invoices are not affected. The status
of the recurrence schedule and its future invoices in the iterations
array becomes "canceled"
.
Canceled recurring invoices cannot be reactivated or otherwise updated. The invoice and its recurrence schedule will have to be recreated anew.