Scheduled Invoices
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.
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:
- An invoice is generated based on the schedule's details.
- If a payment method is attached (autopay), a payment is attempted immediately.
- The system updates the schedule's
next_run_atfield 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:
| Status | Description |
|---|---|
NOT STARTED | The schedule's DTSTART is in the future, and the schedule has not yet generated any invoices. |
WAITING | The schedule is active and awaiting the next run date. |
PENDING | The DTSTART has passed, but the system has not yet processed the schedule. |
PAUSED | The schedule has been paused manually, and the next_run_at is set to null. |
COMPLETED | The schedule has reached its defined end (COUNT or UNTIL parameters). |
DELETED | The schedule has been soft-deleted, making it inaccessible but still stored in the database. |
Key Status Transitions
- Pause and Resume: Pausing a schedule clears the
next_run_atfield. To resume, setactive=trueand update theDTSTARTwith a future date. - Delete: Deleting a schedule sets the
deleted_atfield, halts future occurrences, and makes the schedule inaccessible.
Common Use Cases
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.
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.
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:
| Recurrence | RRule Example |
|---|---|
| Repeat monthly indefinitely | DTSTART=20230101T120000Z;FREQ=MONTHLY |
| Repeat monthly for 12 months | DTSTART=20230101T120000Z;FREQ=MONTHLY;COUNT=12 |
| Every other week until December 31, 2025 | DTSTART=20230101T120000Z;FREQ=WEEKLY;UNTIL=20251231T000000Z;INTERVAL=2 |
| One-time invoice on a future date | DTSTART=20230101T120000Z;FREQ=DAILY;COUNT=1 |
Important:
DTSTARTmust be in the future and formatted in ISO 8601 UTC (YYYYMMDDTHHMMSSZ).- For testing, avoid using
DTSTARTvalues close to the current time to account for API latency. - Try a JavaScript utility called Jakubroztocil rrule to see how the RRule spec works.
Best Practices
Setup & Configuration
- Metadata: Populate
metafields (subtotal, tax, line items) to ensure invoices contain complete and accurate details for customers. - Line Item Visibility: Set
meta.hideCustomerLineItems: trueto suppress the itemized line-item breakdown on the hosted bill page and receipt email for every invoice this schedule generates. Line items remain intact on the invoice record and in the downstream gateway payload. Leave unset orfalseto keep line items visible (default). - Autopay: Attach a
payment_method_idfor automatic payments, reducing manual intervention.
Management & Notifications
- Email Notifications: Set
email_notification=falseif you want to disable automatic email receipts for generated invoices. - Deletion: 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
Schedule does not generate invoices
Cause: DTSTART is in the past or incorrectly formatted.
Solution: Use a future DTSTART in the correct ISO 8601 format.
Invoice not processed on time
Cause: The scheduler is delayed due to system processing.
Solution: Wait a few minutes and check the PENDING status.
Schedule paused unintentionally
Cause: active=false was set during an update.
Solution: Update the rule with a valid DTSTART and set active=true.
Unable to delete a schedule
Cause: Invalid or missing schedule ID.
Solution: Verify the schedule ID and ensure the schedule is not already deleted.
Future Occurrences
Use this to estimate revenue or visualize the schedule's execution.
The future_occurrences is an array of timestamps, truncated to the 50 upcoming occurrences in the schedule. Estimating total revenue for a schedule works best when you have a specific end date or when your calculation relies on 50 or fewer occurrences.
Note on Pausing Scheduled InvoicesIf 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.