navan-core-workflow-b

What this skill does

# Navan — Expense Management

## Overview

This skill covers the Navan expense reporting workflow through the REST API. The Expense Transaction API requires separate enablement from Navan support — it is not available by default. Once enabled, you can retrieve transaction data incrementally (the TRANSACTION table is append-only, unlike BOOKING which re-imports weekly). This skill provides patterns for expense data retrieval, approval workflow automation, and synchronization with ERP systems including NetSuite, Sage Intacct, Xero, and QuickBooks.

## Prerequisites

- Navan account with OAuth 2.0 API credentials (see `navan-install-auth`)
- Expense Transaction API enabled by Navan support (submit request via help center)
- For ERP sync: active integration configured in Navan Admin > Integrations
- Environment variables: `NAVAN_CLIENT_ID`, `NAVAN_CLIENT_SECRET`, `NAVAN_BASE_URL`
- Node.js 18+ or Python 3.8+

## Instructions

### Step 1: Request Expense API Enablement

The Expense Transaction API is not self-service. To enable it:

1. Navigate to [Navan Help Center](https://app.navan.com/app/helpcenter)
2. Submit a support request for "Expense Transaction API access"
3. Provide your company ID and the OAuth client_id that needs access
4. Navan support will enable the expense endpoints (typically 1-3 business days)
5. Verify access by calling the transaction endpoint after enablement

### Step 2: Authenticate

```typescript
const tokenRes = await fetch(`${process.env.NAVAN_BASE_URL}/ta-auth/oauth/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.NAVAN_CLIENT_ID!,
    client_secret: process.env.NAVAN_CLIENT_SECRET!,
  }),
});
const { access_token } = await tokenRes.json();
const headers = { Authorization: `Bearer ${access_token}` };
```

### Step 3: Retrieve Expense Transactions

```typescript
// Expense transactions are incremental — use date ranges for efficient pulls
// Note: The bookings endpoint is the primary data endpoint; expense data
// may require separate enablement from Navan support
const txnRes = await fetch(
  `${process.env.NAVAN_BASE_URL}/v1/bookings` +
  `?createdFrom=2026-03-01&createdTo=2026-03-31&page=0&size=50`,
  { headers }
);
const { data: transactions } = await txnRes.json();

transactions.forEach((txn: any) => {
  console.log(`ID: ${txn.transaction_id}`);
  console.log(`  Employee: ${txn.employee_name} (${txn.employee_id})`);
  console.log(`  Amount: ${txn.currency} ${txn.amount}`);
  console.log(`  Category: ${txn.category}`);
  console.log(`  Status: ${txn.approval_status}`);
  console.log(`  Merchant: ${txn.merchant_name}`);
});
```

### Step 4: Build Approval Workflow Logic

```typescript
// Route expenses based on amount thresholds and department policies
interface ApprovalRule {
  maxAmount: number;
  approverLevel: 'manager' | 'director' | 'vp' | 'cfo';
}

const approvalRules: ApprovalRule[] = [
  { maxAmount: 100, approverLevel: 'manager' },
  { maxAmount: 500, approverLevel: 'director' },
  { maxAmount: 5000, approverLevel: 'vp' },
  { maxAmount: Infinity, approverLevel: 'cfo' },
];

function getRequiredApprover(amount: number): string {
  const rule = approvalRules.find(r => amount <= r.maxAmount);
  return rule?.approverLevel ?? 'cfo';
}

// Process pending transactions
const pending = transactions.filter(
  (t: any) => t.approval_status === 'pending'
);
for (const txn of pending) {
  const approver = getRequiredApprover(txn.amount);
  console.log(`${txn.transaction_id}: $${txn.amount} -> route to ${approver}`);
}
```

### Step 5: Map Expense Categories to GL Codes

```typescript
// Map Navan expense categories to your chart of accounts
const categoryToGL: Record<string, string> = {
  'airfare': '6200-10',
  'hotel': '6200-20',
  'meals': '6200-30',
  'ground_transport': '6200-40',
  'car_rental': '6200-50',
  'other_travel': '6200-90',
  'office_supplies': '6300-10',
  'software': '6400-10',
};

