GraphQL Organizations

This page documents GraphQL operations for managing organizations in Crane Ledger.

Organization Queries

Get Current Organization

Get information about the organization associated with your API key.

query {
  organization {
    id
    name
    baseCurrency {
      code
      name
      symbol
      decimalPlaces
    }
    isRoot
    creditsRemaining
    createdAt
    updatedAt
  }
}

Returns:

  • id: Organization unique identifier
  • name: Organization display name
  • baseCurrency: Base currency for all financial operations
  • isRoot: Whether this is a root billing organization
  • creditsRemaining: Available credit balance
  • createdAt/updatedAt: Timestamps

Get Organization by ID

Get a specific organization (must be your own organization).

query GetOrganization($id: ID!) {
  organizationById(id: $id) {
    id
    name
    baseCurrency {
      code
      name
    }
    creditsRemaining
  }
}

Organization Relationships

Accounts

Get all accounts in the organization's chart of accounts.

query {
  organization {
    accounts {
      id
      code
      name
      accountType
      status
      description
      isSystem
      createdAt
    }
  }
}

Returns:

  • Complete account information for all accounts
  • Includes system accounts and user-created accounts

Recent Transactions

Get the most recent transactions for the organization.

query {
  organization {
    recentTransactions(limit: 10) {
      id
      description
      date
      status
      amount
      currency {
        code
        symbol
      }
      createdAt
    }
  }
}

Parameters:

  • limit: Maximum number of transactions (default: 10, max: 100)

Contacts

Get all contacts (customers, vendors, employees) for the organization.

query {
  organization {
    contacts {
      id
      name
      contactType
      email
      phone
      taxId
      createdAt
    }
  }
}

Returns:

  • All customer, vendor, and employee contacts
  • Contact type indicates relationship

Invoices

Get all sales invoices for the organization.

query {
  organization {
    invoices {
      id
      invoiceNumber
      contactId
      invoiceDate
      dueDate
      status
      subtotal
      taxAmount
      total
      currency {
        code
        symbol
      }
      createdAt
    }
  }
}

Bills

Get all purchase bills for the organization.

query {
  organization {
    bills {
      id
      billNumber
      contactId
      billDate
      dueDate
      status
      subtotal
      taxAmount
      total
      currency {
        code
        symbol
      }
      createdAt
    }
  }
}

Financial Reports

Trial Balance

Generate a trial balance showing all account balances.

query {
  organization {
    trialBalance {
      generatedAt
      accounts {
        accountId
        accountCode
        accountName
        accountType
        debitBalance
        creditBalance
        netBalance
      }
      totalDebits
      totalCredits
    }
  }
}

Returns:

  • Balance for each account
  • Ensures debits = credits (trial balance should balance)

Balance Sheet

Generate a balance sheet report.

query {
  organization {
    balanceSheet {
      generatedAt
      asOfDate
      assets {
        accountId
        accountCode
        accountName
        balance
      }
      liabilities {
        accountId
        accountCode
        accountName
        balance
      }
      equity {
        accountId
        accountCode
        accountName
        balance
      }
      totalAssets
      totalLiabilities
      totalEquity
    }
  }
}

Returns:

  • Assets, liabilities, and equity sections
  • Account balances grouped by type
  • Total for each section

Income Statement

Generate an income statement (profit & loss) report.

query {
  organization {
    incomeStatement {
      generatedAt
      periodStart
      periodEnd
      revenue {
        accountId
        accountCode
        accountName
        amount
      }
      expenses {
        accountId
        accountCode
        accountName
        amount
      }
      totalRevenue
      totalExpenses
      netIncome
    }
  }
}

Returns:

  • Revenue and expense accounts
  • Net income calculation
  • Period-based reporting

Organization Operations

Create Account

Add a new account to the chart of accounts.

mutation CreateAccount($code: String!, $name: String!, $type: AccountType!) {
  createAccount(
    code: $code
    name: $name
    accountType: $type
    description: "Account description"
  ) {
    id
    code
    name
    accountType
    status
    createdAt
  }
}

Required Fields:

  • code: Unique account code (e.g., "1001")
  • name: Account display name
  • accountType: ASSET, LIABILITY, EQUITY, REVENUE, or EXPENSE

Optional Fields:

  • description: Account description

Update Account

Modify an existing account.

mutation UpdateAccount($id: ID!, $name: String, $description: String) {
  updateAccount(
    id: $id
    name: $name
    description: $description
  ) {
    id
    name
    description
    updatedAt
  }
}

Fields: Any combination of code, name, description

Delete Account

Remove an account (only if no transactions exist).

mutation DeleteAccount($id: ID!) {
  deleteAccount(id: $id)
}

Restrictions:

  • Cannot delete accounts with existing transactions
  • Cannot delete system accounts

Create Contact

Add a new contact to the organization.

mutation CreateContact($name: String!, $type: ContactType!, $email: String) {
  createContact(
    name: $name
    contactType: $type
    email: $email
    phone: "+1-555-0123"
    taxId: "123456789"
  ) {
    id
    name
    contactType
    email
    phone
    createdAt
  }
}

Required Fields:

  • name: Contact display name
  • contactType: CUSTOMER, VENDOR, or EMPLOYEE

Optional Fields:

  • email: Email address
  • phone: Phone number
  • taxId: Tax ID or VAT number

Update Contact

Modify an existing contact.

mutation UpdateContact($id: ID!, $email: String, $phone: String) {
  updateContact(
    id: $id
    email: $email
    phone: $phone
  ) {
    id
    name
    email
    phone
    updatedAt
  }
}

Delete Contact

Remove a contact from the organization.

mutation DeleteContact($id: ID!) {
  deleteContact(id: $id)
}

