Create recurring invoice
Create recurring invoice. Create a series (ACTIVE immediately). delivery.mode defaults to DRAFT (drafts for review, never emailed). AUTO_SEND emails each generated invoice automatically; it is refused with 409 while automatic sending is unavailable. Scope: write. Manager, Admin or Owner token (Members get 403). Requires the Studio plan or higher (`recurringBilling`, 402 otherwise). While recurring invoices are temporarily unavailable, every recurring endpoint returns a definitive 409 `conflict`.
Authorization
BearerAuth Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.
In: header
Header Parameters
Caller-generated UUID/ULID; replay returns the cached response within 24h.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Server-owned and rejected if sent: currency (the client's), language and delivery.language (the acting user's), paymentMethods (inherit). Defaults: interval 1, timezone = acting user's, localRunTime 06:00, endMode NEVER (or inferred from endDate/maxOccurrences), delivery.mode DRAFT. cadence.startDate must be today or later in the series timezone.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/recurring-invoices" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "clientId": "5e505642-9024-474d-9434-e5a44f505cc5", "cadence": { "unit": "DAY", "startDate": "2019-08-24" } }'{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "status": "ACTIVE", "attentionCode": "string", "attentionMessage": "string", "client": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string" }, "clientId": "5e505642-9024-474d-9434-e5a44f505cc5", "currency": "string", "revision": 0, "templateRevisionNumber": 0, "templateEffectiveFrom": "2019-08-24", "cadence": { "unit": "DAY", "interval": 1, "startDate": "2019-08-24", "timezone": "string", "localRunTime": "string", "anchorLastDay": true, "endMode": "NEVER", "endDate": "2019-08-24", "maxOccurrences": 1 }, "nextScheduledDate": "2019-08-24", "nextRunAt": "2019-08-24T14:15:22Z", "generateNextDate": "2019-08-24", "pausedAt": "2019-08-24T14:15:22Z", "pausedUntil": "2019-08-24", "completedAt": "2019-08-24T14:15:22Z", "endedAt": "2019-08-24T14:15:22Z", "generatedInvoiceCount": 0, "deliveryMode": "DRAFT", "dueOffsetDays": 0, "manualLineItems": [ { "description": "string", "quantity": "string", "unitPrice": "string", "unitLabel": "string" } ], "dynamic": { "includeTime": true, "includeExpenses": true, "projectIds": [ "b2d9859a-b2e9-4f49-b393-9a25d0eff2f8" ], "projects": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string" } ], "sourceStartOn": "2019-08-24" }, "display": { "groupBy": "project", "showProjectName": true, "showTaskName": true }, "taxRate": "string", "discount": { "type": "AMOUNT", "value": "string" }, "notes": "string", "poNumber": "string", "documents": { "attachTimesheet": true, "includeExpenseReceipts": true }, "delivery": { "mode": "DRAFT", "to": [ "user@example.com" ], "cc": [ "user@example.com" ], "subject": "string", "body": "string", "message": "string", "language": "string", "maxAutoSendTotal": "string" }, "reminderOffsets": [ 0 ], "paymentMethodMode": "INHERIT", "estimate": { "currency": "string", "manualSubtotal": "string", "discount": "string", "tax": "string", "total": "string", "includesVariableWork": true }, "upcomingOccurrences": [ { "scheduledDate": "2019-08-24", "state": "SCHEDULED", "occurrenceId": "740a3903-0839-47b4-bce7-bee5e46cbf4a", "runAt": "2019-08-24T14:15:22Z", "issueDate": "2019-08-24", "dueDate": "2019-08-24", "servicePeriodStart": "2019-08-24", "servicePeriodEnd": "2019-08-24", "hasOverride": true, "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec", "invoice": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "number": "string", "status": "string", "total": "string", "currency": "string" }, "deliveryStatus": "string", "skipReason": "string", "failureMessage": "string" } ], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z" }, "warnings": [ "string" ]}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}List recurring invoices
Cursor-paginated series list. Unknown or repeated scalar query parameters return 422. Scope: read. Manager, Admin or Owner token (Members get 403). Requires the Studio plan or higher (`recurringBilling`, 402 otherwise). While recurring invoices are temporarily unavailable, every recurring endpoint returns a definitive 409 `conflict`.
Get recurring invoice
Series detail with the template of its next invoice (the revision in force on nextScheduledDate, or the latest one when there is no next date), an estimate and the next 6 occurrences. Scope: read. Manager, Admin or Owner token (Members get 403). Requires the Studio plan or higher (`recurringBilling`, 402 otherwise). While recurring invoices are temporarily unavailable, every recurring endpoint returns a definitive 409 `conflict`.