How to Integrate Xero with V0

Open V0 at v0.dev and describe the financial dashboard interface you want to build. Accounting dashboards benefit from clear visual hierarchy: key financial figures prominently displayed, color-coded status indicators (red for overdue, green for paid, blue for pending), and tables that support sorting by amount, date, or status. When prompting V0, be specific about the Xero data entities you want to display — invoices, bank balances, contacts, or financial report summaries. V0 generates React components with shadcn/ui — Table, Card, Badge, and Chart components from recharts work well for financial dashboards. Describe the currency format you need (Xero supports multi-currency, so specify whether amounts should be shown in the account currency or a specific currency), and ask V0 to include appropriate number formatting for financial figures. Include the API endpoint paths your components will call (/api/xero/invoices, /api/xero/bank-summary) so V0 generates accurate fetch calls. For dashboards that require user authentication with their own Xero account, also ask V0 to include a 'Connect Xero Account' button that links to /api/xero/auth — this starts the OAuth2 flow. Push the generated code to GitHub via V0's Git panel.

Xero requires OAuth2 authentication, which involves redirecting users to Xero's authorization page and handling the callback with the authorization code. Install the xero-node SDK with npm install xero-node — it handles the OAuth2 flow, token refresh, and all API calls. The OAuth2 flow has three steps: first, your app redirects the user to Xero's authorization URL with your client ID, scopes, and a redirect URI; second, the user logs into Xero and approves the connection, and Xero redirects back to your callback URL with an authorization code; third, your callback route exchanges the code for access and refresh tokens. Create two API routes: /api/xero/auth (initiates the OAuth2 flow by building the authorization URL and redirecting) and /api/xero/callback (handles the return from Xero, exchanges the code for tokens, and stores them). In production, store the refresh token in a database or encrypted cookie so you can refresh access tokens without requiring re-authentication. For development and single-user apps, you can store the token in an encrypted HTTP-only cookie. The access token expires after 30 minutes — use the xero-node client's refreshToken() method when the access token expires. The refresh token is valid for 60 days and itself refreshes with each use.

1// app/api/xero/auth/route.ts
2import { NextResponse } from 'next/server';
3import { XeroClient } from 'xero-node';
4
5const xero = new XeroClient({
6  clientId: process.env.XERO_CLIENT_ID!,
7  clientSecret: process.env.XERO_CLIENT_SECRET!,
8  redirectUris: [process.env.XERO_REDIRECT_URI!],
9  scopes: [
10    'openid',
11    'profile',
12    'email',
13    'accounting.transactions',
14    'accounting.contacts',
15    'accounting.reports.read',
16    'accounting.settings',
17    'offline_access', // Required for refresh tokens
18  ],
19});
20
21export async function GET() {
22  const consentUrl = await xero.buildConsentUrl();
23  return NextResponse.redirect(consentUrl);
24}
25
26// app/api/xero/callback/route.ts
27// (Separate file)
28export { callbackHandler as GET } from './callback-handler';
29
30// lib/xero-callback.ts
31export async function getXeroCallbackHandler() {
32  const { XeroClient } = await import('xero-node');
33  return new XeroClient({
34    clientId: process.env.XERO_CLIENT_ID!,
35    clientSecret: process.env.XERO_CLIENT_SECRET!,
36    redirectUris: [process.env.XERO_REDIRECT_URI!],
37    scopes: ['openid', 'profile', 'email', 'accounting.transactions', 'accounting.contacts', 'accounting.reports.read', 'offline_access'],
38  });
39}

With authentication in place, create API routes that call Xero's accounting API for your dashboard data. The xero-node SDK provides typed methods for all Xero API endpoints. A critical requirement for all Xero API calls is the Xero Tenant ID — after OAuth2 authentication, call xero.updateTenants() to get the list of organizations the user has connected, then include the tenantId in every subsequent API call. Store the tenant ID in your session or cookie alongside the access token. For invoices, use the xero.accountingApi.getInvoices() method which accepts filter parameters for status (DRAFT, SUBMITTED, AUTHORISED, VOIDED, DELETED — 'AUTHORISED' means approved and outstanding, not authorized in a permissions sense), contact ID, date range, and page number. For bank accounts and balances, call xero.accountingApi.getAccounts() with type filter BANK to list bank accounts, then xero.accountingApi.getBankTransactions() for transaction history. For financial reports (P&L, Balance Sheet), use xero.accountingApi.getReportProfitAndLoss() and xero.accountingApi.getReportBalanceSheet() which accept reporting date parameters. Parse the report responses carefully — Xero's report API returns a hierarchical data structure with Rows containing nested Cells, which requires recursive traversal to extract the figures you need for your dashboard.

