Recurring Payments
API Reference
Recurring payments allow your customers to make payments on a custom schedule from a single invoice template. Once set up, the system automatically creates and processes invoices according to your specified payment schedule.
How Recurring Payments Work
Recurring payments are created by creating an invoice template and then updating it to the SCHEDULED
status.
Invoice templates create invoices on a custom schedule to pay each recurring payment. To use recurring payments, you must:
- Create an invoice template.
- Ensure the invoice template has all the necessary information to create recurring invoices:
- Payment Schedule (set by the
paymentSchedule
field) - defines the frequency and pattern of payments - First Payment Date (set by the
deductionDate
field) - when the first recurring payment should be processed - All other fields required to schedule a normal invoice
- Payment Schedule (set by the
- Update the invoice template to the
SCHEDULED
status.
Once the invoice template reaches the SCHEDULED
status, it remains there and begins creating recurring invoices according to the template’s paymentSchedule
and deductionDate
fields.
Payment Schedule Types
Recurring payments support several schedule types:
Daily
Payments occur every day or every N days:
Weekly
Payments occur on specific days of the week:
Monthly
Payments occur on a specific day of the month:
Yearly
Payments occur on a specific date each year:
Invoice Creation Timing
When Invoices Are Created
-
First Invoice: When you update an invoice template to
SCHEDULED
status, the first recurring invoice is immediately created with thedeductionDate
specified in the template. -
Subsequent Invoices: New invoices are created automatically when the previous invoice moves to
PENDING
status on itsdeductionDate
. This ensures there’s always one upcoming invoice in theSCHEDULED
state.
Invoice Status Flow
- SCHEDULED: Invoice is created and waiting for its payment date
- PENDING: Payment date has arrived, invoice is being processed
- PAID: Payment has been successfully processed
- FAILED: Payment processing failed
Next Invoice Creation
The system automatically calculates the next deductionDate
based on the payment schedule and creates the next invoice. This process continues until:
- The payment schedule reaches its end date
- The payment schedule reaches its maximum number of occurrences
- The invoice template is updated to
CANCELED
status
Invoice Numbering for Recurring Invoices
When a recurring invoice is created from a template, its invoice number is automatically incremented based on the template’s invoice number. For example, if the template’s invoice number is INV-001
, the first recurring invoice will be INV-002
, the next will be INV-003
, and so on. The incrementing logic will preserve leading zeros and common patterns (e.g., INV-099
→ INV-100
).
- If the template’s invoice number does not end in a number,
-001
will be appended (e.g.,MONTHLY
→MONTHLY-001
). - The system ensures that each generated invoice number is unique for the same vendor or payer.
Editing Invoice Numbers
You can edit the invoice number of any scheduled recurring invoice after it is created. Changing the invoice number for one invoice does not affect the numbering of future or past invoices. Each invoice’s number is independent once created.
- Editing the invoice number is allowed for scheduled recurring invoices (status
SCHEDULED
and created from a template). - The template’s invoice number is only used as a base for generating new recurring invoices; editing a single invoice’s number does not change the template or future invoices.
Approvals for Recurring Payments
Template Approval
When you create an invoice template, it follows the same approval workflow as regular invoices. The template must be approved before it can be scheduled to create recurring invoices. Approval rules (approvers, approval workflow, etc.) apply to the invoice template itself.
Generated Invoice Approval
Once an invoice template is approved and scheduled, all recurring invoices created from that template are automatically approved and do not require additional approval. This ensures that recurring payments can proceed without manual intervention for each invoice.
Note: If you update the invoice template after it’s been scheduled, the template may need to be re-approved depending on the changes made, but existing generated invoices remain approved.
Updating Created Invoices
Individual Invoice Updates
You can update individual recurring invoices using the Invoice Update API. This allows you to modify:
- Amount, currency, and line items
- Payment source and destination
- Due date and deduction date
- Approvers and approval workflow
- Notes and metadata
- Status (with restrictions)
Important: Updating an individual invoice does not affect the invoice template or future recurring invoices.
Invoice Template Updates
Updating the invoice template affects future recurring invoices but not already-created invoices. You can modify:
- Payment schedule (affects future invoices only)
- Amount, currency, and line items (affects future invoices only)
- Payment source and destination (affects future invoices only)
- Template status (SCHEDULED, CANCELED, etc.)
Bulk Updates
To update multiple recurring invoices at once, you can:
- Update the template - affects all future invoices
- Use the Invoice Search API to find specific invoices and update them individually
- Use webhooks to react to invoice events and make programmatic updates
Viewing Recurring Invoices
Finding Recurring Invoices
To view recurring invoices created from an invoice template, use the Invoice Search API with the invoiceTemplateId
parameter:
Invoice Template Details
Each recurring invoice includes:
recurringTemplateId
: Links the invoice to its templateisRecurringTemplate
: Set tofalse
for created invoicesnextDeductionDate
: Shows when the next invoice will be created (on the template)
Template Status Tracking
The invoice template maintains:
nextDeductionDate
: When the next recurring invoice will be createdstatus
: Current template status (SCHEDULED, CANCELED, etc.)paymentSchedule
: The recurring schedule configuration
Identifying Recurring Invoices
When an invoice is created from a recurring template, the invoice response will include a recurringTemplateId
field that contains the ID of the template that created it. This field is only present for invoices that were created from a recurring template.
Stopping Recurring Payments
Cancel the Template
To stop an invoice template from creating more invoices, use the Update Invoice Template API to update the template to the CANCELED
status:
End Date in Payment Schedule
You can also set an end date in the payment schedule when creating the template:
Maximum Occurrences
Set a maximum number of payments:
Best Practices
Setting Up Recurring Payments
- Test with a small amount first to ensure the schedule works as expected
- Use specific end dates rather than unlimited recurring payments
- Monitor the first few payments to ensure they process correctly
- Set up webhooks to track payment events and failures
Managing Recurring Payments
- Regular monitoring of payment success rates
- Update payment methods before they expire
- Communicate changes to customers when updating templates
- Keep templates simple - complex schedules can be harder to debug
Webhooks and Events
Recurring payments trigger various events that you can monitor via webhooks:
- Invoice Created: When a new recurring invoice is created
- Invoice Status Changed: When an invoice moves between statuses
- Payment Processed: When a payment is successfully completed
- Payment Failed: When a payment fails to process
Set up webhooks to automatically handle these events and maintain your recurring payment system.