Set up recurring or one-time scheduled invoices with automatic billing workflows, autopay functionality, and flexible recurrence rules.
This system sets up a recurring or one-time schedule to generate invoices automatically based on specified parameters. This endpoint provides flexibility for creating automated billing workflows.
Key Features
Flexible Scheduling
Creates a schedule to generate invoices at specified intervals using recurrence rules following the iCalendar RRule specification.
Autopay Support
Supports optional autopay functionality by attaching a payment_method_id for automatic payment processing.
Smart Recalculation
Automatically recalculates the next_run_at time after each generated invoice or payment for seamless scheduling.
Enhanced Details
Enables merchants to include metadata like tax, subtotal, and lineItems for comprehensive invoice detail.
Email Control
Allows merchants to control email notifications for generated invoices with customizable settings.
Pause & Resume
Full control over schedule lifecycle with the ability to pause and resume billing as needed.
Usage Guide
The rule parameter follows the iCalendar RRule specification. Here are common examples:
Monthly Recurrence:
DTSTART=20231101T120000Z;FREQ=MONTHLYWeekly Recurrence Until a Specific Date:
DTSTART=20231101T120000Z;FREQ=WEEKLY;UNTIL=20231231T000000Z;INTERVAL=1Important:
DTSTARTmust be a future date; past dates are invalid and will result in a 422 validation error.
Response Structure
| Code | Response | Reason |
|---|---|---|
| 201 | Schedule Created | The schedule was successfully created. |
| 400 | Bad Request | Invalid parameters or missing required fields. |
| 422 | Validation Error | DTSTART is in the past, or recurrence rules are incorrectly formatted. |
| 500 | Internal Server Error | Unexpected server error. |
Important Considerations
Best Practices & Requirements
Metadata and Emails: Populate meta fields such as subtotal, tax, and lineItems to include these details in email notifications and invoices for better customer communication.
Future Start Dates: Always ensure DTSTART is set to a future date. Past dates are invalid and will trigger validation errors.
Automatic Recalculation: The system automatically recalculates the next_run_at time each time an invoice is generated or paid, ensuring accurate scheduling.
Audit Trail: Each generated invoice includes comprehensive timestamps and payment details for reporting and compliance purposes.
Invoice Lifecycle: When paused, schedules will not generate invoices until resumed with a valid future DTSTART. Plan pause periods accordingly to avoid billing gaps.