Organizations

Organizations are the foundation of Crane Ledger's multi-tenant architecture. They represent separate business entities with their own financial data, chart of accounts, and billing. Organizations can be structured hierarchically to support complex business relationships like parent companies, subsidiaries, and client isolation.

Organization Types

Master Organizations

Master organizations are the root entities in Crane Ledger's hierarchy. They:

• Control billing for themselves and their sub-organizations
• Store credits in a unified pool shared across the hierarchy
• Manage billing settings like auto-recharge and payment methods
• Can have unlimited sub-organizations for different business units or clients

{
  "id": "org_1234567890abcdef",
  "name": "Acme Corporation",
  "is_root": true,
  "parent_organization_id": null,
  "stripe_customer_id": "cus_xxxxxxxxxxxxxxxx",
  "base_currency": "USD"
}

Sub-Organizations

Sub-organizations are child entities that belong to a master organization. They:

• Share billing with their parent (master organization pays for all sub-orgs)
• Have isolated data (unless configured for data sharing)
• Inherit settings like base currency from their parent
• Can be organized hierarchically (sub-orgs can have their own sub-orgs)

{
  "id": "org_abcdef1234567890",
  "name": "Acme Europe GmbH",
  "is_root": false,
  "parent_organization_id": "org_1234567890abcdef",
  "relationship_type": "owned",
  "billing_type": "shared"
}

Data Sharing Relationships

Owned Relationships (Consolidated Data)

Owned sub-organizations share financial data with their parent for consolidated reporting:

• Shared financial data - transactions from sub-orgs appear in parent reports
• Consolidated reporting - balance sheets, income statements include all entities
• Unified audit trail - all activities tracked across the hierarchy
• Perfect for: Corporate groups, subsidiaries, business units

Corporate HQ (Master)
├── US Division (Owned - consolidated)
├── Europe Division (Owned - consolidated)
│   └── Germany Branch (Owned - consolidated)
└── Asia Division (Owned - consolidated)

Linked Relationships (Isolated Data)

Linked sub-organizations maintain complete data isolation:

• Separate financial data - no data sharing between organizations
• Independent reporting - each org has its own financial statements
• Client isolation - perfect for accounting firms serving multiple clients
• Perfect for: Professional services, client management, separate legal entities

Accounting Firm (Master)
├── Client A (Linked - isolated)
├── Client B (Linked - isolated)
└── Client C (Linked - isolated)

Billing

All sub-organizations use shared billing with the master organization's credit pool:

• Unified credit pool - all API calls consume credits from the master account
• Single payment method - billing managed at the master level
• Cost allocation - track usage per organization for internal billing
• Auto-recharge - configured once at the master level

This ensures seamless API key management across the entire organization hierarchy. The master organization is always responsible for billing, regardless of whether sub-organizations have isolated or shared data.

Organization Hierarchy Benefits

For Accounting Firms

Tax & Accounting LLP (Master)
├── Client A Corp (Linked - isolated)
├── Client B LLC (Linked - isolated)
│   ├── B's US Operations (Owned - consolidated)
│   └── B's Canadian Branch (Owned - consolidated)
└── Firm's Internal Books (Linked - isolated)

Benefits:

• Client data isolation - each client's data completely separate
• Firm oversight - master account can monitor usage and billing
• Consolidated firm reporting - track all client work in firm books
• Flexible per-client features - different configurations per client

For Real Estate Companies

Real Estate Investment Group (Master)
├── Property A LLC (Owned - consolidated)
├── Property B LLC (Owned - consolidated)
├── Management Company (Owned - consolidated)
└── Construction Division (Linked - isolated)

Benefits:

• Consolidated financials - see all properties in one report
• Individual property tracking - separate books per property
• Management fee tracking - dedicated org for management operations
• Construction isolation - separate books for construction projects

For Enterprise Corporations

Global Corporation (Master)
├── US Operations (Owned - consolidated)
│   ├── West Coast Division (Owned - consolidated)
│   └── East Coast Division (Owned - consolidated)
├── European Subsidiary (Linked - isolated)
└── Asian Joint Venture (Linked - isolated)

Benefits:

• Global consolidation - unified corporate reporting
• Regional autonomy - subsidiaries manage their own operations
• Currency management - different base currencies per region
• Tax compliance - separate books for different jurisdictions

Creating Organizations

Master Organization Creation

Master organizations are created through the /accounts/master endpoint:

POST /accounts/master
{
  "organization_name": "My Company",
  "user_github_id": "12345678",
  "user_email": "user@company.com",
  "base_currency_code": "USD"
}

Response:

{
  "id": "org_1234567890abcdef",
  "name": "My Company",
  "is_root": true,
  "credits_remaining": 500,
  "stripe_customer_id": "cus_xxxxxxxxxxxxxxxx"
}

Sub-Organization Creation

Sub-organizations are created under existing master organizations:

POST /accounts/sub
{
  "parent_organization_id": "org_1234567890abcdef",
  "organization_name": "European Division",
  "relationship_type": "owned",
  "billing_type": "shared",
  "base_currency_code": "EUR"
}

Managing Organization Hierarchy

Listing Your Organizations

GET /organizations
Authorization: Bearer cl_live_your_api_key

Returns all organizations you have access to, including hierarchical relationships.

Checking Data Sharing

GET /organizations/can-share-data/org1_id/org2_id

Determines if two organizations can share financial data based on their relationship.

Getting Billing Organization

GET /organizations/{org_id}/billing-organization

Returns the organization responsible for billing (useful for sub-organizations).

Best Practices

Choose the Right Structure

1. Start with a master organization for your primary business entity
2. Use owned relationships when you need consolidated financial reporting
3. Use linked relationships when you need complete data isolation
4. Billing is always shared - the master organization pays for all sub-organizations

Naming Conventions

• Use descriptive names that clearly identify the organization purpose
• Include location/division information in sub-organization names
• Consider legal entity names for tax and compliance purposes

Access Control

• API keys are organization-scoped - they only access their assigned organization
• Master organization access doesn't automatically grant sub-organization access
• Create separate API keys for different organizations as needed

Migration and Restructuring

Changing Relationship Types

Organization relationships can be updated, but consider the implications:

• Owned → Linked: Removes data sharing, historical data remains accessible
• Linked → Owned: Enables data sharing, but requires careful consideration of existing data
• Billing: Always shared with master organization - cannot be changed

Moving Organizations

Organizations cannot be moved between different master organizations. Instead:

1. Create a new sub-organization under the desired parent
2. Migrate data programmatically using the API
3. Update integrations to use the new organization ID
4. Deactivate the old organization when migration is complete

Common Patterns

Multi-Client Accounting Platform

// Create client organization
const clientOrg = await api.createSubOrganization({
  parentId: firmMasterOrg.id,
  name: client.name,
  relationshipType: 'linked', // Data isolation
  billingType: 'shared'       // Firm pays
});

// Create client-specific API key
const apiKey = await api.createApiKey({
  organizationId: clientOrg.id,
  name: `Client: ${client.name}`,
  permissions: ['read', 'write']
});

Enterprise Division Structure

// Create divisions under corporate master
const divisions = await Promise.all([
  api.createSubOrganization({
    parentId: corporateMaster.id,
    name: 'Sales Division',
    relationshipType: 'owned',   // Consolidated reporting
    billingType: 'shared'        // Corporate billing
  }),
  api.createSubOrganization({
    parentId: corporateMaster.id,
    name: 'Manufacturing Division',
    relationshipType: 'owned',
    billingType: 'shared'
  })
]);

• ✨ For LLMs/AI assistants: Read our structured API reference