Billing & Credits

Crane Ledger uses a transparent, credit-based pricing model designed for developers. All API operations consume credits from your organization's unified pool, with no hidden fees or surprise charges. This guide explains how billing works and how to manage your costs effectively.

🎯 Credit System Overview

Basic Unit

1 Credit = $0.01 USD

Every API operation consumes credits from your organization's credit pool:

• Transparent pricing - Every endpoint shows its credit cost
• Predictable costs - Know exactly what each operation costs
• No overages - Operations are blocked when credits run out
• Real-time tracking - Monitor usage as you go

Organization-Based Billing

Credits are tied to organizations, not users:

{
  "organization_id": "ORG_1234567890abcdef",
  "credits_remaining": 1500,
  "credits_total": 2000,
  "auto_recharge_enabled": true,
  "billing_email": "billing@company.com"
}

Key Benefits:

• Multi-user organizations share credit pools
• Client isolation in accounting firms (separate billing per client)
• Cost allocation for enterprise deployments
• Flexible billing across different business units

💰 Pricing Tiers

Choose the credit package that fits your development needs:

Solo Dev Package

$10.00 - 1,000 Credits

Perfect for individual developers and small projects:

• Cost: $10.00 one-time purchase
• Credits: 1,000 (enough for ~3-6 months of light usage)
• Monthly equivalent: ~$3.35/month
• Use case: Personal projects, prototypes, learning

Builder Package

$50.00 - 5,000 Credits

Ideal for development teams and growing applications:

• Cost: $50.00 one-time purchase
• Credits: 5,000 (sustained development usage)
• Monthly equivalent: ~$16.70/month
• Use case: Development teams, MVPs, production applications

Scale Package

$250.00 - 25,000 Credits

Built for high-volume applications and enterprises:

• Cost: $250.00 one-time purchase
• Credits: 25,000 (heavy usage applications)
• Monthly equivalent: ~$83.40/month
• Use case: Enterprise platforms, high-traffic applications

Enterprise Custom Packages

Need more credits or special terms?

• Volume discounts for large purchases
• Custom credit amounts (50K, 100K, 500K+)
• Enterprise agreements with dedicated support
• Contact sales for custom pricing

📊 Operation Pricing

Free Operations (0 Credits)

These operations don't consume credits:

• All read operations (GET requests, listings, searches)
• Data retrieval (account balances, transaction history, reports)
• System information (health checks, API status)
• Authentication (login, token refresh)

Paid Operations

Core Accounting Operations

Document Management

Business Management

Advanced Features

🔄 Auto-Recharge System

How It Works

Prevent service interruptions with automatic credit replenishment:

1. Low Balance Alert: When credits drop below $4.00 (400 credits)
2. Automatic Recharge: Adds credits to reach $20.00 balance (2,000 credits)
3. Email Notification: Sent when auto-recharge occurs
4. Continued Service: No interruption to your applications

Trigger Conditions

// Auto-recharge triggers when:
credits_remaining <= 400  // $4.00

// Adds credits to reach:
target_balance = 2000     // $20.00

Managing Auto-Recharge

Enable/Disable per Organization:

# Check current setting
GET /organizations/{org_id}/billing

# Enable auto-recharge
PUT /organizations/{org_id}/billing
{
  "auto_recharge_enabled": true
}

# Disable auto-recharge
PUT /organizations/{org_id}/billing
{
  "auto_recharge_enabled": false
}

Benefits:

• Never run out of credits unexpectedly
• Predictable billing cycles
• Per-organization control - different settings for different orgs
• Email alerts - stay informed of usage

🏢 Organization Base Cost

$1.00 Per Organization Per Month

Every active organization incurs a base maintenance cost:

• $1.00/month ($12/year) per organization
• 25 credits/week (prorated daily)
• Automatic deduction from credit balance
• Ensures service availability and system maintenance

What It Covers

The base cost supports:

• System maintenance and infrastructure
• Database storage and backups
• API availability and performance monitoring
• Security updates and compliance
• Customer support infrastructure

