How to Integrate Bolt.new with Harvest

Harvest uses personal access tokens for API authentication, combined with a second header called Harvest-Account-Id that tells the API which account to access. Both are required for every API call — missing either one results in a 401 Unauthorized response. To create a personal access token, log into your Harvest account and go to the Developers section. In the top navigation, click your profile picture or name, then select Developers. On the Developers page, you will see a section called Personal Access Tokens. Click Create New Personal Access Token. Give it a descriptive name like 'Bolt App Integration.' Harvest personal access tokens are not scoped — they grant full API access to your account. The token is shown once immediately after creation, starting with a long random string. Copy it immediately and add it to your Bolt project's .env file as HARVEST_ACCESS_TOKEN. Your Account ID appears directly on the Developers page below the Personal Access Tokens section — look for 'Your Account ID' with a numeric value (for example, 1234567). This is a number, not a string, but store it as a string in .env. Add it as HARVEST_ACCOUNT_ID. If you have access to multiple Harvest accounts, you will see multiple Account IDs listed — use the one corresponding to the account containing your projects and time entries. Every API request to Harvest must include both headers: Authorization: Bearer YOUR_TOKEN and Harvest-Account-Id: YOUR_ACCOUNT_ID. The API base URL is https://api.harvestapp.com/v2. Add both values to your .env file before prompting Bolt to build any integration code. Test the connection by calling GET /v2/users/me — this endpoint returns your user information and is a quick health check to confirm both headers are working.

1// lib/harvest.ts
2const HARVEST_BASE_URL = 'https://api.harvestapp.com/v2';
3
4function getHeaders() {
5  const token = process.env.HARVEST_ACCESS_TOKEN;
6  const accountId = process.env.HARVEST_ACCOUNT_ID;
7
8  if (!token || !accountId) {
9    throw new Error('HARVEST_ACCESS_TOKEN and HARVEST_ACCOUNT_ID must be set in .env');
10  }
11
12  return {
13    Authorization: `Bearer ${token}`,
14    'Harvest-Account-Id': accountId,
15    'Content-Type': 'application/json',
16    'User-Agent': 'Bolt App (your@email.com)',
17  };
18}
19
20export async function harvestFetch<T = unknown>(
21  path: string,
22  params?: Record<string, string | number | boolean>
23): Promise<T> {
24  const url = new URL(`${HARVEST_BASE_URL}${path}`);
25  if (params) {
26    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, String(v)));
27  }
28
29  const response = await fetch(url.toString(), { headers: getHeaders() });
30
31  if (!response.ok) {
32    const error = await response.json().catch(() => ({ message: response.statusText })) as { message?: string };
33    throw new Error(error.message || `Harvest API error: ${response.status}`);
34  }
35
36  return response.json() as Promise<T>;
37}
38
39export async function harvestPost<T = unknown>(path: string, body: unknown): Promise<T> {
40  const response = await fetch(`${HARVEST_BASE_URL}${path}`, {
41    method: 'POST',
42    headers: getHeaders(),
43    body: JSON.stringify(body),
44  });
45
46  if (!response.ok) {
47    const error = await response.json().catch(() => ({ message: response.statusText })) as { message?: string };
48    throw new Error(error.message || `Harvest POST error: ${response.status}`);
49  }
50
51  return response.json() as Promise<T>;
52}
53
54export async function harvestPatch<T = unknown>(path: string, body: unknown): Promise<T> {
55  const response = await fetch(`${HARVEST_BASE_URL}${path}`, {
56    method: 'PATCH',
57    headers: getHeaders(),
58    body: JSON.stringify(body),
59  });
60
61  if (!response.ok) {
62    const error = await response.json().catch(() => ({ message: response.statusText })) as { message?: string };
63    throw new Error(error.message || `Harvest PATCH error: ${response.status}`);
64  }
65
66  return response.json() as Promise<T>;
67}

