Finds and lists all scheduled invoices under a merchant's account.
Retrieves a list of all scheduled invoices for a merchant's account. This endpoint allows merchants to manage their scheduled invoices effectively and provides flexibility with sorting and filtering options.
Key Features
- Returns all scheduled invoices associated with a merchant account.
- Provides default sorting by
created_atin descending order (newest first). - Enables filtering and ordering based on various parameters.
- Supports pagination for handling large datasets.
Usage Notes
Default Sorting: Results are sorted by created_at in descending order.
Custom Sorting: Use query parameters to sort by other fields, such as next_run_at or status.
Filtering: Include parameters like status (e.g., active, paused, deleted) or customer-specific identifiers to refine the results.
Paginate results using the page and limit parameters.
Example: ?page=1&limit=50 retrieves the first 50 scheduled invoices.
For large datasets, implement pagination to ensure optimal performance and usability.
Scheduled invoices can be managed through these operations:
- Created using
POST /invoice/schedule - Updated using
PUT /invoice/schedule/{id} - Deleted using
DELETE /invoice/schedule/{id}
Additional Parameters
| Sort Parameter | Description | Example Query |
|---|---|---|
last_run_at | Sorts by the most recent time the schedule was run. | ?sort=last_run_at&order=DESC (latest first) |
next_run_at | Sorts by the next scheduled run time. | ?sort=next_run_at&order=ASC (earliest first) |
count | Sorts numerically by the total number of runs. | ?sort=count&order=DESC (highest first) |
created_at | Sorts by the creation time of the schedule. | ?sort=created_at&order=ASC (oldest first) |
updated_at | Sorts by the last time the schedule was updated. | ?sort=updated_at&order=DESC (most recent first) |
Additional Notes
- Use the
orderparameter to define the sorting direction:DESC: Descending order (e.g., newest, latest, highest).ASC: Ascending order (e.g., oldest, earliest, lowest).
Response Structure
| Code | Response | Reason |
|---|---|---|
| 200 | Success | Returns a paginated list of scheduled invoices. |
| 400 | Bad Request | Invalid query parameters or missing required fields. |
| 401 | Unauthorized | Authentication failed. |
| 500 | Internal Server Error | Unexpected server error. |
Important Considerations
- Schedule Management: Use this endpoint to monitor and manage active, paused, or deleted schedules.
- Deleted Schedules: Scheduled invoices marked as deleted will not generate new invoices.
- Pagination Best Practices: For large datasets, implement pagination to ensure optimal performance and usability.
- Audit Trail: Scheduled invoices include timestamps and metadata for tracking purposes. Use this information to reconcile or audit scheduled billing activities.