Authenticated API

This endpoint requires a valid JWT Bearer token with integration_admin or manager roles. Accessible via the API gateway at /v1/integrations/*.

Accounting Integration API

Connect to QuickBooks, Xero, Sage, and other accounting platforms for automated financial synchronization.

Overview

Attribute	Value
Base Path	`/api/v1/integrations/accounting`
Authentication	Bearer Token
Required Roles	`integration_admin`, `finance`, `restaurant_manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Supported Platforms

Platform	Status	Features
QuickBooks Online	GA	Full sync, Journal entries, Invoices
QuickBooks Desktop	GA	Via Web Connector
Xero	GA	Full sync, Bank feeds
Sage Intacct	GA	Multi-entity, Advanced GL
FreshBooks	Beta	Invoices, Expenses
Wave	Beta	Basic sync

Connections

List Connections

GET /api/v1/integrations/accounting/connections

Response

{
  "connections": [
    {
      "id": "conn_001",
      "platform": "quickbooks_online",
      "company_name": "Downtown Restaurant LLC",
      "company_id": "1234567890",
      "status": "active",
      "last_sync": "2026-01-24T18:00:00Z",
      "sync_status": "healthy",
      "features_enabled": [
        "sales_sync",
        "expense_sync",
        "payroll_sync",
        "inventory_sync"
      ],
      "connected_at": "2025-08-15T00:00:00Z",
      "expires_at": null
    }
  ]
}

Connect Platform

POST /api/v1/integrations/accounting/connect

Request Body

{
  "platform": "quickbooks_online",
  "location_id": "loc_123",
  "redirect_url": "https://app.example.com/accounting/callback"
}

Response

{
  "authorization_url": "https://appcenter.intuit.com/connect/oauth2?...",
  "state": "state_abc123",
  "expires_in": 600
}

Complete OAuth

POST /api/v1/integrations/accounting/callback

Request Body

{
  "platform": "quickbooks_online",
  "code": "oauth_code_here",
  "state": "state_abc123",
  "realm_id": "1234567890"
}

Response

{
  "connection_id": "conn_001",
  "platform": "quickbooks_online",
  "company_name": "Downtown Restaurant LLC",
  "status": "active",
  "initial_sync_required": true,
  "chart_of_accounts_mapping_required": true
}

Disconnect Platform

DELETE /api/v1/integrations/accounting/connections/{connection_id}

Chart of Accounts

Get Chart of Accounts

GET /api/v1/integrations/accounting/connections/{connection_id}/accounts

Response

{
  "accounts": [
    {
      "id": "acct_001",
      "external_id": "80",
      "name": "Food Sales",
      "type": "Income",
      "sub_type": "SalesOfProductIncome",
      "account_number": "4000",
      "currency": "USD",
      "active": true,
      "olympus_mapping": {
        "category": "revenue",
        "sub_category": "food_sales"
      }
    },
    {
      "id": "acct_002",
      "external_id": "81",
      "name": "Beverage Sales",
      "type": "Income",
      "sub_type": "SalesOfProductIncome",
      "account_number": "4100",
      "currency": "USD",
      "active": true,
      "olympus_mapping": {
        "category": "revenue",
        "sub_category": "beverage_sales"
      }
    },
    {
      "id": "acct_003",
      "external_id": "150",
      "name": "Cost of Goods Sold - Food",
      "type": "Cost of Goods Sold",
      "sub_type": "SuppliesMaterialsCogs",
      "account_number": "5000",
      "currency": "USD",
      "active": true,
      "olympus_mapping": {
        "category": "cogs",
        "sub_category": "food_cost"
      }
    }
  ],
  "unmapped_olympus_categories": [
    "revenue.merchandise",
    "expense.marketing"
  ]
}

Update Account Mapping

PUT /api/v1/integrations/accounting/connections/{connection_id}/accounts/mapping

Request Body

{
  "mappings": [
    {
      "olympus_category": "revenue.food_sales",
      "external_account_id": "80"
    },
    {
      "olympus_category": "revenue.beverage_sales",
      "external_account_id": "81"
    },
    {
      "olympus_category": "cogs.food_cost",
      "external_account_id": "150"
    },
    {
      "olympus_category": "expense.labor",
      "external_account_id": "200"
    }
  ]
}

Synchronization

Trigger Sync

POST /api/v1/integrations/accounting/connections/{connection_id}/sync

Request Body

{
  "sync_type": "full",
  "date_range": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "modules": ["sales", "expenses", "payroll"],
  "options": {
    "create_missing_accounts": false,
    "auto_reconcile": true
  }
}

Response

{
  "sync_job_id": "sync_001",
  "status": "in_progress",
  "modules": [
    {"module": "sales", "status": "pending", "records": 0},
    {"module": "expenses", "status": "pending", "records": 0},
    {"module": "payroll", "status": "pending", "records": 0}
  ],
  "started_at": "2026-01-24T19:30:00Z",
  "estimated_completion": "2026-01-24T19:35:00Z"
}

Get Sync Status

GET /api/v1/integrations/accounting/sync/{sync_job_id}

Response

{
  "sync_job_id": "sync_001",
  "connection_id": "conn_001",
  "status": "completed",
  "modules": [
    {
      "module": "sales",
      "status": "completed",
      "records_synced": 1250,
      "records_failed": 2,
      "duration_seconds": 45
    },
    {
      "module": "expenses",
      "status": "completed",
      "records_synced": 85,
      "records_failed": 0,
      "duration_seconds": 12
    },
    {
      "module": "payroll",
      "status": "completed",
      "records_synced": 45,
      "records_failed": 0,
      "duration_seconds": 8
    }
  ],
  "summary": {
    "total_synced": 1380,
    "total_failed": 2,
    "journal_entries_created": 32,
    "invoices_created": 0
  },
  "errors": [
    {
      "module": "sales",
      "record_id": "sale_001",
      "error": "Account mapping not found for gift card redemption",
      "resolution": "Map the gift_card_liability account"
    }
  ],
  "started_at": "2026-01-24T19:30:00Z",
  "completed_at": "2026-01-24T19:32:05Z"
}

Get Sync History

GET /api/v1/integrations/accounting/connections/{connection_id}/sync/history

Query Parameters

Parameter	Type	Description
`status`	string	`completed`, `failed`, `partial`
`start_date`	date	Filter from date
`end_date`	date	Filter to date

Journal Entries

List Journal Entries

GET /api/v1/integrations/accounting/connections/{connection_id}/journal-entries

Query Parameters

Parameter	Type	Description
`start_date`	date	Period start
`end_date`	date	Period end
`status`	string	`pending`, `synced`, `failed`

Response

{
  "journal_entries": [
    {
      "id": "je_001",
      "external_id": "JE-2026-0124",
      "date": "2026-01-24",
      "memo": "Daily Sales Summary - Downtown Location",
      "status": "synced",
      "lines": [
        {
          "account": "Food Sales",
          "account_id": "acct_001",
          "debit": 0,
          "credit": 8542.00,
          "description": "Food revenue"
        },
        {
          "account": "Beverage Sales",
          "account_id": "acct_002",
          "debit": 0,
          "credit": 2150.00,
          "description": "Beverage revenue"
        },
        {
          "account": "Sales Tax Payable",
          "account_id": "acct_010",
          "debit": 0,
          "credit": 855.36,
          "description": "Sales tax collected"
        },
        {
          "account": "Cash",
          "account_id": "acct_020",
          "debit": 3200.00,
          "credit": 0,
          "description": "Cash payments"
        },
        {
          "account": "Credit Card Receivable",
          "account_id": "acct_021",
          "debit": 8347.36,
          "credit": 0,
          "description": "Credit card payments"
        }
      ],
      "total_debit": 11547.36,
      "total_credit": 11547.36,
      "synced_at": "2026-01-25T02:00:00Z"
    }
  ]
}

Create Manual Journal Entry

POST /api/v1/integrations/accounting/connections/{connection_id}/journal-entries

Request Body

{
  "date": "2026-01-24",
  "memo": "Month-end adjustment",
  "lines": [
    {
      "account_id": "acct_050",
      "debit": 500.00,
      "credit": 0,
      "description": "Prepaid expense adjustment"
    },
    {
      "account_id": "acct_060",
      "debit": 0,
      "credit": 500.00,
      "description": "Insurance expense"
    }
  ],
  "sync_immediately": true
}

Invoices

Sync Invoice

POST /api/v1/integrations/accounting/connections/{connection_id}/invoices

Request Body

{
  "olympus_invoice_id": "inv_001",
  "customer": {
    "name": "Corporate Events Inc",
    "email": "billing@corpevents.com",
    "external_id": "cust_qb_001"
  },
  "line_items": [
    {
      "description": "Catering - Holiday Party",
      "quantity": 1,
      "unit_price": 2500.00,
      "account_id": "acct_005"
    },
    {
      "description": "Beverage Service",
      "quantity": 1,
      "unit_price": 800.00,
      "account_id": "acct_002"
    }
  ],
  "tax_amount": 264.00,
  "due_date": "2026-02-24"
}

Reconciliation

Get Reconciliation Status

GET /api/v1/integrations/accounting/connections/{connection_id}/reconciliation

Query Parameters

Parameter	Type	Description
`period`	string	`2026-01` format

Response

{
  "period": "2026-01",
  "status": "in_progress",
  "olympus_totals": {
    "gross_sales": 285420.00,
    "net_sales": 268500.00,
    "taxes_collected": 22850.00,
    "tips_collected": 45200.00,
    "refunds": 1250.00
  },
  "accounting_totals": {
    "gross_sales": 285420.00,
    "net_sales": 268500.00,
    "taxes_collected": 22850.00,
    "tips_collected": 45200.00,
    "refunds": 1250.00
  },
  "discrepancies": [],
  "reconciled": true,
  "last_reconciled": "2026-01-24T06:00:00Z"
}

Run Reconciliation

POST /api/v1/integrations/accounting/connections/{connection_id}/reconciliation

Request Body

{
  "period": "2026-01",
  "auto_adjust": false
}

Configuration

Get Sync Settings

GET /api/v1/integrations/accounting/connections/{connection_id}/settings

Response

{
  "sync_frequency": "daily",
  "sync_time": "02:00",
  "timezone": "America/New_York",
  "modules_enabled": {
    "sales": true,
    "expenses": true,
    "payroll": true,
    "inventory": true,
    "invoices": false
  },
  "options": {
    "consolidate_daily_sales": true,
    "separate_by_location": true,
    "include_tips_in_revenue": false,
    "auto_create_customers": true,
    "auto_create_vendors": true
  },
  "notifications": {
    "sync_failures": ["admin@example.com"],
    "reconciliation_discrepancies": ["accounting@example.com"]
  }
}

Update Sync Settings

PUT /api/v1/integrations/accounting/connections/{connection_id}/settings

Webhooks

Event	Description
`accounting.connected`	New platform connected
`accounting.disconnected`	Platform disconnected
`accounting.sync_completed`	Sync job completed
`accounting.sync_failed`	Sync job failed
`accounting.reconciliation_discrepancy`	Reconciliation mismatch found
`accounting.token_expiring`	OAuth token expiring soon

Error Responses

Status	Code	Description
400	`invalid_mapping`	Account mapping invalid
401	`token_expired`	OAuth token expired
404	`connection_not_found`	Connection ID not found
409	`sync_in_progress`	Sync already running
422	`unbalanced_entry`	Journal entry debits != credits
503	`platform_unavailable`	Accounting platform unavailable

Invoices API - Invoice management
Payments API - Payment processing
Payroll Integration - Payroll sync

Overview​

Supported Platforms​

Connections​

List Connections​

Connect Platform​

Complete OAuth​

Disconnect Platform​

Chart of Accounts​

Get Chart of Accounts​

Update Account Mapping​

Synchronization​

Trigger Sync​

Get Sync Status​

Get Sync History​

Journal Entries​

List Journal Entries​

Create Manual Journal Entry​

Invoices​

Sync Invoice​

Reconciliation​

Get Reconciliation Status​

Run Reconciliation​

Configuration​

Get Sync Settings​

Update Sync Settings​

Webhooks​

Error Responses​

Related Documentation​

Overview

Supported Platforms

Connections

List Connections

Connect Platform

Complete OAuth

Disconnect Platform

Chart of Accounts

Get Chart of Accounts

Update Account Mapping

Synchronization

Trigger Sync

Get Sync Status

Get Sync History

Journal Entries

List Journal Entries

Create Manual Journal Entry

Invoices

Sync Invoice

Reconciliation

Get Reconciliation Status

Run Reconciliation

Configuration

Get Sync Settings

Update Sync Settings

Webhooks

Error Responses

Related Documentation