Journal Entries

Manual journals let you adjust the general ledger without flowing through invoices, purchases, or automated workflows. Use these endpoints to inspect the entries Naqood generates automatically, import data from other systems, and attach supporting evidence for audits.

Prerequisites

• A Naqood API secret or OAuth-issued secret scoped to the target organization
• The organization slug for every request
• A role that grants the Journal permission set (JOURNAL_MANAGE)

Journal entry shape

JournalEntry objects expose both the requested payload (lines) and the resolved postings (transactions). Key properties include:

Field	Type	Notes
id	ID!	Stable identifier used by update/void operations.
number	Int	Auto-incremented per fiscal year. null for draft entries.
date	Date!	Posting date that determines the fiscal period.
type	JournalEntryType!	journalEntry, bankEntry, cashEntry, debitNote, etc.
description	String!	Freeform memo shown in the UI and exported reports.
lines	[JSONObject!]	Original lines provided at creation time.
transactions	[JSONObject!]!	Fully resolved ledger postings (after VAT and multi-currency logic).
invoiceId	ID	Present when the entry belongs to an invoice.
purchaseId	ID	Present when the entry belongs to a purchase/bill.
docs	[JSONObject!]	Attached receipts or other documents (see Documents).
createdAt	Timestamp!	Audit timestamp.
updatedAt	Timestamp!	Audit timestamp.

Fetch a single journal entry

query JournalEntry($journalEntryID: ID!) {
  journalEntry(journalEntryID: $journalEntryID)
}

The resolver returns the raw journal entry as a JSON object so you can inspect every property (lines, transactions, linked docs, etc.).

List journal entries

query JournalEntries(
  $slug: Slug!
  $offset: Int
  $limit: Int
  $orderBy: OrderByInput
  $filter: JSONObject
) {
  organization(slug: $slug) {
    journalEntries(
      offset: $offset
      limit: $limit
      orderBy: $orderBy
      filter: $filter
    ) {
      count
      entries
    }
  }
}

• limit is capped at 50 per request.
• Filters accept the standard operators (equalTo, greaterThan, between, and/or, etc.) and the same field names you see in the UI. Common filters include date, type, contactId, and number.
• Each entry contains pre-fetched transactions, docs, and contact details for quick rendering.

Create manual journal entries

Use createJournalEntries to post one or many manual entries in a single mutation. Naqood automatically balances the lines, enforces currency rules, and assigns sequential numbers per fiscal year.

mutation CreateManualJournals($input: CreateJournalEntriesInput!) {
  createJournalEntries(input: $input)
}

CreateJournalEntriesInput fields:

Field	Required	Notes
slug	✅	Organization receiving the journals.
journalEntries	✅	Array of entry payloads (see below).

Each journal entry object supports:

Field	Required	Notes
date	✅	Posting date; fiscal year is derived automatically.
type	Optional	Defaults to journalEntry.
description	✅	Entry-level memo displayed in reports.
contactId	Optional	Link the entry to an existing contact.
invoiceId	Optional	Tie the entry to an invoice (for example credit notes).
purchaseId	Optional	Tie the entry to a purchase/bill.
docs	Optional	Array of Doc IDs to attach immediately.
lines	✅	Array of JournalEntryLineInput objects.

JournalEntryLineInput fields:

Field	Required	Notes
description	✅	Line memo.
amount	✅	Decimal string. Positive/negative determines the account direction.
accountId	✅	Ledger account to debit/credit.
accountVatId	Optional	Applies VAT logic and generates additional VAT transactions.
contraAccountId	Optional	Creates a matching contra posting; useful for quick two-sided entries.
contraAccountVatId	Optional	VAT code for the contra posting.
currency	Optional	Defaults to the organization currency. Provide exchangeRate when overriding.
exchangeRate	Optional	Required whenever currency differs from the org currency.
purchaseLineId / invoiceLineItemId / fixedAssetLineId	Optional	Use when mirroring system-generated entries.

The mutation returns an array of newly created journal entry IDs in the same order you submitted the payload. Entries are automatically numbered after they are committed; drafts (with draft: true) return null numbers until finalized.

Update a journal entry

mutation UpdateJournalEntry($input: UpdateJournalEntryInput!) {
  updateJournalEntry(input: $input)
}

• Only manual entries can be updated. System-generated journals from invoices, purchases, or payroll remain read-only.
• You must supply the complete replacement lines array; omitted lines are removed.
• Naqood recalculates transactions and enforces balancing before committing.

Void a journal entry

mutation VoidJournalEntry($input: VoidJournalEntryInput!) {
  voidJournalEntry(input: $input)
}

Provide the journalEntryId plus a description explaining why the entry was voided. Naqood creates the necessary reversing postings so history remains intact while downstream balances stay correct.

Attach supporting documents

mutation AddJournalEntryDocs($input: AddJournalEntryDocsInput!) {
  addJournalEntryDocs(input: $input)
}

Use this mutation to append doc IDs you previously uploaded via the Documents API. Attachments appear inside the Naqood UI, exports, and the journal entry payload returned by queries.

With these operations you can run a full close process from external systems—import batch journals, correct mistakes, link backing evidence, and audit the ledger directly through the API.