Journal Categories

Retrieves the journal categories of your company. A category groups journal entries and restricts which entry types may be posted into it — pass its id as journalCategoryId when creating journal entries or drafts.

The default category is returned first, then the rest in creation order. Results are cached for 5 seconds. A change you make through this API clears that cache, so your own writes are visible on your next read.

What each type means

These five are the ones you can post. The entryType column is what you send when creating a journal entry or draft — several spellings map onto one type.

Type	Holds	Posted with
JOURNAL_ENTRY	General ledger entries with no customer or supplier side	entryType: "journal"
SUPPLIER_INVOICE	Bills received from a supplier	entryType: "supplier_invoice" (or the deprecated "invoice")
SUPPLIER_PAYMENT	Money paid out to a supplier	entryType: "supplier_payment" (or the deprecated "payment")
CUSTOMER_INVOICE	Invoices issued to a customer	entryType: "customer_invoice"
CUSTOMER_PAYMENT	Money received from a customer	entryType: "customer_payment"

The remaining six are raised by the platform, not by an API caller. Listing them restricts which of these postings may land in the category; there is no entryType that produces one.

Type	Raised by
CUSTOMER_REMINDER	Reminder fees and interest booked by the dunning process
CURRENCY_REVALUATION	Foreign-currency revaluation
VAT_SETTLEMENT	VAT settlement
SET_OPENING_BALANCE	Opening balances, on company setup and at year end
TRANSFERRED_AMOUNT	The opening-balance transfer posted by the year-end close
YEAR_END_CLOSING	The legacy year-end close

Required Scope

• journal-categories-read

Creates a journal category. Use this to set up the journals a customer posts into — for example one for sales and another for settlements — instead of asking them to create those in the app first.

Request Body

Field	Type	Required	Description
name	string	Yes	Display name (2-100 characters, must be unique within your company)
allowedJournalTypes	string[]	No	Entry types that may be posted into this category. Omit to allow every type.
isDefault	boolean	No	Make this the default category. Defaults to false.

Restricting what can be posted

Omit allowedJournalTypes and the category accepts every type — the same set your company's first category is created with. That is usually what you want for a general-purpose journal.

Send a list to restrict it. An empty array is rejected rather than treated as "allow everything": it would describe a category nothing could ever be posted into, which is never intentional.

What each type means

These five are the ones you can post. The entryType column is what you send when creating a journal entry or draft — several spellings map onto one type.

Type	Holds	Posted with
JOURNAL_ENTRY	General ledger entries with no customer or supplier side	entryType: "journal"
SUPPLIER_INVOICE	Bills received from a supplier	entryType: "supplier_invoice" (or the deprecated "invoice")
SUPPLIER_PAYMENT	Money paid out to a supplier	entryType: "supplier_payment" (or the deprecated "payment")
CUSTOMER_INVOICE	Invoices issued to a customer	entryType: "customer_invoice"
CUSTOMER_PAYMENT	Money received from a customer	entryType: "customer_payment"

The remaining six are raised by the platform, not by an API caller. Listing them restricts which of these postings may land in the category; there is no entryType that produces one.

Type	Raised by
CUSTOMER_REMINDER	Reminder fees and interest booked by the dunning process
CURRENCY_REVALUATION	Foreign-currency revaluation
VAT_SETTLEMENT	VAT settlement
SET_OPENING_BALANCE	Opening balances, on company setup and at year end
TRANSFERRED_AMOUNT	The opening-balance transfer posted by the year-end close
YEAR_END_CLOSING	The legacy year-end close

Examples

A journal that accepts anything:

Code
{
  "name": "Daily"
}

A sales journal restricted to customer postings:

Code
{
  "name": "Sales",
  "allowedJournalTypes": ["CUSTOMER_INVOICE", "CUSTOMER_PAYMENT"],
  "isDefault": false
}

The default category

Your company always has exactly one default. Passing isDefault: true moves the flag off the category that currently holds it. Passing false (or omitting it) leaves the existing default in place.

Error Handling

• Name already taken: JOURNAL_CATEGORY_NAME_ALREADY_EXISTS
• Empty allowedJournalTypes: JOURNAL_CATEGORY_ALLOWED_TYPES_REQUIRED

Required Scope

• journal-categories-write

Updates a journal category. All fields are optional — send only what you want to change; anything you omit is left as it is.

Request Body

Field	Type	Required	Description
name	string	No	New display name (2-100 characters, must be unique within your company)
allowedJournalTypes	string[]	No	Replaces the allowed entry types. Cannot be empty.
isDefault	boolean	No	See below.

Changing the allowed types

The new list replaces the old one, and cannot be empty. Entries already posted into the category are unaffected — the restriction applies to entries posted from now on.

Note this differs from create: omitting the field here leaves the current set alone, whereas omitting it on create means every type. To widen a category back to everything, send the full list.

What each type means

These five are the ones you can post. The entryType column is what you send when creating a journal entry or draft — several spellings map onto one type.

Type	Holds	Posted with
JOURNAL_ENTRY	General ledger entries with no customer or supplier side	entryType: "journal"
SUPPLIER_INVOICE	Bills received from a supplier	entryType: "supplier_invoice" (or the deprecated "invoice")
SUPPLIER_PAYMENT	Money paid out to a supplier	entryType: "supplier_payment" (or the deprecated "payment")
CUSTOMER_INVOICE	Invoices issued to a customer	entryType: "customer_invoice"
CUSTOMER_PAYMENT	Money received from a customer	entryType: "customer_payment"

The remaining six are raised by the platform, not by an API caller. Listing them restricts which of these postings may land in the category; there is no entryType that produces one.

Type	Raised by
CUSTOMER_REMINDER	Reminder fees and interest booked by the dunning process
CURRENCY_REVALUATION	Foreign-currency revaluation
VAT_SETTLEMENT	VAT settlement
SET_OPENING_BALANCE	Opening balances, on company setup and at year end
TRANSFERRED_AMOUNT	The opening-balance transfer posted by the year-end close
YEAR_END_CLOSING	The legacy year-end close

Moving the default

Mark the successor with isDefault: true; that moves the flag off the category that currently holds it, in one call. Clearing the flag with isDefault: false is only accepted when another category is already the default, so a company can never end up without one.

Error Handling

• Category not found: JOURNAL_CATEGORY_NOT_FOUND
• Name already taken: JOURNAL_CATEGORY_NAME_ALREADY_EXISTS
• Empty allowedJournalTypes: JOURNAL_CATEGORY_ALLOWED_TYPES_REQUIRED
• Clearing the only default: JOURNAL_CATEGORY_CANNOT_DELETE_DEFAULT

Required Scope

• journal-categories-write

Deletes a journal category.

Prerequisites

• It must not be the default category. Make another category the default first, then delete this one.
• No unposted entry may still be pointing at it. Move or post those drafts first.

What happens to posted entries

Journal entries already posted into the category keep pointing at it, so history still reads back with the journal it was booked in. The category simply stops appearing in listings and can no longer be posted into.

Error Handling

• Category not found: JOURNAL_CATEGORY_NOT_FOUND
• It is the default: JOURNAL_CATEGORY_CANNOT_DELETE_DEFAULT
• An unposted entry still uses it: JOURNAL_CATEGORY_IN_USE_BY_DRAFT

Required Scope

• journal-categories-write