Recurring invoices

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 created on the first or last day of the month. Invoices can be created as drafts or configured to be automatically sent to the predefined recipients.

Create a recurring invoice

1. Create a draft invoice template

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.

2. Set up the recurrence

Next, configure the recurrence schedule for the base invoice. To do this, call POST /recurrences and specify the start and end dates and other settings. For a list of available settings, see Recurring invoice configuration.

1
curl -X POST 'https://api.sandbox.monite.com/v1/recurrences' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "invoice_id": "8beb7faa-6851-44c8-9fb9-24a94ca30343",
8
9
       "start_month": 8,
10
       "start_year": 2024,
11
       "end_month": 10,
12
       "end_year": 2024,
13
       "day_of_month": "first_day",
14
15
       "automation_level": "issue_and_send",
16
17
       "recipients": {
18
         "to": ["customer@example.org"],
19
         "cc": ["support@entity.example.com", "sales@entity.example.com"],
20
         "bcc": ["exec@entity.example.com"]
21
       },
22
       "subject_text": "New invoice #{invoice_number}",
23
       "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!"
24
     }'

After a recurrence schedule is created, the status of the base invoice is changed from draft to recurring.

Monite also calculates the scheduled creation dates for all instances of the recurring invoice, and returns these dates in the iterations list in the response from POST /recurrences:

1
{
2
  "id": "b17d34e3-63c0-4c44-a39c-e09a162ef3b4",
3
  ...
4
  "invoice_id": "8beb7faa-6851-44c8-9fb9-24a94ca30343",
5
  "start_month": 8,
6
  "start_year": 2024,
7
  "end_month": 10,
8
  "end_year": 2024,
9
  "day_of_month": "first_day",
10
  "iterations": [
11
    {
12
      "issue_at": "2024-08-01",
13
      "issued_invoice_id": null,
14
      "status": "pending",
15
      "iteration": 1
16
    },
17
    {
18
      "issue_at": "2024-09-01",
19
      "issued_invoice_id": null,
20
      "status": "pending",
21
      "iteration": 2
22
    },
23
    {
24
      "issue_at": "2024-10-01",
25
      "issued_invoice_id": null,
26
      "status": "pending",
27
      "iteration": 3
28
    }
29
  ],
30
  ...
31
  "status": "active",
32
  "current_iteration": 1
33
}

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 dates. The issued_invoice_id values will be automatically generated and populated when invoices are created.

Recurring invoice configuration

The following fields are used in the request body for POST /recurrences and PATCH /recurrences/{recurrence_id}.

Schedule

The start_month, start_day, end_month, end_day, and day_of_month settings define the invoice schedule.

1
...
2
"start_month": 8,
3
"start_year": 2024,
4
"end_month": 10,
5
"end_year": 2024,
6
"day_of_month": "first_day",
7
...

• end_month and end_year are required. Currently, invoices cannot be infinitely recurring. However, you can extend a recurrence when it is reaching its end date.

• Months (start_month and end_month) are numbered 1 through 12 with 1 corresponding to January.

• The first recurring invoice will be created 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 and day_of_month = “first_day”, the first recurring invoice will be created on October 1. No invoice will be created in September because September 1 has already passed.

Invoice creation modes

Monite lets you customize how recurring invoices are created and, optionally, sent out. This is controlled by the automation_level value in the recurrence configuration, and can be configured for each recurring invoice separately.

You can change the automation_level setting at any time, even for existing recurrences.

Create invoices as drafts

automation_level = draft

Individual invoices are created in the draft status and are not issued or sent to the counterpart. Use this mode if the users may need to review or modify recurring invoices before sending them (for example, add an extra line item or an external payment link).

Users will need to mark invoices as issued and send them manually.

Create invoices without sending

automation_level = issue

Individual invoices will have the issued status (that is, finalized and read-only) but will not be automatically sent to the counterpart. This is useful if:

• invoices may need to be sent to a different email address,
• users want to manually trigger the sending of invoices (whether by using POST /receivables/{invoice_id}/send or through other means),
• invoices are not emailed but instead get printed and sent via post.

Create and automatically send invoices

automation_level = issue_and_send

Individual invoices will have the issued status and will be automatically sent to the counterpart. To use this mode, you must provide the following values in the recurrence configuration:

• 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 the receivables_invoice email template.

