Scheduled invoices enable merchants to automate recurring billing for their customers using the Stax Pay API. By creating a schedule record, you can define when and how often invoices are generated, with options to automatically charge a saved payment method (autopay) or allow the customer to manually pay each invoice.

This page provides an in-depth overview of the scheduled invoice system, its functionality, and the lifecycle of scheduled invoices.

---

How Scheduled Invoices Work

A schedule record acts as an "invoice generator." It stores information such as:

• Customer Details: Who the invoice is for.
• Invoice Details: The total amount, taxes, line items, and other metadata.
• Frequency Rules: How often the invoice should be generated (daily, weekly, monthly, etc.).
• Autopay Setup: Optional saved payment method to automatically process payments.

At each scheduled interval:

1. An invoice is generated based on the schedule's details.
2. If a payment method is attached (autopay), a payment is attempted immediately.
3. The system updates the schedule's next_run_at field to calculate the next occurrence.

Note: If no payment method is attached, the customer can manually pay the invoice, and optionally save a payment method for future use.

---

Schedule Lifecycle and Statuses

Scheduled invoices can have the following statuses:

Key Status Transitions

• Pause and Resume: Pausing a schedule clears the next_run_at field. To resume, set active=true and update the DTSTART with a future date.
• Delete: Deleting a schedule sets the deleted_at field, halts future occurrences, and makes the schedule inaccessible.

---

Common Use Cases

Recurring Payments

Scheduled invoices simplify recurring payments by automating invoice generation and processing.

• Example: A monthly subscription service can create a schedule with FREQ=MONTHLY;COUNT=12.

Deferred Billing

Schedules allow merchants to defer billing to a future date without requiring immediate action from the customer.

• Example: Generate a one-time invoice for a specific date in the future with FREQ=MONTHLY;COUNT=1.

Installment Payments

Merchants can split a larger payment into multiple installments with specific amounts and due dates.

• Example: A three-part payment plan can use FREQ=WEEKLY;COUNT=3.

---

RRule Parameter Guide

The rule field in a schedule specifies the recurrence pattern using the iCalendar RRule . Here are some examples:

Important:

• DTSTART must be in the future and formatted in ISO 8601 UTC (YYYYMMDDTHHMMSSZ).
• For testing, avoid using DTSTART values close to the current time to account for API latency.
• Try a JavaScript utility to see how the RRule spec works, called Jakubroztocil rrule.

---

Best Practices

• Metadata: Populate meta fields (subtotal, tax, line items) to ensure invoices contain complete and accurate details for customers.
• Autopay: Attach a payment_method_id for automatic payments, reducing manual intervention.
• Email Notifications: Set email_notification=false if you want to disable automatic email receipts for generated invoices.
• To delete a schedule, call DELETE invoice/schedule/id. A deleted_at variable will be set for the time of deletion. There is no way to undelete a schedule without a support request.

---

Troubleshooting and Error Handling

---

Advanced Features

Future Occurrences

Use this to estimate revenue or visualize the schedule's execution.

Thefuture_occurrences is an array of timestamps and is truncated to 50 upcoming occurrences for the schedule. Estimating total revenue for a schedule works best if you have a specific end date or if your calculation only relies on 50 or fewer occurrences.

📘

Note on Pausing Scheduled Invoices

If you use PUT invoice/schedule/id to pause the schedule. It will clear the next_run_at date also. This means no new invoices will be generated. To resume the schedule, you must mark active to 1 or true again, and you will need to update your rule’s DTSTART to have a date in the future. A date in the past is never allowed during a PUT or POST operation.