Creates a new scheduled invoice for automated recurring or one-time billing.
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
Creates a schedule to generate invoices at specified intervals using recurrence rules following the iCalendar RRule specification.
Supports optional autopay functionality by attaching a payment_method_id for automatic payment processing.
Automatically recalculates the next_run_at time after each generated invoice or payment for seamless scheduling.
Enables merchants to include metadata like tax, subtotal, and lineItems for comprehensive invoice detail. Optionally hide line items from customer-facing emails using hideCustomerLineItems.
Allows merchants to control email notifications for generated invoices with customizable settings.
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.
Configure automatic payment processing for generated invoices:
- With Autopay: Include
payment_method_idto attempt payments automatically when invoices are generated - Manual Payment: Omit
payment_method_idto allow customers to manually enter payment details when paying
Autopay provides a seamless experience for recurring billing scenarios where customers have pre-authorized payment methods on file.
Control how customers are notified about new invoices:
- Default Behavior:
email_notificationis set totrueby default - Disable Notifications: Set
email_notification=falseto disable automatic emails - Enhanced Emails: Populate
metafields likesubtotal,tax, andlineItemsto include detailed information in notifications - Hide Line Items: Set
meta.hideCustomerLineItems=trueto suppress line item details from customer-facing emails and receipts. The line items remain stored on the invoice and are passed to the payment gateway, but are excluded from email notifications sent to customers.
Manage schedule lifecycle with pause and resume functionality:
To Pause a Schedule:
- Use
PUT /invoice/schedule/{id} - Set
active=false - This clears the
next_run_atdate
To Resume a Schedule:
- Set
active=true - Provide a future
DTSTARTdate - Schedule will resume generating invoices from the new start date
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. Use meta.hideCustomerLineItems (boolean) to hide line item details from customer-facing emails while retaining them on the invoice record.
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.
Schedule successfully created.
Bad Request - Invalid parameters or missing required fields.
Validation Error - DTSTART is in the past, recurrence rules are incorrectly formatted, or invalid field values.
Internal Server Error.