function mapToGLCode(category: string): string {
  return categoryToGL[category] ?? '6900-00'; // default: miscellaneous
}

transactions.forEach((txn: any) => {
  const gl = mapToGLCode(txn.category);
  console.log(`${txn.transaction_id}: ${txn.category} -> GL ${gl}`);
});
```

### Step 6: ERP Sync Pattern (NetSuite Example)

```typescript
// Build journal entry payload for NetSuite sync
// Navan integrates natively with NetSuite, Sage Intacct, Xero, QuickBooks
const journalEntries = transactions.map((txn: any) => ({
  tranDate: txn.transaction_date,
  subsidiary: txn.cost_center,
  lineItems: [
    {
      account: mapToGLCode(txn.category),
      debit: txn.amount,
      memo: `Navan: ${txn.merchant_name} - ${txn.employee_name}`,
      department: txn.department,
      class: txn.project_code,
    },
    {
      account: '2000-00', // Accounts Payable
      credit: txn.amount,
      memo: `Navan expense reimbursement`,
    },
  ],
}));

console.log(`Prepared ${journalEntries.length} journal entries for NetSuite sync`);
```

## Output

Successful execution produces:

- Expense transaction records with employee, amount, category, and approval status
- Approval routing decisions based on configurable threshold rules
- GL-coded transaction records ready for ERP import
- Journal entry payloads formatted for target accounting system

## Error Handling

| Error | HTTP Code | Cause | Solution |
|-------|-----------|-------|----------|
| Unauthorized | 401 | Expired or invalid bearer token | Re-authenticate via POST /ta-auth/oauth/token |
| Forbidden | 403 | Expense API not enabled | Contact Navan support to enable Expense Transaction API |
| Bad Request | 400 | Invalid date range or parameters | Verify date format is YYYY-MM-DD |
| Rate Limited | 429 | Too many requests | Implement exponential backoff (start at 1s) |
| Server Error | 500 | Navan platform issue | Retry with backoff; check Navan status page |
| No Data | 200 (empty) | No transactions in date range | Widen date range or verify expense API enablement |

## Examples

**Python — Expense retrieval with category breakdown:**

```python
import requests
import os
from collections import defaultdict

base_url = os.environ.get('NAVAN_BASE_URL', 'https://api.navan.com')
auth = requests.post(f'{base_url}/ta-auth/oauth/token', data={
    'grant_type': 'client_credentials',
    'client_id': os.environ['NAVAN_CLIENT_ID'],
    'client_secret': os.environ['NAVAN_CLIENT_SECRET'],
})
headers = {'Authorization': f'Bearer {auth.json()["access_token"]}'}

resp = requests.get(
    f'{base_url}/v1/bookings',
    params={'createdFrom': '2026-03-01', 'createdTo': '2026-03-31', 'page': 0, 'size': 50},
    headers=headers,
).json()
txns = resp['data']

# Category breakdown
by_category = defaultdict(float)
for t in txns:
    by_category[t['category']] += t['amount']
for cat, total in sorted(by_category.items(), key=lambda x: -x[1]):
    print(f'  {cat}: ${total:,.2f}')
```

## Resources

- [Navan Help Center](https://app.navan.com/app/helpcenter) — Support and documentation
- [Navan Integrations](https://navan.com/integrations) — NetSuite, Sage Intacct, Xero, QuickBooks connectors
- [Booking Data Integration](https://app.navan.com/app/helpcenter/articles/travel/admin/other-integrations/booking-data-integration) — Data export configuration

## Next Steps

After setting up expense management, proceed to `navan-data-sync` for incremental sync strategies or `navan-entity-management` for user and department configuration.