GraphQL Queries

This document provides a comprehensive reference of all GraphQL queries available in Crane Ledger's API. Each query includes parameter descriptions, return types, and practical examples.

Organization Queries

organization

Get the current organization based on your API key.

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

Parameters: None (uses API key context)

Return Type: OrganizationNode

Authentication: Required

Credits: 0 (free)

Example Response:

{
  "data": {
    "organization": {
      "id": "org_1234567890abcdef",
      "name": "Acme Corporation",
      "baseCurrency": {
        "code": "USD",
        "name": "US Dollar",
        "symbol": "$"
      },
      "isRoot": true,
      "creditsRemaining": 1500,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

organizationById

Get a specific organization by ID.

query GetOrganizationById($organizationId: ID!) {
  organizationById(id: $organizationId) {
    id
    name
    baseCurrency {
      code
      name
    }
    parentOrganizationId
    metadata
  }
}

Parameters:

  • id: ID! - Organization ID to retrieve

Return Type: OrganizationNode

Authentication: Required

Credits: 0 (free)

Example:

query GetSpecificOrg {
  organizationById(id: "org_1234567890abcdef") {
    id
    name
  }
}

Account Queries

account

Get a specific account by ID.

query GetAccount($accountId: ID!) {
  account(id: $accountId) {
    id
    code
    name
    accountType
    status
    balance {
      amount
      formatted
      currency {
        code
        symbol
      }
    }
    transactions(limit: 10) {
      id
      description
      amount
      date
    }
    createdAt
  }
}

Parameters:

  • id: ID! - Account ID to retrieve

Return Type: AccountNode

Authentication: Required

Credits: 0 (free)

Example Response:

{
  "data": {
    "account": {
      "id": "act_1234567890abcdef",
      "code": "1001",
      "name": "Operating Cash",
      "accountType": "ASSET",
      "status": "ACTIVE",
      "balance": {
        "amount": 25000.00,
        "formatted": "$25,000.00",
        "currency": {
          "code": "USD",
          "symbol": "$"
        }
      },
      "transactions": [
        {
          "id": "txn_1234567890abcdef",
          "description": "Cash sale",
          "amount": 250.00,
          "date": "2024-01-15T00:00:00Z"
        }
      ],
      "createdAt": "2024-01-01T00:00:00Z"
    }
  }
}

Transaction Queries

transaction

Get a specific transaction by ID.

query GetTransaction($transactionId: ID!) {
  transaction(id: $transactionId) {
    id
    description
    date
    status
    amount
    currency {
      code
      name
    }
    entries {
      id
      accountId
      entryType
      amount
      currency {
        code
      }
      baseAmount
      description
      reference
    }
    createdAt
    updatedAt
  }
}

Parameters:

  • id: ID! - Transaction ID to retrieve

Return Type: TransactionNode

Authentication: Required

Credits: 0 (free)

Example:

query GetSpecificTransaction {
  transaction(id: "txn_1234567890abcdef") {
    id
    description
    entries {
      accountId
      entryType
      amount
      description
    }
  }
}

Contact Queries

contact

Get a specific contact by ID.

query GetContact($contactId: ID!) {
  contact(id: $contactId) {
    id
    name
    contactType
    email
    phone
    taxId
    billingAddress
    billingCity
    billingState
    billingPostalCode
    billingCountry
    transactions(limit: 5) {
      id
      description
      amount
      date
    }
    invoices {
      id
      invoiceNumber
      total
      status
    }
    bills {
      id
      billNumber
      total
      status
    }
    createdAt
  }
}

Parameters:

  • id: ID! - Contact ID to retrieve

Return Type: ContactNode

Authentication: Required

Credits: 0 (free)

Document Queries

invoice

Get a specific invoice by ID.

query GetInvoice($invoiceId: ID!) {
  invoice(id: $invoiceId) {
    id
    invoiceNumber
    contactId
    invoiceDate
    dueDate
    status
    subtotal
    taxAmount
    total
    currency {
      code
      name
    }
    items {
      id
      description
      quantity
      unitPrice
      lineTotal
      taxAmount
    }
    notes
    payments {
      id
      amount
      paymentDate
      paymentMethod
      reference
    }
    pdfUrl
    createdAt
  }
}

Parameters:

  • id: ID! - Invoice ID to retrieve

Return Type: InvoiceNode

Authentication: Required

Credits: 0 (free)

bill

Get a specific bill by ID.

query GetBill($billId: ID!) {
  bill(id: $billId) {
    id
    billNumber
    contactId
    billDate
    dueDate
    status
    subtotal
    taxAmount
    total
    currency {
      code
      name
    }
    items {
      id
      description
      quantity
      unitPrice
      lineTotal
      taxAmount
    }
    notes
    payments {
      id
      amount
      paymentDate
      paymentMethod
      reference
    }
    pdfUrl
    createdAt
  }
}

Parameters:

  • id: ID! - Bill ID to retrieve

Return Type: BillNode

Authentication: Required

Credits: 0 (free)

System Queries

currencies

Get list of all supported currencies.

query GetCurrencies {
  currencies {
    code
    name
    symbol
    decimalPlaces
  }
}

Parameters: None

Return Type: [CurrencyNode!]!

Authentication: Required

Credits: 0 (free)

Example Response:

{
  "data": {
    "currencies": [
      {
        "code": "USD",
        "name": "US Dollar",
        "symbol": "$",
        "decimalPlaces": 2
      },
      {
        "code": "EUR",
        "name": "Euro",
        "symbol": "€",
        "decimalPlaces": 2
      },
      {
        "code": "JPY",
        "name": "Japanese Yen",
        "symbol": "¥",
        "decimalPlaces": 0
      }
    ]
  }
}

Complex Query Examples

Organization Dashboard

Get comprehensive organization overview with related data.

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

    # Recent financial activity
    recentTransactions(limit: 10) {
      id
      description
      amount
      currency {
        code
      }
      date
      status
    }

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

    # Financial reports
    trialBalance {
      generatedAt
      totalDebits
      totalCredits
      accounts {
        accountCode
        accountName
        netBalance
      }
    }

    balanceSheet {
      generatedAt
      totalAssets
      totalLiabilities
      totalEquity
      assets {
        accountName
        balance
      }
      liabilities {
        accountName
        balance
      }
      equity {
        accountName
        balance
      }
    }

    incomeStatement {
      generatedAt
      totalRevenue
      totalExpenses
      netIncome
      revenue {
        accountName
        amount
      }
      expenses {
        accountName
        amount
      }
    }

    # Business entities
    contacts {
      id
      name
      contactType
      email
    }

    invoices {
      id
      invoiceNumber
      total
      status
      dueDate
    }

    bills {
      id
      billNumber
      total
      status
      dueDate
    }
  }
}

Credits: ~15 (includes report generation)

Account Analysis

Get detailed account information with transaction history.

query GetAccountAnalysis($accountId: ID!) {
  account(id: $accountId) {
    id
    code
    name
    accountType
    status
    description

    # Current balance
    balance {
      amount
      formatted
      currency {
        code
        name
      }
    }

    # Transaction history
    transactions(limit: 50) {
      id
      description
      amount
      currency {
        code
      }
      date
      status

      # Journal entries affecting this account
      entries {
        entryType
        amount
        baseAmount
        description
        reference
      }
    }

    createdAt
    updatedAt
  }
}

Credits: 0 (free)

Customer Financial Overview

Get complete financial picture for a specific customer.

query GetCustomerOverview($contactId: ID!) {
  contact(id: $contactId) {
    id
    name
    contactType
    email
    phone
    taxId

    # Transaction history with this contact
    transactions(limit: 20) {
      id
      description
      amount
      currency {
        code
      }
      date
      status
    }

    # All invoices for this customer
    invoices {
      id
      invoiceNumber
      invoiceDate
      dueDate
      status
      subtotal
      taxAmount
      total
      currency {
        code
      }

      # Line items
      items {
        description
        quantity
        unitPrice
        lineTotal
        taxAmount
      }

      # Payment history
      payments {
        amount
        paymentDate
        paymentMethod
        reference
      }
    }

    # Outstanding bills from this vendor
    bills {
      id
      billNumber
      billDate
      dueDate
      status
      total
      currency {
        code
      }
    }
  }
}

Credits: 0 (free)

Financial Reporting Suite

Generate complete financial reports in single query.

query GetFinancialReports {
  organization {
    # Trial Balance - checks accounting equation
    trialBalance {
      generatedAt
      totalDebits
      totalCredits
      accounts {
        accountCode
        accountName
        accountType
        debitBalance
        creditBalance
        netBalance
      }
    }

    # Balance Sheet - financial position
    balanceSheet {
      generatedAt
      asOfDate
      totalAssets
      totalLiabilities
      totalEquity

      assets {
        accountName
        balance
      }
      liabilities {
        accountName
        balance
      }
      equity {
        accountName
        balance
      }
    }

    # Income Statement - profitability
    incomeStatement {
      generatedAt
      periodStart
      periodEnd
      totalRevenue
      totalExpenses
      netIncome

      revenue {
        accountName
        amount
      }
      expenses {
        accountName
        amount
      }
    }
  }
}

Credits: ~15 (includes report generation)

Query Optimization

Use Fragments for Reusable Fields

fragment AccountFields on AccountNode {
  id
  code
  name
  accountType
  balance {
    formatted
  }
}

fragment TransactionFields on TransactionNode {
  id
  description
  amount
  date
  status
}

query GetAccountsAndTransactions {
  organization {
    accounts {
      ...AccountFields
      transactions(limit: 5) {
        ...TransactionFields
      }
    }
  }
}

Limit Related Data

# ✅ Good - Limited related data
query EfficientQuery {
  organization {
    accounts {
      id
      name
      balance {
        formatted
      }
      transactions(limit: 10) {
        id
        description
        amount
      }
    }
  }
}

# ❌ Bad - Excessive related data
query InefficientQuery {
  organization {
    accounts {
      # Gets ALL transactions for EACH account
      transactions {
        id
        description
        amount
        entries {
          description
          amount
          account {
            name
            code
          }
        }
      }
    }
  }
}

Use Aliases for Multiple Similar Queries

query GetMultipleAccounts {
  cashAccount: account(id: "act_1001") {
    id
    name
    balance { formatted }
  }

  revenueAccount: account(id: "act_4001") {
    id
    name
    balance { formatted }
  }

  expenseAccount: account(id: "act_5001") {
    id
    name
    balance { formatted }
  }
}

Error Handling

Authentication Errors

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Permission Errors

{
  "errors": [
    {
      "message": "Access denied to organization",
      "extensions": {
        "code": "FORBIDDEN"
      }
    }
  ]
}

Not Found Errors

{
  "errors": [
    {
      "message": "Account not found: act_invalid_id",
      "extensions": {
        "code": "NOT_FOUND"
      }
    }
  ]
}

Validation Errors

{
  "errors": [
    {
      "message": "Variable 'accountId' of type 'ID!' is required",
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ]
}

Introspection Queries

Schema Discovery

query DiscoverSchema {
  __schema {
    types {
      name
      description
      kind
      fields {
        name
        description
        type {
          name
          kind
        }
        args {
          name
          description
          type {
            name
            kind
          }
        }
      }
    }
  }
}

Type Information

query GetTypeInfo($typeName: String!) {
  __type(name: $typeName) {
    name
    description
    kind
    fields {
      name
      description
      type {
        name
        kind
        ofType {
          name
          kind
        }
      }
      args {
        name
        description
        type {
          name
          kind
        }
        defaultValue
      }
    }
  }
}

Example:

query GetAccountType {
  __type(name: "AccountNode") {
    name
    fields {
      name
      type {
        name
        kind
      }
    }
  }
}

Performance Considerations

Credit Costs

  • Simple queries: 0 credits (organization info, basic lookups - free)
  • Complex queries: 0 credits (with resolvers - free)
  • Report queries: 5 credits each (financial calculations)
  • Multiple resolvers: No additional cost for read operations

Response Size

Large result sets can impact performance:

# ✅ Good - Paginated
query GetRecentTransactions {
  organization {
    recentTransactions(limit: 50) {
      id
      description
      amount
    }
  }
}

# ❌ Bad - Potentially huge response
query GetAllTransactions {
  organization {
    # Could return thousands of records
    recentTransactions(limit: 10000) {
      id
      description
      amount
      entries {
        description
        amount
      }
    }
  }
}

Caching Strategy

// Cache static data
const currencies = await client.query({
  query: gql`query { currencies { code name symbol } }`
});

// Cache organization info (changes infrequently)
const orgInfo = await client.query({
  query: gql`query { organization { id name baseCurrency { code } } }`
});

GraphQL queries in Crane Ledger provide flexible, efficient access to your accounting data. Use the query reference above to construct powerful queries that fetch exactly the data you need in single requests.

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.