Write a balanced journal entry: an accrual, a reclassification, an adjustment

POST

/v1/entities/{entity_id}/entries

const url = 'https://example.com/v1/entities/example/entries';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"legs":[{"account":"example","commodity":"example","amount":"-12.00","memo":"example","tax_code":"example"}],"dt":"example","narration":"example","reason":"example","origin":"example","code":"example","comment":"example","tags":[["example"]],"id":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/entities/example/entries \
  --header 'Content-Type: application/json' \
  --data '{ "legs": [ { "account": "example", "commodity": "example", "amount": "-12.00", "memo": "example", "tax_code": "example" } ], "dt": "example", "narration": "example", "reason": "example", "origin": "example", "code": "example", "comment": "example", "tags": [ [ "example" ] ], "id": "example" }'

Post one balanced journal entry that no bank statement line stands behind.

An invoice raised, a payroll accrued, a quarter’s withholding moved from one liability to the next: each is an economic event on a date with no cash row behind it on that date. The other entry writes either hang an entry off a statement line or post a converted set as one unit (POST /batches). This one is for a single entry, and without it a period’s profit could only ever be its cash flow.

The entry takes the ordinary posting path (drafted and sealed in one transaction), so it meets the same balance rule, the same account, currency and precision rules and the same period lock as a line classified off a statement. It takes any number of legs from two upward, as a four-leg payroll accrual needs. It comes back posted and is never edited: POST /entries/{id}/correct restates it and POST /entries/{id}/reverse withdraws it.

Parameters

Path Parameters

entity_id

required

Entity Id

The entity this path is relative to

string

The entity this path is relative to

Request Body^required

application/json

JournalEntrySubmission

Write one balanced entry directly into the books: an accrual, a reclassification, an adjustment.

This is how the books record what a bank statement does not: an invoice raised, a payroll accrued, a quarter’s withholding moved from one liability to the next. Without it a ledger can only record cash, and a period’s profit is not a cash-flow figure.

The entry is posted when it is written; there is no approval step. A posted entry is never edited. It is corrected with POST /entries/{id}/correct (a mirror that cancels it plus a replacement, in one transaction) or withdrawn with POST /entries/{id}/reverse.

reason is required and is kept verbatim on the append-only audit action. narration is what the entry reads as in every report and export; reason is why it was written.

object

legs

required

Legs

Every leg of the entry; they net to zero per commodity

Array<object>

>= 2 items

EntryLeg

One leg of a manual journal entry: an account, a currency and a signed amount.

Unlike a line booking’s legs, these are the whole entry. No cash leg is supplied for you, because there is no statement line behind this entry. Two legs or more, netting to zero per commodity.

object

account

required

Account

Account path (preferred) or stable account id

string

>= 1 characters <= 255 characters

commodity

required

Commodity

string

>= 1 characters <= 64 characters

amount

required

Amount

Signed decimal amount in whole commodity units; never a JSON number

string

memo

Any of:

string
null

string

<= 4096 characters

tax_code

Any of:

string
null

string

<= 255 characters

required

The entry date, YYYY-MM-DD; a date in a closed month is refused

string

narration

required

Narration

What this entry reads as in the books

string

>= 1 characters <= 4096 characters

reason

required

Reason

Why it is being written; kept in the record

string

>= 1 characters

origin

Any of:

string
null

string

code

Any of:

string
null

string

<= 255 characters

comment

Any of:

string
null

string

<= 4096 characters

tags

Any of:

Array<Array<string>>
null

Array<Array<string>>

Any of:

string
null

string

Responses

201

Successful Response

application/json

JournalEntryResponse

object

entity_id

required

Entity Id

string

legal_name

required

Legal Name

string

base_currency

required

Base Currency

string

snapshot_seq

required

Snapshot Seq

integer

entry

required

Entry

object

required

string

required

string

narration

required

Narration

string

status

required

Status

string

origin

required

Origin

string

version

required

Version

integer

code

required

Code

string

comment

required

Comment

string

tags

required

Tags

Array<Array<string>>

created_at

required

Created At

string

created_by

required

Created By

string

postings

required

Postings

Array<object>

Posting

object

required

string

seq

required

Seq

integer

account_id

required

Account Id

string

account_path

required

Account Path

string

commodity

required

Commodity

string

amount_micros

required

Amount Micros

Signed integer micro-units (millionths) as a base-10 string; never a JSON number.

string

/^-?(0|[1-9][0-9]*)$/

memo

required

Any of:

string
null

string

tax_code

required

Any of:

string
null

string

links

required

Links

object

key

additional properties

string

version

required

Version

integer

audit_seq

required

Audit Seq