1// app/api/xero/invoices/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { XeroClient, Invoice } from 'xero-node';
4
5const xero = new XeroClient({
6  clientId: process.env.XERO_CLIENT_ID!,
7  clientSecret: process.env.XERO_CLIENT_SECRET!,
8  redirectUris: [process.env.XERO_REDIRECT_URI!],
9  scopes: [],
10});
11
12export async function GET(request: NextRequest) {
13  // In a real app, load tokens from your database or encrypted session
14  const accessToken = process.env.XERO_ACCESS_TOKEN; // For demo — use database in production
15  const refreshToken = process.env.XERO_REFRESH_TOKEN;
16  const tenantId = process.env.XERO_TENANT_ID;
17
18  if (!accessToken || !tenantId) {
19    return NextResponse.json({ error: 'Not authenticated with Xero', requiresAuth: true }, { status: 401 });
20  }
21
22  try {
23    // Set the token on the xero-node client
24    xero.setTokenSet({ access_token: accessToken, refresh_token: refreshToken, token_type: 'Bearer' });
25
26    const { searchParams } = new URL(request.url);
27    const statuses = (searchParams.get('statuses') || 'AUTHORISED,OVERDUE').split(',') as Invoice['status'][];
28    const page = parseInt(searchParams.get('page') || '1', 10);
29
30    const response = await xero.accountingApi.getInvoices(
31      tenantId,
32      undefined, // ifModifiedSince
33      undefined, // where
34      'DueDateASC', // order
35      undefined, // IDs
36      undefined, // invoiceNumbers
37      undefined, // contactIDs
38      statuses,
39      page,
40      false, // includeArchived
41      true,  // createdByMyApp - show all invoices
42      undefined,
43      undefined,
44      100 // unitdp - decimal places
45    );
46
47    const invoices = response.body.invoices || [];
48
49    // Calculate summary statistics
50    const summary = {
51      total: invoices.length,
52      totalOutstanding: invoices.reduce((sum, inv) => sum + (inv.amountDue || 0), 0),
53      overdueCount: invoices.filter(inv => inv.isDiscounted).length, // Use your overdue logic
54      currency: invoices[0]?.currencyCode || 'USD',
55    };
56
57    return NextResponse.json({ invoices, summary });
58  } catch (error) {
59    const message = error instanceof Error ? error.message : 'Unknown error';
60    console.error('Xero invoices fetch failed:', message);
61    return NextResponse.json({ error: message }, { status: 500 });
62  }
63}

Configure all Xero credentials in Vercel before deploying. Open the Vercel Dashboard, navigate to your project, and go to Settings → Environment Variables. Add XERO_CLIENT_ID with your Xero app's Client ID from developer.xero.com/app/manage. Add XERO_CLIENT_SECRET with the Client Secret — treat this as a password. Add XERO_REDIRECT_URI with the exact redirect URI you configured in your Xero app — this must match character-for-character, including trailing slashes. For Vercel deployments, the URI will be https://your-project.vercel.app/api/xero/callback. Do not use NEXT_PUBLIC_ on any of these variables. For testing with real tokens, also add XERO_ACCESS_TOKEN, XERO_REFRESH_TOKEN, and XERO_TENANT_ID if you're using the simple environment variable token storage (for production, use a database for token storage instead). Set all variables for Production and Preview environments. After deploying, test the OAuth2 flow by visiting your live URL, clicking 'Connect to Xero', completing the authorization on Xero's site, and verifying you're redirected back to your dashboard with data loading. Important: In production apps, store Xero tokens in a database (Supabase, Neon) rather than environment variables — tokens change on every refresh and must be updated dynamically, which is not possible with environment variables. For complex multi-tenant apps where multiple users each connect their own Xero organizations, RapidDev's team can help implement the full token storage and multi-tenant architecture.