POST
Create a recurring entry (organization)
Organization space Accounting module For: Accountant · Permission: recurring_entries.create, journal_entries.create Conditions
  • The accounting module must be included in the plan of the organization.
  • In the organization space the caller needs an accounting access grant on the book named in the URL.
  • The caller needs both the recurring_entries.create and the journal_entries.create permissions, because a template posts entries unattended.
  • The book must be set up for accounting (it must have at least one journal).
  • journal_id must be a journal of the selected book.
  • There must be at least two lines with distinct accounts, positive whole amounts, equal total debits and credits, and postable accounts of the book.
  • frequency must be monthly, quarterly or yearly, and day_of_month a whole number from 1 to 31.
  • end_date, when sent, must not be before start_date.
  • start_date must not be before the start of the earliest open fiscal year of the book.
What else happens
  • Creates the template with status active, the schedule computed from start_date, frequency and day_of_month (first occurrence on or after the start date) and the creator recorded.
  • Posts nothing immediately. The nightly job later posts one journal entry for each due occurrence (catching up a late template, up to 120 occurrences per run), in the chosen journal, with the label as description, source type recurring_entry and no author. An occurrence already posted is never posted twice.
  • An occurrence falling in a closed period is skipped; one refused for another business reason (closed account, declared VAT) is retried on the next run.
Part of Record and correct entries.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

book
string
required

Identifier of the accounting book (a 27-character KSUID): the organization itself or one of its companies. The caller must hold an accounting access grant on it.

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: id, owner_type, label, journal_id, frequency, day_of_month, start_date, end_date, next_run_on, last_run_on, lines, status, created_by, created_by_type, created_at, updated_at.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: journal.

Response

Resource (only with response=resource).

id

Identifier of the recurring entry template (27-character KSUID).

owner_type

Kind of book the template belongs to: organization, company or client.

label

Name of the template; it becomes the description of each entry it posts.

journal_id

Identifier of the journal the entries are posted in (27-character KSUID).

journal
object

The journal. Present only when requested with include=journal and the caller holds the journals.retrieve permission.

frequency

How often the entry is posted: monthly, quarterly (every 3 months) or yearly (every 12 months).

day_of_month
integer

Day of the month of each occurrence, from 1 to 31; in shorter months the last day of the month is used.

start_date

Date from which occurrences are due (YYYY-MM-DD).

end_date

Date after which no occurrence is posted (YYYY-MM-DD); null when the schedule has no end.

next_run_on

Date of the next occurrence to post (YYYY-MM-DD).

last_run_on

Date of the latest occurrence posted (YYYY-MM-DD); null when none has been posted yet.

lines
any[]

Lines posted at each occurrence, as entered: objects with accounting_account_id, direction (debit or credit), amount (whole number in minor units) and label.

status

State of the template: active (posts on schedule), paused (temporarily not posting) or finished (the next occurrence is past the end date).

created_by

Identifier of the member or agent account that created the template; null when unknown.

created_by_type

Kind of the creator; null when unknown.

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).