The entry.posted audit action’s event sequence; see /entries/{id}/events

integer

links

required

Links

object

key

additional properties

string

Example

{
  "entry": {
    "postings": [
      {
        "amount_micros": "-12000000"
      }
    ]
  }
}

400

Bad Request

application/json

ErrorEnvelope

object

error

required

ErrorBody

object

code

required

Code

string

message

required

Message

string

retryable

required

Retryable

boolean

details

required

Details

Array<object>

object

key

additional properties

any

request_id

Any of:

string
null

string

next_action

Any of:

object
null

object

key

additional properties

any

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "retryable": true,
    "details": [
      {}
    ],
    "request_id": "example",
    "next_action": {}
  }
}

401

Unauthorized

application/json

ErrorEnvelope

object

error

required

ErrorBody

object

code

required

Code

string

message

required

Message

string

retryable

required

Retryable

boolean

details

required

Details

Array<object>

object

key

additional properties

any

request_id

Any of:

string
null

string

next_action

Any of:

object
null

object

key

additional properties

any

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "retryable": true,
    "details": [
      {}
    ],
    "request_id": "example",
    "next_action": {}
  }
}

403

Forbidden

application/json

ErrorEnvelope

object

error

required

ErrorBody

object

code

required

Code

string

message

required

Message

string

retryable

required

Retryable

boolean

details

required

Details

Array<object>

object

key

additional properties

any

request_id

Any of:

string
null

string

next_action

Any of:

object
null

object

key

additional properties

any

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "retryable": true,
    "details": [
      {}
    ],
    "request_id": "example",
    "next_action": {}
  }
}

404

Not Found

application/json

ErrorEnvelope

object

error

required

ErrorBody

object

code

required

Code

string

message

required

Message

string

retryable

required

Retryable

boolean

details

required

Details

Array<object>

object

key

additional properties

any

request_id

Any of:

string
null

string

next_action

Any of:

object
null

object

key

additional properties

any

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "retryable": true,
    "details": [
      {}
    ],
    "request_id": "example",
    "next_action": {}
  }
}

409

Conflict

application/json

ErrorEnvelope

object

error

required

ErrorBody

object

code

required

Code

string

message

required

Message

string

retryable

required

Retryable

boolean

details

required

Details

Array<object>

object

key

additional properties

any

request_id

Any of:

string
null

string

next_action

Any of:

object
null

object

key

additional properties

any

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "retryable": true,
    "details": [
      {}
    ],
    "request_id": "example",
    "next_action": {}
  }
}

412

Precondition Failed

application/json

ErrorEnvelope

object

error

required

ErrorBody

object

code

required

Code

string

message

required

Message

string

retryable

required

Retryable

boolean

details

required

Details

Array<object>

object

key

additional properties

any

request_id

Any of:

string
null

string

next_action

Any of:

object
null

object

key

additional properties

any

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "retryable": true,
    "details": [
      {}
    ],
    "request_id": "example",
    "next_action": {}
  }
}

422

Unprocessable Content

application/json

ErrorEnvelope

object

error

required

ErrorBody

object

code

required

Code

string

message

required

Message

string

retryable

required

Retryable

boolean

details

required

Details

Array<object>

object

key

additional properties

any

request_id

Any of:

string
null

string

next_action

Any of:

object
null

object

key

additional properties

any

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "retryable": true,
    "details": [
      {}
    ],
    "request_id": "example",
    "next_action": {}
  }
}

500

Internal Server Error

application/json

ErrorEnvelope

object

error

required

ErrorBody

object

code

required

Code

string

message

required

Message

string

retryable

required

Retryable

boolean

details

required

Details

Array<object>

object

key

additional properties

any

request_id

Any of:

string
null

string

next_action

Any of:

object
null

object

key

additional properties

any

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "retryable": true,
    "details": [
      {}
    ],
    "request_id": "example",
    "next_action": {}
  }
}

503

Service Unavailable

application/json

ErrorEnvelope

object

error

required

ErrorBody

object

code

required

Code

string

message

required

Message

string

retryable

required

Retryable

boolean

details

required

Details

Array<object>

object

key

additional properties

any

request_id

Any of:

string
null

string

next_action

Any of:

object
null

object

key

additional properties

any

Example ^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "retryable": true,
    "details": [
      {}
    ],
    "request_id": "example",
    "next_action": {}
  }
}

Write a balanced journal entry: an accrual, a reclassification, an adjustment

Parameters

Path Parameters

Request Bodyrequired

Responses

201

Example

400

Example generated

401

Example generated

403

Example generated

404

Example generated

409

Example generated

412

Example generated

422

Example generated

500

Example generated

503

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated