evenbooks
Sign inStart for free

Recurring invoices

Invoices issued on a schedule.

Paths are relative to https://evenbooks.org/api/v1. How keys, errors, paging and versions work is in the guide; the whole reference is also an OpenAPI 3.1 document.

Administrator key marks endpoints that need a key with the admin role, Write access those a read-only key can’t call, and Idempotent those that accept an idempotency key.

List recurring invoices

get/recurring

Every schedule, by name. List items omit occurrences, catchUp and templateTotal: get one schedule for those.

Response 200

array of ScheduleDto

Errors 400 · 401 · 403 · 404 · 409 · 429

Create a recurring invoice

post/recurring
Write access

A schedule issues an invoice for the customer on every occurrence from anchorDate (until endDate, if set), and emails it when sendEmail is on (to emailTo, or else the customer’s email). Give either contactId and template (the invoice lines), or fromInvoiceId to copy an issued invoice; its payment URL is copied only with copyPaymentUrl: true.

Request body

CreateScheduleInput

  • fromInvoiceIdstring · Uuid
  • contactIdstring · Uuid
  • namestringrequired

    1–120 characters

  • frequencystring · Frequencyrequired

    One of: weekly biweekly monthly quarterly semiannually yearly

  • anchorDatestring · PlainDateStringrequired
  • endDatestring · PlainDateString or null
  • termsDaysinteger

    0–365

  • sendEmailboolean

    default false

  • emailTostring (email) or null

    up to 254 characters

  • templateRecurringTemplateInput
    Show 5 fields
    • linesarray of DocumentLineInputrequired

      1–200 items

    • documentDiscountDiscountInput or null
    • memostring or null

      up to 2000 characters

    • footerstring or null

      up to 2000 characters

    • paymentUrlstring or null

      up to 2000 characters · pattern ^https:\/\/.*

  • copyPaymentUrlboolean

    default false

Response 200

ScheduleDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Get a recurring invoice

get/recurring/{id}

Includes the invoices issued so far (occurrences) and, for a paused schedule, the missed occurrences a catch-up resume would issue (catchUp).

Parameters

  • idstring (uuid)path · required

Response 200

ScheduleDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Change a recurring invoice

patch/recurring/{id}
Write access

Omitted fields stay as they are. A new template becomes a new template version used for future invoices only. Send version from your last read (409 version_conflict); cancelled schedules cannot change (409 invalid_state).

Parameters

  • idstring (uuid)path · required

Request body

UpdateScheduleInput

  • versionintegerrequired
  • namestring

    1–120 characters

  • endDatestring · PlainDateString or null
  • termsDaysinteger

    0–365

  • sendEmailboolean
  • emailTostring (email) or null

    up to 254 characters

  • templateRecurringTemplateInput
    Show 5 fields
    • linesarray of DocumentLineInputrequired

      1–200 items

    • documentDiscountDiscountInput or null
    • memostring or null

      up to 2000 characters

    • footerstring or null

      up to 2000 characters

    • paymentUrlstring or null

      up to 2000 characters · pattern ^https:\/\/.*

Response 200

ScheduleDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Cancel a recurring invoice

post/recurring/{id}/cancel
Write access

Stops the schedule for good; invoices already issued stay as they are. Send version from your last read (409 version_conflict). The reason is kept in History.

Parameters

  • idstring (uuid)path · required

Request body

PostRecurringIdCancelBody

  • versionintegerrequired
  • reasonstringrequired

    1–500 characters

Response 200

ScheduleDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Pause a recurring invoice

post/recurring/{id}/pause
Write access

Stops issuing until it is resumed. Active schedules only (409 invalid_state); send version from your last read (409 version_conflict).

Parameters

  • idstring (uuid)path · required

Request body

PostRecurringIdPauseBody

  • versionintegerrequired

Response 200

ScheduleDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Resume a recurring invoice

post/recurring/{id}/resume
Write accessIdempotent

catch_up issues every occurrence missed while paused, right away (listed in the schedule’s catchUp); skip never issues them and continues from the next one. Paused schedules only (409 invalid_state); send version from your last read (409 version_conflict).

Parameters

  • idstring (uuid)path · required

Request body

ResumeScheduleInput

  • versionintegerrequired
  • modestringrequired

    One of: catch_up skip

  • idempotencyKeystring · IdempotencyKey

Response 200

ScheduleDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Issue due recurring invoices now

post/recurring/{id}/run
Write access

Issues every occurrence that is due today or earlier and has no invoice yet, as the scheduler would, and emails them if the schedule says so. Works on active and paused schedules; cancelled and completed ones issue nothing. Safe to repeat: an occurrence never gets a second invoice.

Parameters

  • idstring (uuid)path · required

Response 200

ScheduleRunResultDto

  • issuedarray of string

    Ids of the invoices issued by this run.

  • skippedExistinginteger

    Due occurrences that already had an invoice.

Errors 400 · 401 · 403 · 404 · 409 · 429

Schemas

The types these endpoints take or return, by name. Type names above link here.

DecimalString

decimal string

string

up to 32 characters · pattern ^-?\d+(\.\d+)?$

Discount

DiscountInput

DocumentLineInput

DocumentLineInputOutput

Frequency

string

One of: weekly biweekly monthly quarterly semiannually yearly

IdempotencyKey

string

8–128 characters

NonNegativeDecimalString

string

up to 32 characters · pattern ^\d+(\.\d+)?$

PlainDateString

string

pattern ^\d{4}-\d{2}-\d{2}$

RecurringTemplateInput

  • linesarray of DocumentLineInputrequired

    1–200 items

  • documentDiscountDiscountInput or null
  • memostring or null

    up to 2000 characters

  • footerstring or null

    up to 2000 characters

  • paymentUrlstring or null

    up to 2000 characters · pattern ^https:\/\/.*

RecurringTemplateInputOutput

  • linesarray of DocumentLineInputOutput

    1–200 items

  • documentDiscountDiscount or nulloptional
  • memostring or nulloptional

    up to 2000 characters

  • footerstring or nulloptional

    up to 2000 characters

  • paymentUrlstring or nulloptional

    up to 2000 characters · pattern ^https:\/\/.*

ScheduleDto

  • idstring
  • namestring
  • statusstring · ScheduleStatus

    One of: active paused cancelled completed

  • contactIdstring
  • contactNamestringoptional
  • frequencystring · Frequency

    One of: weekly biweekly monthly quarterly semiannually yearly

  • anchorDatestring · PlainDateString
  • endDatestring · PlainDateString or null
  • termsDaysinteger
  • sendEmailboolean
  • emailTostring or null
  • templateVersioninteger
  • templateRecurringTemplateInputOutput
  • templateTotalstring · DecimalStringoptional
  • lastIssuedIndexinteger or null
  • lastIssuedAtstring or null
  • nextOccurrenceDatestring · PlainDateString or null
  • nextRunAtstring or null
  • pausedAtstring or null
  • createdFromInvoiceIdstring or null
  • occurrencesarray of ScheduleOccurrenceDtooptional
  • catchUparray of ScheduleOccurrenceDtooptional
  • versioninteger
  • createdAtstring

ScheduleOccurrenceDto

  • indexinteger
  • datestring · PlainDateString
  • invoiceIdstring or null
  • invoiceNumberstring or null
  • invoiceStatusstring or null

ScheduleStatus

string

One of: active paused cancelled completed

Uuid

string (uuid)