The Harvest time entries endpoint is the core of most integrations. GET /v2/time_entries returns a paginated list of time entries with extensive filtering options. Understanding the key query parameters is essential for building useful dashboards and reports. The most important filter parameters are from and to for date range filtering — these accept ISO 8601 date strings (YYYY-MM-DD). Without a date range, Harvest returns entries starting from the most recent, paginated at 100 entries per page. For dashboard views, always set a from and to to get a specific billing period. The billable parameter accepts true or false to filter to only billable or non-billable time. client_id and project_id filter to specific clients or projects, and user_id filters to a specific team member. Each time entry in the response includes nested objects for client, project, and task — you get the name, id, and basic details of each without requiring additional API calls. This makes the time entries endpoint efficient for building dashboards that need to display time grouped by multiple dimensions. Harvest uses cursor-based pagination via the next_page parameter. When the response includes a next_page value (an integer), there are more results. Fetch subsequent pages by adding the page parameter to your request. For typical dashboard date ranges (a week or a month), most accounts will have fewer than 100 entries and pagination is not needed. For longer date ranges or large teams, build pagination into your API route. The Harvest API returns all monetary amounts in the account's currency. Hourly rates are set on the project-task assignment level, so not every time entry will have a calculated amount — only entries with a rate set will include a billable_amount value. Handle this gracefully in your UI by showing '-' or 'no rate set' for entries without a billable amount.

1// app/api/harvest/time-entries/route.ts
2import { NextResponse } from 'next/server';
3import { harvestFetch } from '@/lib/harvest';
4
5interface HarvestTimeEntry {
6  id: number;
7  hours: number;
8  billable: boolean;
9  billable_rate: number | null;
10  billable_amount: number | null;
11  notes: string | null;
12  spent_date: string;
13  client: { id: number; name: string };
14  project: { id: number; name: string };
15  task: { id: number; name: string };
16  user: { id: number; name: string };
17}
18
19interface HarvestEntriesResponse {
20  time_entries: HarvestTimeEntry[];
21  next_page: number | null;
22  total_pages: number;
23}
24
25const cache = new Map<string, { data: unknown; expiresAt: number }>();
26
27export async function GET(request: Request) {
28  const { searchParams } = new URL(request.url);
29  const from = searchParams.get('from');
30  const to = searchParams.get('to');
31  const clientId = searchParams.get('clientId');
32  const projectId = searchParams.get('projectId');
33  const billable = searchParams.get('billable');
34
35  if (!from || !to) {
36    return NextResponse.json({ error: 'from and to query params are required' }, { status: 400 });
37  }
38
39  const cacheKey = `${from}-${to}-${clientId}-${projectId}-${billable}`;
40  const cached = cache.get(cacheKey);
41  if (cached && Date.now() < cached.expiresAt) {
42    return NextResponse.json(cached.data);
43  }
44
45  try {
46    const allEntries: HarvestTimeEntry[] = [];
47    let page = 1;
48
49    while (true) {
50      const params: Record<string, string | number | boolean> = { from, to, page };
51      if (clientId) params.client_id = clientId;
52      if (projectId) params.project_id = projectId;
53      if (billable !== null) params.billable = billable === 'true';
54
55      const data = await harvestFetch<HarvestEntriesResponse>('/time_entries', params);
56      allEntries.push(...data.time_entries);
57
58      if (!data.next_page) break;
59      page = data.next_page;
60    }
61
62    const totalHours = allEntries.reduce((sum, e) => sum + e.hours, 0);
63    const billableHours = allEntries.filter(e => e.billable).reduce((sum, e) => sum + e.hours, 0);
64    const billableAmount = allEntries.reduce((sum, e) => sum + (e.billable_amount || 0), 0);
65
66    const result = {
67      entries: allEntries,
68      summary: {
69        totalHours: Math.round(totalHours * 100) / 100,
70        billableHours: Math.round(billableHours * 100) / 100,
71        nonBillableHours: Math.round((totalHours - billableHours) * 100) / 100,
72        billableAmount: Math.round(billableAmount * 100) / 100,
73        billablePercentage: totalHours > 0 ? Math.round((billableHours / totalHours) * 100) : 0,
74      },
75    };
76
77    cache.set(cacheKey, { data: result, expiresAt: Date.now() + 30_000 });
78    return NextResponse.json(result);
79  } catch (err) {
80    const message = err instanceof Error ? err.message : 'Failed to fetch time entries';
81    return NextResponse.json({ error: message }, { status: 500 });
82  }
83}

