Update an existing invoice schedule, allowing changes to metadata, recurrence rules, or the schedule's active status.
Update an existing invoice schedule, allowing changes to metadata, recurrence rules, or the schedule's active status.
Key Features
Modify invoice details, including subtotal, tax, and lineItems.
Pause or resume a schedule by toggling the active status.
Change the recurrence rule (rule) to update the schedule's frequency and timing.
Clear or manually set the next_run_at field for resumed schedules.
Usage Guide
Pausing a Schedule
- Set
active=falseto pause the schedule. - When paused, the
next_run_atfield will automatically be set tonull. - No new invoices will be generated while the schedule is paused.
Resuming a Schedule
- Set
active=trueto resume a paused schedule. - A valid
next_run_atdate in the future must be provided when resuming. - Past dates for
next_run_atwill result in a validation error.
Updating Recurrence Rules
- Use the
ruleparameter to adjust the schedule's recurrence pattern. - Ensure the new
ruleincludes a validDTSTARTvalue in the future.
Invoice Metadata
- Update fields such as
subtotal,tax, andlineItemsto reflect new invoice details. - Set
meta.hideCustomerLineItemstotrueto hide line item details from customer-facing emails and receipts. Line items remain stored on the invoice and are passed to the payment gateway. - Changes will apply only to future invoices generated by the schedule.
Response Structure
| Code | Response | Reason |
|---|---|---|
200 | Success | The schedule was successfully updated. |
400 | Bad Request | Invalid fields or missing required parameters. |
422 | Validation Error | DTSTART or next_run_at is in the past. |
500 | Internal Server Error | An unexpected server error occurred. |
Important Considerations
Active Status
- Pausing the schedule (
active=false) prevents further invoices from being generated. - To resume the schedule, provide a new
next_run_atdate in the future.
Recurrence Rules
- Follow the iCalendar RRule format for the
ruleparameter. - A properly formatted
DTSTARTin the future is mandatory.
Audit Trail
All changes to the schedule, including updates to metadata and status changes, are logged for tracking purposes.
Future Dates Only
Ensure all dates, such as next_run_at and DTSTART, are in the future to avoid validation errors.
Schedule successfully updated.
Bad Request - Invalid fields or missing required parameters.
Validation Error - DTSTART or next_run_at is in the past, or invalid field values.
Internal Server Error.