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=MONTHLY

Weekly Recurrence Until a Specific Date:

DTSTART=20231101T120000Z;FREQ=WEEKLY;UNTIL=20231231T000000Z;INTERVAL=1

Important: DTSTART must 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.