• (Optional.) recipients - the list of invoice recipients (To, CC, BCC). 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.

1
...
2
"automation_level": "issue_and_send",
3
"subject_text": "New invoice #{invoice_number}",
4
"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!",
5
"recipients": {
6
  "to": ["customer@example.com"],
7
  "cc": [],
8
  "bcc": []
9
},
10
...

How recurring invoices are generated

When a recurring invoice date comes, Monite creates a copy of the base invoice with the following additional values:

• based_on is set to the ID of the base invoice.
• status starts as “draft”.
• If automation_level is issue or issue_and_send:
  • status is immediatey changed from “draft” to “issued”.
  • document_id is assigned an auto-generated invoice document number based on the entity’s document customization settings.
  • issue_date is set to the current date.
  • 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.
• If automation_level is issue_and_send, Monite then automatically sends the invoice to the specified recipients.

The ID of the new invoice is saved to the iterations[].issued_invoice_id field in the Recurrence object.

The status of the corresponding recurrence iteration is set to one of the following:

• "completed" - the invoice was successfully created and sent to the recipients (if auto-sending is configured).
• "send_failed" - the invoice was issued but could not be sent to the recipients. You can call GET /receivables/{invoice_id}/mails to check for email sending errors and then resend this invoice.
• "issue_failed" - the invoice could not be moved from the draft to issued 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.

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:

1
{
2
  "invoice_id": "<ID of the base invoice>",
3
  "start_month": 8,
4
  "start_year": 2024,
5
  "end_month": 10,
6
  "end_year": 2024,
7
  "day_of_month": "first_day",
8
  "id": "b17d34e3-63c0-4c44-a39c-e09a162ef3b4",
9
  ...
10
  "iterations": [
11
    {
12
      "issue_at": "2024-08-01",
13
      "issued_invoice_id": "<ID of the created recurring invoice>",
14
      "status": "completed",
15
      "iteration": 1
16
    },
17
    {
18
      "issue_at": "2024-09-01",
19
      "issued_invoice_id": null,
20
      "status": "pending",
21
      "iteration": 2
22
    },
23
    ...
24
  ],
25
  "status": "active",
26
  "current_iteration": 2
27
}

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:

1
{
2
  ...
3
  "id": "b17d34e3-63c0-4c44-a39c-e09a162ef3b4",
4
  ...
5
  "iterations": [ ... ],
6
  "status": "completed",
7
  ...
8
}

Manage recurring invoices

View all recurring invoices

Use GET /recurrences to get a list of base invoice IDs and their recurrence schedule.

1
curl -X GET 'https://api.sandbox.monite.com/v1/recurrences' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

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:

1
{
2
  "data": [
3
    {
4
      "invoice_id": "<base invoice ID>",
5
      "start_month": 8,
6
      "start_year": 2024,
7
      "end_month": 10,
8
      "end_year": 2024,
9
      "day_of_month": "first_day",
10
      ...
11
      "iterations": [
12
        {
13
          "issue_at": "2024-08-01",
14
          "issued_invoice_id": "<ID of an already created recurring invoice>",
15
          "status": "completed",
16
          "iteration": 1
17
        },
18
        ...
19
      ],
20
      "status": "active",
21
      "current_iteration": 2
22
    },
23
    ...
24
  ]
25
}

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 base invoice template (such as line items) cannot be changed.

As a workaround, you can change the automation_level to draft in the recurrence configuration to have future invoices created as drafts so that users can change them manually.

Alternatively, you can cancel the current recurring invoice and create a new one with a new invoice template.

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:

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/recurrences/b17d34e3-63c0-4c44-a39c-e09a162ef3b4' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "end_month": 12,
8
       "end_year": 2025
9
     }'

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 creation day

You can change the day of the month on which the recurring invoices will be created. Currently, it can be either the first or last day of the month. Changing the day affects the creation date of future invoices only, it does not affect already created invoices.

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/recurrences/b17d34e3-63c0-4c44-a39c-e09a162ef3b4' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
       "day_of_month": "last_day"
8
     }'

The response will reflect the new scheduled issue_at dates for the future iterations of the recurring invoice.

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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/recurrences/b17d34e3-63c0-4c44-a39c-e09a162ef3b4/cancel' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

This prevents future invoices from being created, but already created invoices are not affected. The status of the recurrence schedule and its future invoices in the iterations array becomes "canceled".