> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recurring invoices

> Learn how to create and manage recurring invoices in Tesouro.

## Overview

With Tesouro, organizations can set up recurring invoices to bill their customers the same amount every month (or other period).
This is useful, for example, when implementing subscriptions or regular service bills.

Tesouro provides flexible date- and interval-based scheduling options for recurring invoices.
Invoices can be created as drafts or configured to be automatically issued and sent to the predefined recipients.

## Create a recurring invoice

### 1. Create a draft invoice template

Start by [creating the base invoice](/finops/guides/accounts-receivable/invoices/create) 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](/finops/guides/accounts-receivable/invoices/create#verify) to make sure the invoice can be issued successfully.

<Info>Each invoice can have only one recurrence schedule associated with it.</Info>

### 2. Set up the recurrence

Next, configure the recurrence schedule for the base invoice. To do this, call [`POST /recurrences`](/finops/reference/openapi/recurrences/post-recurrences) and specify the start date, frequency, end date or maximum number of invoices, and other settings. For a list of available settings, see [Recurring invoice configuration](#configuration).

<Tip>You can also change most of these settings later.</Tip>

```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/v1/recurrences' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "invoice_id": "8beb7faa-6851-44c8-9fb9-24a94ca30343",

       "start_date": "2025-01-20",
       "end_date": "2025-12-20",
       "frequency": "month",

       "automation_level": "issue_and_send",

       "recipients": {
         "to": ["customer@example.org"],
         "cc": ["support@organization.example.com", "sales@organization.example.com"],
         "bcc": ["exec@organization.example.com"]
       },
       "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!"
     }'
```

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

Tesouro 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`:

```json {4-5, 7, 13, 19} expandable lines theme={null}
{
  "id": "b17d34e3-63c0-4c44-a39c-e09a162ef3b4",
  ...
  "current_iteration": 1,
  "iterations": [
    {
      "issue_at": "2025-01-20",
      "issued_invoice_id": null,
      "status": "pending",
      "iteration": 1
    },
    {
      "issue_at": "2025-02-20",
      "issued_invoice_id": null,
      "status": "pending",
      "iteration": 2
    },
    {
      "issue_at": "2025-03-20",
      "issued_invoice_id": null,
      "status": "pending",
      "iteration": 3
    },
    ...
  ],
  "status": "active"
}
```

The `iterations` array contains a list of all scheduled invoice iterations, both pending and past.

* `issue_at` is the scheduled date when an invoice will be created or was created.
* `issued_invoice_id` is the ID of the created invoice. Initially the value is `null` because those invoices are not created yet. The value will be populated as soon as each invoice is created.
* `status` is one of:
  * `pending` - invoice is scheduled to be created.
  * `canceled` - when a recurrence in [canceled](#cancel), the remaining future iteractions get this status.
  * `completed` - invoice has been successfully created according to `automation_level`.
  * `issue_failed` - when using [`automation_level`](#modes) = `issue` or `issue_and_send`, this status indicates that a draft invoice could not be issued.
    See [How recurring invoices are generated](#how) for details.
  * `skipped` - indicates iterations that were skipped while the recurrence is [paused](#pause).
  * `send_failed` - when using `automation_level` = `issue_and_send`, this status indicates that an invoice could not be automatically sent.
    See [How recurring invoices are generated](#how) for details.

## Recurring invoice configuration

The following fields are used in the request body for [`POST /recurrences`](/finops/reference/openapi/recurrences/post-recurrences) and [`PATCH /recurrences/{recurrence_id}`](/finops/reference/openapi/recurrences/patch-recurrences-id).

### Schedule

Tesouro offers flexible date- and interval-based scheduling options for recurring invoices.
Schedule parameters include:

* `start_date` - Required. The date when the first invoice is to be created. Can be the current or future date.
  This date also defines the day of month/week/year when invoices will be created.
* Either `end_date` or `max_occurrences` (total number of invoices to create) is required to define the end condition for the recurrence.
  <Note>
    Currently, invoices cannot be indefinitely recurring. However, you can [extend a
    recurrence](#change-end-date) when it is reaching its end date.
  </Note>
* `frequency` - Can be monthly (default), weekly, daily, quarterly, or yearly.
  * When creating monthly or quarterly invoices on the 31st, 30th, or 29th, if a month does not have this day the invoice will be created on the last day of that month.
  * When using weekly frequency, if you want to send invoices on a specific day of week (e.g. Tuesday) the `start_date` must fall on that day.
* `interval` - How often invoices will be created based on the frequency, for example:
  * 1 (default) means every month/week/day/etc.
  * 2 means every 2 months/weeks/days/etc.

#### Examples

<AccordionGroup>
  <Accordion title="Monthly invoice created on the 20th">
    ```json POST /recurrences lines theme={null}
    {
      ...
      "start_date": "2025-05-20",
      "end_date": "2026-04-30",

      // Default values, can be omitted
      "frequency": "month",
      "interval": 1
    }
    ```
  </Accordion>

  <Accordion title="Bi-weekly invoice created on Tuesday">
    To send weekly or bi-weekly invoices on a specific day of week, `start_date` must fall on that day of week.

    ```json POST /recurrences lines theme={null}
    {
      ...
      "start_date": "2025-04-22",  // April 22, 2025 is Tuesday
      "end_date": "2025-12-31",
      "frequency": "week",
      "interval": 2
    }
    ```
  </Accordion>

  <Accordion title="Five quarterly invoices">
    ```json POST /recurrences lines theme={null}
    {
      ...
      "start_date": "2025-01-31",
      "frequency": "quarter",
      "max_occurrences": 5
    }
    ```

    Invoices will be created on January 31, April 30, July 31, and so on.
  </Accordion>
</AccordionGroup>

#### Time of day

Currently, Tesouro's scheduler generates recurring invoices twice a day: at 0:00 UTC and 12:00 UTC.

Recurrences created between 0:00 UTC and 11:59 UTC will create invoices at 12:00 UTC on the scheduled day.

Recurrences created between 12:00 UTC and 23:59 UTC will create invoices at 0:00 UTC on the scheduled day.

### Invoice creation modes

Tesouro lets you customize how recurring invoices are created and, optionally, sent out.
This is controlled by the [`automation_level`](/finops/reference/openapi/recurrences/post-recurrences#request.body.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`](/finops/guides/accounts-receivable/invoices/index#statuses) 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](/finops/guides/accounts-receivable/invoices/create#send-via-email) 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`](/finops/reference/openapi/receivables/post-receivables-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](/finops/guides/advanced/email-templates/index), 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`](/finops/reference/openapi/receivables/get-receivables-id#response.body.invoice.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.

```json lines theme={null}
...
"automation_level": "issue_and_send",
"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": ["customer@example.com"],
  "cc": [],
  "bcc": []
},
...
```

## How recurring invoices are generated

When the date and [time](#time-of-day) of a recurring invoice arrives, Tesouro 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`](#modes) 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 organization's [document customization settings](/finops/guides/advanced/document-number-customization).
  * `issue_date` is set to the current date.
  * Invoice due date is calculated automatically based on the [payment terms](/finops/guides/common/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](/finops/guides/common/payment-terms#net-x), the `due_date` is set to 2024-08-11.
* If `automation_level` is `issue_and_send`, Tesouro then automatically sends the invoice to the specified recipients.

The ID of the created 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`](/finops/reference/openapi/receivables/get-receivables-id-mails) to check for email sending errors and then [resend this invoice](/finops/guides/accounts-receivable/invoices/create#send-via-email).
* `"issue_failed"` - the invoice could not be moved from the `draft` to `issued` status.
  The `receivable.failed` [webhook](/finops/guides/getting-started/webhooks/index#events) is also triggered in this case.

  Normally this should not happen. You can [verify the invoice data](/finops/guides/accounts-receivable/invoices/create#verify) to see if there are any errors, then update invalid or missing data and [re-issue the invoice](/finops/reference/openapi/receivables/post-receivables-id-issue).
  If the base invoice's data is no longer valid or sufficient, [update the base invoice](#update-invoice-details) to resolve the issue for future invoices.

<Info>
  Re-issuing or re-sending an invoice instance does not change the corresponding iteration status
  (`interations[].status`) in the recurrence configuration.
</Info>

The `current_iteration` in the recurrence configuration is then incremented to reflect the next pending invoice.

The response from [`GET /recurrence/{recurrence_id}`](/finops/reference/openapi/recurrences/get-recurrences-id) will then look like this:

```json {12-13} expandable lines theme={null}
{
  "id": "b17d34e3-63c0-4c44-a39c-e09a162ef3b4",
  "invoice_id": "<ID of the base invoice>",
  "start_date": "2024-08-01",
  "max_occurrences": 12,
  "frequency": "month",
  "interval": 1,
  ...
  "iterations": [
    {
      "issue_at": "2024-08-01",
      "issued_invoice_id": "<ID of the created recurring invoice>",
      "status": "completed",
      "iteration": 1
    },
    {
      "issue_at": "2024-09-01",
      "issued_invoice_id": null,
      "status": "pending",
      "iteration": 2
    },
    ...
  ],
  "status": "active",
  "current_iteration": 2
}
```

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:

```json {6} lines theme={null}
{
  ...
  "id": "b17d34e3-63c0-4c44-a39c-e09a162ef3b4",
  ...
  "iterations": [ ... ],
  "status": "completed",
  ...
}
```

## Manage recurring invoices

### View all recurring invoices

Use [`GET /recurrences`](/finops/reference/openapi/recurrences/get-recurrences) to get a list of base invoice IDs and their recurrence schedules.

```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/v1/recurrences' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -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:

```json maxLines=18 {3, 10, 16} expandable lines theme={null}
{
  "data": [
    {
      "invoice_id": "<base invoice ID>",
      "start_date": "2024-08-01",
      ...
      "iterations": [
        {
          "issue_at": "2024-08-01",
          "issued_invoice_id": "<ID of an already created recurring invoice>",
          "status": "completed",
          "iteration": 1
        },
        {
          "issue_at": "2024-09-01",
          "issued_invoice_id": null,
          "status": "pending",
          "iteration": 2
        },
        ...
      ],
      "status": "active",
      "current_iteration": 2
    },
    ...
  ]
}
```

You can then use [`GET /receivable/{receivable_id}`](/finops/reference/openapi/receivables/get-receivables-id) to fetch the details for a specific invoice ID, such as the total amount, line items, and so on.

### Update invoice details

There are two ways to update invoice data for a recurring invoice:

* Update the base invoice template (the invoice in the `recurring` status). The changes will be reflected in future invoices, but already created invoices are not affected.
* With [`automation_level`](#modes) = `draft`, individual invoices are created as drafts and users can edit them before sending out.

In any case, you can update any data in an invoice - line items, prices, [payment terms](/finops/guides/common/payment-terms), and so on.

<Note>
  To update the invoice number format, use the organization's [document number
  customizaton](/finops/guides/advanced/document-number-customization) options.
</Note>

To update the base invoice:

1. Call [`GET /recurrences/{recurrence_id}`](/finops/reference/openapi/recurrences/get-recurrences-id) to get the ID of the base invoice for that recurrence:

   ```json {3} lines theme={null}
   {
     "id": "b17d34e3-63c0-4c44-a39c-e09a162ef3b4",
     "invoice_id": "8beb7faa-6851-44c8-9fb9-24a94ca30343"
     ...
   }
   ```

   Alternatively, call [`GET /receivables?status=recurring`](/finops/reference/openapi/receivables/get-receivables) (optionally with other filters) and find the ID of the needed invoice template among the results.

2. Edit the base invoice by calling [`PATCH /receivables/{receivable_id}`](/finops/reference/openapi/receivables/patch-receivables-id) and providing the new values.

### Change the invoice schedule

You can change the frequency, interval, end condition, and other parameters of existing recurrences at any time.
If the recurrence has not begun yet, you can also change the `start_date` to another non-past date.

<Note>
  Changing the invoice schedule affects the creation date of future invoices only, it does not
  affect already created invoices.
</Note>

To update the recurrence configuration, send the new values in a [`PATCH /recurrences/{recurrence_id}`](/finops/reference/openapi/recurrences/patch-recurrences-id) request:

```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/recurrences/b17d3...3b4' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "end_date": "2026-11-30"
     }'
```

The response reflects the updated pending iterations and their scheduled dates.
If the recurrence has been extended, additional iterations are added.
If the end date has been moved ealier, excess pending iterations are removed.

### Pause a recurring invoice

To temporarily pause a recurring invoice sequence, call [`POST /recurrences/{recurrence_id}/pause`](/finops/reference/openapi/recurrences/post-recurrences-id-pause).

New invoices are not created while the recurrence is paused.
However, the corresponding scheduled invoice dates remain in the `iterations` array returned by `GET /recurrences/{recurrence_id}`.
When the next scheduled invoice date is reached while the recurrence is paused, that iteration gets the `"skipped"` status to indicate that no invoice was created.

```json {12-13} maxLines=14 title="GET /recurrences/{recurrence_id}" expandable lines theme={null}
{
  ...
  "iterations": [
    {
      "issue_at": "2025-02-20",
      "issued_invoice_id": "<ID of the created invoice>",
      "status": "completed",
      "iteration": 1
    },
    {
      "issue_at": "2024-03-20",
      "issued_invoice_id": null,
      "status": "skipped",
      "iteration": 2
    },
    {
      "issue_at": "2024-04-20",
      "issued_invoice_id": null,
      "status": "pending",
      "iteration": 2
    },
    ...
  ]
}
```

<Note>
  Skipped iterations still count towards the invoice limit for recurrences configured with
  `max_occurrences`. To extend a paused recurrence, edit it and increase the `max_occurrences` value
  accordingly.
</Note>

The recurrence stays in the `"paused"` status until either it is [resumed](#resume) or its end date or invoice limit is reached.
In the latter case, the recurrence `status` will be automatically changed from `"paused"` to `"completed"` once the end condition is met.

### Resume a recurring invoice

To resume a paused recurrence, call [`POST /recurrences/{recurrence_id}/resume`](/finops/reference/openapi/recurrences/post-recurrences-id-resume).
This changes the recurrence's `status` back to `"active"`, and the remaining invoices will be created based on the configured schedule.

<Note>Skipped invoices will not be created retroactively.</Note>

### Cancel a recurring invoice

You may want to cancel a recurring invoice, for example, if an organization's customer cancels their order or subscription. To do this, call [`POST /recurrences/{recurrence_id}/cancel`](/finops/reference/openapi/recurrences/post-recurrences-id-cancel).

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

<Note>
  Only active and paused recurrences can be canceled.

  Canceled recurring invoices cannot be reactivated or otherwise updated. The invoice and its recurrence schedule will have to be recreated anew.
</Note>