Recurring invoices

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.

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.

2. Set up the recurrence

Next, you need to 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:

1
curl -X POST 'https://api.sandbox.monite.com/v1/recurrences' \
2
     -H 'X-Monite-Version: 2024-01-31' \
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
       "start_month": 8,
9
       "start_year": 2022,
10
       "end_month": 10,
11
       "end_year": 2022,
12
       "day_of_month": "first_day"
13
     }'

Notes:

• Months - start_month and end_month - are represented numerically, with 1 for January and 12 for December.

• end_month and end_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 and day_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:

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

The issued_invoice_id fields in the iterations list is null because the instances of the recurring invoice will be created on their scheduled issue dates. The issued_invoice_id will be automatically generated and populated on each issue date.

3. Track the issued invoices

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 according to the entity’s document customization settings.
• issue_date - set to the current date.
• status - set 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 issued_invoice_id field in the Recurrence object, and the status of the corresponding recurrence iteration changes to either "completed" (if the invoice was issued successfully) or "issue_failed". The recurrence’s current_iteration is incremented to reflect the next pending invoice.

The response from GET /recurrence/{recurrence_id} would now look like this:

1
{
2
  "invoice_id": "<ID of the base invoice>",
3
  "start_month": 8,
4
  "start_year": 2022,
5
  "end_month": 10,
6
  "end_year": 2022,
7
  "day_of_month": "first_day",
8
  "id": "b17d34e3-63c0-4c44-a39c-e09a162ef3b4",
9
  ...
10
  "iterations": [
11
    {
12
      "issue_at": "2022-08-01",
13
      "issued_invoice_id": "<ID of the issued recurring invoice>",
14
      "status": "completed",
15
      "iteration": 1
16
    },
17
    {
18
      "issue_at": "2022-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 issued 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 issued:

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

Send the issued invoices

When a recurring invoice is issued, it is not automatically sent to the associated counterpart. You will need to send the invoice yourself.

You can track the scheduled issue dates and set up external reminders or an external automated task to send the recurring invoices once they have been issued.

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-01-31' \
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": 2022,
7
      "end_month": 10,
8
      "end_year": 2022,
9
      "day_of_month": "first_day",
10
      ...
11
      "iterations": [
12
        {
13
          "issue_at": "2022-08-01",
14
          "issued_invoice_id": "<ID of an already issued 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 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.

Extend a recurring invoice

To extend a recurring invoice past its scheduled end date, 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-01-31' \
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": 2023
9
     }'

The response will reflect the additional scheduled iterations:

1
{
2
  ...
3
  "start_month": 8,
4
  "start_year": 2022,
5
  "end_month": 12,
6
  "end_year": 2023,
7
  ...
8
  "iterations": [
9
    ...
10
    {
11
      "issue_at": "2023-12-01",
12
      "issued_invoice_id": null,
13
      "status": "pending",
14
      "iteration": 17
15
    }
16
  ],
17
  "status": "active",
18
  "current_iteration": 1
19
}

Change the recurrence schedule

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.

1
curl -X PATCH 'https://api.sandbox.monite.com/v1/recurrences/b17d34e3-63c0-4c44-a39c-e09a162ef3b4' \
2
     -H 'X-Monite-Version: 2024-01-31' \
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 that, 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-01-31' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN'

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