> ## 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. # Invoice payment reminders > Learn how to automatically send payment reminders to customers before the invoice due dates and early discount dates. ## Overview Tesouro can automatically send payment reminder emails to an organization's customers before the invoice due dates and [early discount dates](/finops/guides/common/payment-terms#discounts). Organizations can customize the contents of payment reminders and the days on which these reminders should be sent. For example, an organization can send payment reminders to remind a counterpart about the early discount days defined in the invoice's payment terms. There are two types of payment reminders: *discount reminders* and *final reminders*. Discount reminders are configured to be sent before each early payment discount date defined in the payment terms. Conversely, a final reminder is the last reminder to a counterpart and is sent just before the invoice's due date as defined by the `term_final` field in the payment terms. Reminders can be configured on a per-invoice basis or shared between multiple invoices. The language on the payment reminder email depends on the language of the invoice's counterpart. If the counterpart language is `null`, all payment reminder emails to the counterpart will be in English. For more information, see [Email template localization](/finops/guides/advanced/email-templates/index#localization). ## How it works A payment reminder is sent if the following conditions are met: * the counterpart has not paid the invoice in full yet, * the invoice has `payment_reminder_id` specified (see below), * the invoice is due in N days, or an early payment discount ends in M days (where M and N are customizable), * organization setting `reminder.enabled` is `true`, * counterpart setting `reminders_enabled` is `true`. Payment reminders are sent to the email address of the counterpart's [default contact](/finops/guides/common/counterparts/contacts#default), which gets saved in the `counterpart_contact.email` field of the invoice. The `From` address in reminders is `"Tesouro" `, and it can be [customized](/finops/guides/advanced/mailboxes). ## Configure payment reminders Invoice payment reminders are directly linked to payment terms. When configuring payment reminders, you must consider certain information about the invoice's payment terms. This includes the number of discount tiers and the assigned due dates of all payment tiers. For example, suppose you assign a payment reminder with two early discount tiers to an invoice whose payment term has a single early discount tier. In that case, the system will only notify the counterpart about the early discount date defined on the payment term. If an invoice has no early discount dates in the payment terms, no discount reminders will be triggered at any point. However, since all invoices must have due dates, final reminders can be configured to be sent any number of days before the invoice's due date defined in the `term_final` field on payment terms. To use payment reminders, you need to create a *reminder configuration* and include it when creating an invoice. The value of a payment reminder's `days_before` field represents the number of days before the specified payment term's `number_of_days` field that a reminder notification is triggered. For reminders to be triggered successfully, the `days_before` field on each payment reminder tier must be less than the `number_of_days` field in the payment terms for its corresponding tier. Invoices cannot be issued when the potential due dates on any of the payment term's tiers occur before the scheduled payment reminder date for the corresponding tier. Attempting to issue an invoice where the value of the payment reminder's `days_before` field on any tier exceeds the value of the payment term's `number_of_days` field will throw an error. ### 1. Create a payment reminder configuration To create a new payment reminder, call `POST /payment-reminders`. The `days_before` value represents the number of days before each payment due date—early discount or final—to send the reminder notifications to the counterpart: ```sh expandable lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/payment-reminders' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "name": "Send payment reminders 5 days before each due date", "term_1_reminder": { "days_before": 5, "subject": "Subject of the reminder email", "body": "... HTML content of the reminder email ..." }, "term_2_reminder": { "days_before": 5, "subject": "Subject of the reminder email", "body": "... HTML content of the reminder email ..." }, "term_final_reminder": { "days_before": 5, "subject": "Subject of the reminder email", "body": "... HTML content of the reminder ..." } }' ``` The email subject and body can include [variables](/finops/guides/advanced/variables) such as `{invoice_number}` which will be substituted with the corresponding values. To use the `/payment-reminders*` endpoints with an [organization user token](/finops/guides/organizations/users#create-role), this organization user must have a [role](/finops/guides/organizations/users#create-role) that includes the `payment_reminder` permission. The response contains the ID assigned to this configuration. You will need to specify this ID later when creating invoices. ```json lines theme={null} { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Send payment reminders 5 days before each due date", ... } ``` ### 2. Specify the payment reminder configuration for an invoice When [creating a new invoice](/finops/guides/accounts-receivable/invoices/create) or updating an existing draft invoice, you can use the `payment_reminder_id` field to specify the desired payment reminder configuration for this invoice: ```sh lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "type": "invoice", "payment_reminder_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", ... }' ``` After configuring a payment reminder and assigning it to an invoice, you can ensure that the payment reminder's configuration aligns with the invoice's payment terms configuration before issuing the invoice. To do this, make a `POST` request to the [`/receivables/{receivable_id}/verify`](/finops/reference/openapi/receivables/post-receivables-id-verify) endpoint. Tesouro allows organizations to update a payment reminder's configuration when assigned to an invoice. However, the configuration on the assigned invoice is frozen whenever the invoice is issued, and any changes to the payment reminder configuration will not affect the invoice's reminders. For more information on updating payment reminders, see [`PATCH /payment-reminders/ {payment_reminder_id}`](/finops/reference/openapi/payment-reminders/patch-payment-reminders-id). The `payment_reminders` field on the `warnings` object of the response informs the user about any incorrect payment reminder configurations on the invoice as shown: ```json lines theme={null} { "errors": { ... }, "warnings": { "payment_reminders": "The due date on one or more of the invoice's payment term's tier comes before the scheduled reminder date for the corresponding tier. Review the reminders configuration for the invoice." } } ``` ## Preview a payment reminder email After creating a payment reminder and assigning it to an invoice, you can preview reminder emails before sending them out. This step can be helpful when troubleshooting email template layouts for a payment reminder to ensure the final presentation aligns with your template design. To preview a payment reminder template, call `POST /receivables/{receivable_id}/preview`: ```sh lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3/preview' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "subject_text": "Your invoice #{invoice_number} is due in 5 days", "body_text": "Dear {contact_name},\n\nKindly be aware that your invoice #{invoice_number} is due in 5 days!\nPlease pay the balance of {amount_due} (invoice #{invoice_number}) before {due_date} to get the 7% discount.\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!", "type": "discount_reminder" } ``` The `type` field determines the type of receivable document to be previewed and is a required field for previewing payment reminders. The value of the `type` field depends on the type of payment reminder email. This can be either `discount_reminder` or `final_reminder`. The values of the `subject_text` and `body_text` fields will replace the `subject_text` and `body_text` variables defined when creating your custom templates. For more information, see [Create and manage email templates](/finops/guides/advanced/email-templates/manage). ## Manually trigger payment reminders After configuring a payment reminder and assigning it to an invoice, you can manually trigger it to send a reminder email to a counterpart. Tesouro allows you to send test reminders to an invoice's counterpart, allowing you to verify the accuracy of your configuration. You can also use the `recipients` field in the request object to include email addresses that you intend to send the reminder as a copy or blind copy. To manually trigger a reminder, call [`POST /receivables/{receivable_id}/send-test-reminder`](/finops/reference/openapi/receivables/post-receivables-id-send-test-reminder) and provide the `reminder_type` in the request body as shown: ```sh lines theme={null} curl -X POST 'https://api.sandbox.tesouro.com/v1/receivables/411dc6eb...6289b3/send-test-reminder' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "reminder_type": "term_1", "recipients": { "to": ["dana@example.com"], "cc": ["support@example.com"] } } ``` You can manually trigger the reminder email on any payment reminder tier by using a `reminder_type` value of `term_1`, `term_2` or `term_final` in the request object. The successful response sends the reminder email to the counterpart and returns the `mail_ids` in the response. ## Enable or disable payment reminders ### For specific counterparts By default, payment reminders are enabled for all counterparts of an organization. If you want to disable reminders for a specific counterpart, such as a customer who always pays on time, call `PATCH /counterparts/{counterpart_id}` and set the `reminders_enabled` field to `false`: ```sh lines theme={null} curl -X PATCH 'https://api.sandbox.tesouro.com/v1/counterparts/6291de...3699' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'X-Organization-Id: ORGANIZATION_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"reminders_enabled": false}' ``` This disables not only payment reminders, but also [overdue reminders](/finops/guides/accounts-receivable/invoices/overdue-reminders) for this counterpart. ### For all counterparts To disable reminders for all counterparts of a specific organization, call `PATCH /organizations/{organization_id}/settings` and change the `reminder.enabled` field to `false`. ```sh lines theme={null} curl -X PATCH 'https://api.sandbox.tesouro.com/identity/v1/organizations/692b50...09da8/settings' \ -H 'X-Finops-Version: 2025-06-23' \ -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "reminder": { "enabled": false } }' ``` A successful request disables both overdue reminders and payment reminders for all counterparts of an organization. To enable reminders again, change the `reminder.enabled` field back to `true`.