Free Organizations

New organizations receive 500 credits ($5.00) upon creation, covering:

• ~2 weeks of base costs
• Initial setup and testing
• Getting started without immediate payment

💳 Payment Methods

Stripe Integration

All billing handled through Stripe for security and compliance:

// Purchase credit package
POST /api/billing/purchase-package
{
  "package": "builder",     // solo_dev, builder, scale
  "organization_id": "ORG_1234567890abcdef"
}

// Response includes Stripe checkout URL
{
  "checkout_url": "https://checkout.stripe.com/...",
  "package": "builder",
  "credits": 5000,
  "amount": 50.00
}

Supported Payment Methods

• Credit Cards (Visa, MasterCard, American Express)
• Debit Cards (all major networks)
• Digital Wallets (Apple Pay, Google Pay)
• Bank Transfers (ACH, wire transfers for large amounts)

Billing Information

// Update billing details
PUT /organizations/{org_id}/billing
{
  "billing_email": "billing@company.com",
  "billing_address": {
    "line1": "123 Business St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  }
}

📈 Usage Monitoring

Check Credit Balance

# Get current credit status
GET /organizations/{org_id}/billing

# Response
{
  "organization_id": "ORG_1234567890abcdef",
  "credits_remaining": 1500,
  "credits_total": 2000,
  "auto_recharge_enabled": true,
  "billing_email": "billing@company.com",
  "stripe_customer_id": "cus_xxxxxxxxxxxxxxxx",
  "last_recharge_at": "2024-01-15T10:30:00Z",
  "next_billing_date": "2024-02-01T00:00:00Z"
}

Usage History

# Get credit consumption events
GET /organizations/{org_id}/events?type=credits_consumed&limit=50

# Response includes detailed usage
[
  {
    "event_type": "credits_consumed",
    "entity_type": "transaction",
    "entity_id": "TXN_1234567890abcdef",
    "credits_used": 2,
    "description": "Transaction created",
    "timestamp": "2024-01-20T14:22:00Z"
  }
]

Real-Time Alerts

Email notifications for:

• Low balance warnings (below $4.00)
• Auto-recharge events (when triggered)
• Payment failures (card declined)
• Billing updates (new payment method)

🏗️ Multi-Organization Billing

Master Organization Billing

Credits are managed at the master organization level:

Master Organization (Billing Root)
├── Credits Pool: 10,000
├── Sub-Org A (Shared Billing): Consumes from master pool
├── Sub-Org B (Shared Billing): Consumes from master pool
└── Sub-Org C (Shared Billing): Consumes from master pool

Billing Hierarchy Rules

1. Master organizations hold the credit pools
2. All sub-organizations share billing with the master organization
3. Credit consumption is tracked per organization for internal allocation
4. Auto-recharge configured at master level

Cost Allocation Strategies

For Accounting Firms:

// All clients share master billing, tracked per-org
Client A Organization: Shared billing (usage tracked)
Client B Organization: Shared billing (usage tracked)
Firm Admin Organization: Shared billing (overhead costs)

For Enterprises:

// Department cost centers
Sales Division: Shared billing (marketing costs)
Engineering Division: Shared billing (tool costs)
Corporate Overhead: Master billing (shared services)

💡 Billing Examples

Individual Developer (Monthly Usage)

Starting Credits: 500 (free)
Base Cost: $1.00 (25 credits/week)
Usage:
├── 50 Manual Transactions: 100 credits ($1.00)
├── 10 Invoices: 10 credits ($0.10)
├── 5 Reports: 25 credits ($0.25)
└── API Integration: 50 credits ($0.50)

Total Cost: $2.85/month
Effective Rate: ~$0.057 per transaction

Development Team (Monthly Usage)

Starting Credits: 500 (free)
Base Cost: $1.00 (25 credits/week)
Usage:
├── 200 Manual Transactions: 400 credits ($4.00)
├── 50 Invoices: 50 credits ($0.50)
├── 20 Reports: 100 credits ($1.00)
├── Recurring Jobs: 100 credits ($1.00)
└── API Integration: 200 credits ($2.00)

Total Cost: $9.50/month
Effective Rate: ~$0.032 per transaction

Enterprise Platform (Monthly Usage)

Starting Credits: 500 (free)
Base Cost: $1.00 (25 credits/week)
Usage:
├── 1,000 Manual Transactions: 2,000 credits ($20.00)
├── 200 Invoices: 200 credits ($2.00)
├── 100 Reports: 500 credits ($5.00)
├── Bank Reconciliation: 200 credits ($2.00)
├── Multi-Currency: 300 credits ($3.00)
└── API Integration: 500 credits ($5.00)

Total Cost: $38.00/month
Effective Rate: ~$0.030 per transaction

⚠️ Credit Limits & Service Protection

Low Balance Warnings

• Email alerts when balance drops below $4.00
• API warnings in response headers
• Dashboard indicators in web interface
• Grace period before service suspension

Service Suspension

When credits reach zero:

• Read operations remain free (check balances, get data)
• Write operations are blocked (create, update, delete)
• Immediate resumption after adding credits
• No data loss - all data preserved

Preventing Service Interruptions

1. Enable auto-recharge for production applications
2. Monitor usage through API or dashboard
3. Set up alerts for low balance warnings
4. Maintain buffer credits for unexpected usage spikes

🛠️ Managing Billing Programmatically

Purchase Credits via API

// Purchase credit package
async function purchaseCredits(packageType, orgId) {
  const response = await fetch('/api/billing/purchase-package', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      package: packageType,  // 'solo_dev', 'builder', 'scale'
      organization_id: orgId
    })
  });

  const { checkout_url } = await response.json();
  // Redirect user to Stripe checkout
  window.location.href = checkout_url;
}