Create Transaction

Record a new journal entry transaction.

mutation CreateTransaction(
  $description: String!
  $date: DateTime!
  $entries: [LedgerEntryInput!]!
) {
  createTransaction(
    description: $description
    date: $date
    entries: $entries
  ) {
    id
    description
    date
    status
    amount
    entries {
      accountId
      entryType
      amount
      description
    }
  }
}

Required Fields:

  • description: Transaction description
  • date: Transaction date
  • entries: Array of debits and credits

LedgerEntryInput:

{
  accountId: "ACT_123"
  entryType: DEBIT
  amount: 100.00
  description: "Optional entry description"
  reference: "Optional reference"
}

Validation:

  • Debits must equal credits
  • All referenced accounts must exist
  • All accounts must belong to organization

Create Invoice

Create a new sales invoice.

mutation CreateInvoice(
  $contactId: ID!
  $invoiceDate: DateTime!
  $dueDate: DateTime!
  $items: [InvoiceItemInput!]!
) {
  createInvoice(
    contactId: $contactId
    invoiceDate: $invoiceDate
    dueDate: $dueDate
    items: $items
    notes: "Invoice notes"
  ) {
    id
    invoiceNumber
    contactId
    invoiceDate
    dueDate
    status
    subtotal
    taxAmount
    total
    items {
      description
      quantity
      unitPrice
      lineTotal
    }
  }
}

Required Fields:

  • contactId: Customer contact ID
  • invoiceDate: Invoice creation date
  • dueDate: Payment due date
  • items: Line items array

InvoiceItemInput:

{
  description: "Product description"
  quantity: 2.0
  unitPrice: 50.00
  itemId: "ITEM_123" // Optional
}

Create Bill

Create a new purchase bill.

mutation CreateBill(
  $contactId: ID!
  $billDate: DateTime!
  $dueDate: DateTime!
  $items: [BillItemInput!]!
) {
  createBill(
    contactId: $contactId
    billDate: $billDate
    dueDate: $dueDate
    items: $items
    notes: "Bill notes"
  ) {
    id
    billNumber
    contactId
    billDate
    dueDate
    status
    subtotal
    taxAmount
    total
    items {
      description
      quantity
      unitPrice
      lineTotal
    }
  }
}

Required Fields:

  • contactId: Vendor contact ID
  • billDate: Bill creation date
  • dueDate: Payment due date
  • items: Line items array

Complex Queries

Organization Overview Dashboard

Get comprehensive organization data in one query.

query GetOrganizationDashboard {
  organization {
    id
    name
    baseCurrency {
      code
      symbol
    }
    creditsRemaining

    # Recent activity
    recentTransactions(limit: 5) {
      id
      description
      amount
      date
      status
    }

    # Account summary
    accounts {
      id
      code
      name
      accountType
      balance {
        formatted
      }
    }

    # Financial position
    trialBalance {
      totalDebits
      totalCredits
    }

    # Outstanding documents
    invoices(where: { status: { eq: SENT } }) {
      id
      invoiceNumber
      total
      dueDate
    }

    bills(where: { status: { eq: RECEIVED } }) {
      id
      billNumber
      total
      dueDate
    }
  }
}

Financial Health Check

Comprehensive financial position query.

query GetFinancialHealth {
  organization {
    name

    # Balance sheet
    balanceSheet {
      totalAssets
      totalLiabilities
      totalEquity
    }

    # Income statement
    incomeStatement {
      totalRevenue
      totalExpenses
      netIncome
    }

    # Working capital
    accounts(
      where: {
        accountType: { in: [ASSET, LIABILITY] }
        code: { startsWith: "1" } # Current assets/liabilities
      }
    ) {
      code
      name
      balance {
        amount
      }
    }
  }
}

Error Handling

Organization Errors

  • NOT_FOUND: Organization not found
  • FORBIDDEN: Access denied to other organizations
  • UNAUTHENTICATED: Invalid API key

Account Errors

  • VALIDATION_ERROR: Invalid account code or type
  • CONFLICT: Account code already exists
  • NOT_FOUND: Account not found

Transaction Errors

  • VALIDATION_ERROR: Unbalanced entries or invalid accounts
  • NOT_FOUND: Referenced accounts not found

Document Errors

  • NOT_FOUND: Contact not found
  • VALIDATION_ERROR: Invalid dates or amounts

Best Practices

Account Code Standards

// Validate account codes
const validateAccountCode = (code, type) => {
  const patterns = {
    ASSET: /^[1-4]\d{3}$/,      // 1000-4999
    LIABILITY: /^[2-3]\d{3}$/,  // 2000-3999
    EQUITY: /^[3]\d{3}$/,       // 3000-3999
    REVENUE: /^[4]\d{3}$/,      // 4000-4999
    EXPENSE: /^[5-9]\d{3}$/     // 5000-9999
  };

  return patterns[type]?.test(code) || false;
};

Transaction Balancing

// Ensure debits equal credits
const validateTransaction = (entries) => {
  const totalDebits = entries
    .filter(e => e.entryType === 'DEBIT')
    .reduce((sum, e) => sum + parseFloat(e.amount), 0);

  const totalCredits = entries
    .filter(e => e.entryType === 'CREDIT')
    .reduce((sum, e) => sum + parseFloat(e.amount), 0);

  return Math.abs(totalDebits - totalCredits) < 0.01; // Allow for rounding
};

Date Validation

// Ensure logical date ordering
const validateDocumentDates = (invoiceDate, dueDate) => {
  const invoice = new Date(invoiceDate);
  const due = new Date(dueDate);

  return due >= invoice; // Due date should be after invoice date
};

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.