With the API route in place, build the dashboard UI that displays Harvest data visually. A useful time tracking dashboard shows multiple views simultaneously: a top-level summary (total hours, billable percentage, revenue), a breakdown by project or client, and a time-series view of daily or weekly effort. Fetch data on component mount using useEffect, storing the results in state. Pass from and to query params to your API route based on the selected date range. For the default view, use the current week or current month — calculate these programmatically so the dashboard is always showing current data rather than hardcoded dates. For grouping time entries by project or client, use JavaScript's reduce method to aggregate the flat entries array from Harvest into a nested structure. Group by client first, then by project within each client. Calculate subtotals at each level. Sort by hours descending so the most time-intensive projects appear first. For the time-series chart, transform entries into daily totals. Create an object keyed by spent_date, summing billable and non-billable hours separately for each date. Convert this to an array sorted by date for use with Recharts or a similar charting library. A stacked bar chart with one bar per day, split between billable (green) and non-billable (gray) hours, is the most intuitive visualization for this data type. Add a date range picker so users can change the reporting period. Simple options like 'This Week,' 'Last Week,' 'This Month,' and 'Last Month' cover most needs without requiring a full calendar widget. Update the fetch on change and show a loading indicator while new data is being retrieved. Cache results in component state to avoid re-fetching when switching between already-loaded periods.

Harvest supports webhook notifications for key events: when a time entry is created, updated, or deleted; when an invoice is created, sent, or paid; when an expense is created. These webhooks enable real-time dashboard updates, invoice payment notifications sent to Slack, and automated workflows triggered by billing events. During development in Bolt's WebContainer, the preview URL runs inside a browser tab and cannot receive incoming HTTP connections from Harvest's servers. This is a fundamental WebContainer architecture limitation — the Service Worker that handles networking only routes requests to and from the browser session itself, not from external servers. Webhook testing requires a publicly accessible URL. To use Harvest webhooks, deploy your Bolt app to Netlify or Bolt Cloud first. Once deployed, you will have a stable URL like https://yourapp.netlify.app. In your Harvest account, go to Settings → Integrations → Webhooks (or via the Harvest API with POST /v2/webhooks). Create a new webhook, set the payload URL to https://yourapp.netlify.app/api/harvest/webhook, and select the events you want to receive. Harvest signs webhook payloads with HMAC-SHA256 using a secret you set when creating the webhook. Verify this signature in your handler to confirm requests are genuinely from Harvest. The signature is sent in the Harvest-Webhook-Delivery-Id and HTTP_X_HARVEST_SIGNATURE headers — Harvest's documentation shows the exact verification pattern. For the webhook handler, return a 200 response quickly and process the event asynchronously if it involves database writes or external API calls. Harvest will retry failed deliveries (non-2xx responses) multiple times over several hours. Your handler should be idempotent — processing the same event twice should not cause duplicate data.

1// app/api/harvest/webhook/route.ts
2// NOTE: This webhook handler requires deployment to Netlify or Bolt Cloud.
3// Harvest cannot send POST requests to the Bolt WebContainer preview URL.
4// After deploying, register your webhook URL in Harvest Settings → Integrations → Webhooks.
5import { NextResponse } from 'next/server';
6
7interface HarvestWebhookPayload {
8  type: string;
9  payload: {
10    id: number;
11    [key: string]: unknown;
12  };
13  created_at: string;
14}
15
16export async function POST(request: Request) {
17  const body = await request.json() as HarvestWebhookPayload;
18
19  const { type, payload } = body;
20
21  console.log(`[Harvest Webhook] Event: ${type}, ID: ${payload.id}`);
22
23  switch (type) {
24    case 'time_entry.created':
25    case 'time_entry.updated':
26    case 'time_entry.deleted':
27      // Time entry changed — signal frontend to refresh dashboard data
28      // In a real app, invalidate your cache or emit to a WebSocket/SSE stream
29      console.log(`[Harvest] Time entry ${type.split('.')[1]}: ${payload.id}`);
30      break;
31
32    case 'invoice.paid':
33      console.log(`[Harvest] Invoice paid: ${payload.id}`);
34      // Add notification logic here (Slack, email, etc.)
35      break;
36
37    default:
38      console.log(`[Harvest] Unhandled event type: ${type}`);
39  }
40
41  return NextResponse.json({ received: true });
42}