Check Usage Programmatically

// Monitor credit balance
async function checkCredits(orgId) {
  const response = await fetch(`/organizations/${orgId}/billing`);
  const billing = await response.json();

  if (billing.credits_remaining < 400) {
    alert('Low credit balance! Consider purchasing more credits.');
  }

  return billing;
}

// Get usage history
async function getUsageHistory(orgId, days = 30) {
  const since = new Date();
  since.setDate(since.getDate() - days);

  const response = await fetch(
    `/organizations/${orgId}/events?type=credits_consumed&since=${since.toISOString()}`
  );

  return await response.json();
}

Auto-Recharge Management

// Enable auto-recharge
async function enableAutoRecharge(orgId) {
  const response = await fetch(`/organizations/${orgId}/billing`, {
    method: 'PUT',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      auto_recharge_enabled: true
    })
  });

  return await response.json();
}

🎯 Best Practices

For Individual Developers

1. Start with Solo Dev package for personal projects
2. Enable auto-recharge to avoid service interruptions
3. Monitor usage through the dashboard
4. Upgrade packages as your usage grows

For Development Teams

1. Use Builder package for team development
2. Create separate organizations for different projects
3. Enable auto-recharge for production environments
4. Use API integration for automated credit monitoring

For Enterprise Platforms

1. Choose Scale package for high-volume applications
2. Create master organizations per client for billing isolation
3. Use API integration for automated credit management
4. Contact sales for custom enterprise packages

Cost Optimization

1. Batch operations when possible (reduce API calls)
2. Use read operations freely (they're free)
3. Cache data to reduce repeated API calls
4. Monitor usage patterns to identify optimization opportunities

🆘 Billing Troubleshooting

"My API calls are being rejected"

• Check credit balance: GET /organizations/{org_id}/billing
• Purchase more credits if balance is zero
• Enable auto-recharge to prevent future issues

"I wasn't charged for auto-recharge"

• Auto-recharge only triggers when balance drops below $4.00
• Check if auto-recharge is enabled for the organization
• Verify payment method is valid

"Credits are disappearing faster than expected"

• Review usage history: GET /organizations/{org_id}/events
• Check for unexpected API calls or integrations
• Consider upgrading to a larger package

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