How to Integrate Lovable with Zoho Books

Zoho Books uses OAuth2 for authentication. You need to register your integration as a 'Server-Based Application' in the Zoho API Console before making any API calls. Go to api-console.zoho.com and sign in with your Zoho account. Click 'Add Client'. Choose 'Server-based Applications' as the client type — this is the correct type for Edge Function server-to-server integrations. Fill in the registration form: - Client Name: something descriptive like 'Lovable Books Integration' - Homepage URL: your Lovable app URL (e.g., https://yourapp.lovable.app) - Authorized Redirect URIs: use https://yourapp.lovable.app/oauth/callback for now (you will need this for the initial token exchange) After creating the client, Zoho provides a Client ID and Client Secret. Copy both values. Next, you need to generate the first access token and refresh token. Zoho Books tokens follow the standard OAuth2 authorization code flow. Construct the authorization URL: https://accounts.zoho.com/oauth/v2/auth?scope=ZohoBooks.fullaccess.all&client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REDIRECT_URI&access_type=offline The 'access_type=offline' parameter is required to get a refresh token. Paste this URL in your browser, authorize access, and Zoho will redirect to your redirect URI with a 'code' parameter in the URL. Copy that code — it expires in 10 minutes. Exchange the code for tokens via a one-time curl-equivalent: POST to https://accounts.zoho.com/oauth/v2/token with grant_type=authorization_code, client_id, client_secret, redirect_uri, and code. Use a tool like Postman, Insomnia, or the Hoppscotch browser app to make this POST request and capture the access_token and refresh_token from the response. For EU accounts, use accounts.zoho.eu; for India, use accounts.zoho.in.

Zoho Books requires multiple credentials that must all live in Lovable Cloud → Secrets, never in your frontend code or Git repository. The access token provides immediate API access, the refresh token allows obtaining new access tokens when the current one expires (Zoho access tokens expire after one hour), and the organization ID scopes every API request to your specific Zoho Books organization. In Lovable, click the '+' icon at the top of the editor to open the Cloud panel. Navigate to the Secrets tab. Add the following secrets one by one: - ZOHO_CLIENT_ID — your application's Client ID from the Zoho API Console - ZOHO_CLIENT_SECRET — your application's Client Secret from the Zoho API Console - ZOHO_ACCESS_TOKEN — the access token from the token exchange (expires hourly, will be auto-refreshed) - ZOHO_REFRESH_TOKEN — the refresh token (long-lived, used to get new access tokens) - ZOHO_ORGANIZATION_ID — your Zoho Books organization ID (found in Zoho Books → Settings → Organization Profile → Organization ID) - ZOHO_BASE_URL — the API base URL for your data center: https://www.zohoapis.com for US, https://www.zohoapis.eu for EU, https://www.zohoapis.in for India The organization ID is visible in Zoho Books under the Settings gear → Organization Profile. It is a numeric string like '20080000123456'. Every Zoho Books API request must include ?organization_id=YOUR_ID as a query parameter — forgetting this returns a 'MANDATORY_NOT_FOUND' error. Because access tokens expire hourly, your Edge Function needs to implement token refresh logic using the client credentials and refresh token.

The core Edge Function needs to handle both the API call to Zoho Books and OAuth2 token refresh when the access token expires. Zoho access tokens are valid for one hour — a production integration must automatically refresh them using the refresh token and client credentials. The token refresh flow: when a Zoho API call returns 401 (token expired), POST to the Zoho accounts token URL with grant_type=refresh_token, client_id, client_secret, and refresh_token. Zoho responds with a new access_token. Use the new token for the original API request. A gotcha with Zoho Books: you cannot update the Deno environment secrets at runtime — once the new access token is obtained via refresh, you must either store it in your Supabase database table or accept that the next cold start will use the original (possibly expired) token from secrets and refresh again. The simplest production pattern is to store the current access token in a Supabase table with an expiry timestamp, and check that table before using the secret value. The Edge Function below shows the proxy pattern for the most common operations: listing invoices, fetching a single invoice, and creating an invoice. All three go through the same token-refresh-aware fetch wrapper. For development, you can skip the auto-refresh by simply regenerating the access token in Zoho API Console and updating the ZOHO_ACCESS_TOKEN secret whenever it expires — less elegant but fine while building.

1import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
2
3const corsHeaders = {
4  'Access-Control-Allow-Origin': '*',
5  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
6}
7
8async function refreshAccessToken(): Promise<string> {
9  const clientId = Deno.env.get('ZOHO_CLIENT_ID')!
10  const clientSecret = Deno.env.get('ZOHO_CLIENT_SECRET')!
11  const refreshToken = Deno.env.get('ZOHO_REFRESH_TOKEN')!
12  const baseAccounts = Deno.env.get('ZOHO_BASE_URL')!.replace('www.zohoapis', 'accounts.zoho')
13
14  const resp = await fetch(`${baseAccounts}/oauth/v2/token`, {
15    method: 'POST',
16    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
17    body: new URLSearchParams({
18      grant_type: 'refresh_token',
19      client_id: clientId,
20      client_secret: clientSecret,
21      refresh_token: refreshToken,
22    }),
23  })
24  const data = await resp.json()
25  if (!data.access_token) throw new Error('Token refresh failed: ' + JSON.stringify(data))
26  return data.access_token
27}
28
29async function zohoFetch(path: string, options: RequestInit = {}, retry = true): Promise<Response> {
30  const baseUrl = Deno.env.get('ZOHO_BASE_URL')!
31  const orgId = Deno.env.get('ZOHO_ORGANIZATION_ID')!
32  let token = Deno.env.get('ZOHO_ACCESS_TOKEN')!
33
34  const url = `${baseUrl}/books/v3${path}${path.includes('?') ? '&' : '?'}organization_id=${orgId}`
35  let resp = await fetch(url, {
36    ...options,
37    headers: {
38      Authorization: `Zoho-oauthtoken ${token}`,
39      'Content-Type': 'application/json;charset=UTF-8',
40      ...(options.headers || {}),
41    },
42  })
43
44  if (resp.status === 401 && retry) {
45    token = await refreshAccessToken()
46    resp = await fetch(url, {
47      ...options,
48      headers: {
49        Authorization: `Zoho-oauthtoken ${token}`,
50        'Content-Type': 'application/json;charset=UTF-8',
51        ...(options.headers || {}),
52      },
53    })
54  }
55  return resp
56}
57
58serve(async (req) => {
59  if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders })
60
61  try {
62    const { action, params = {} } = await req.json()
63
64    let resp: Response
65    if (action === 'list_invoices') {
66      const query = params.contactId ? `?contact_id=${params.contactId}&status=${params.status || 'all'}` : `?status=${params.status || 'all'}`
67      resp = await zohoFetch(`/invoices${query}`)
68    } else if (action === 'get_invoice') {
69      resp = await zohoFetch(`/invoices/${params.invoiceId}`)
70    } else if (action === 'create_invoice') {
71      resp = await zohoFetch('/invoices', {
72        method: 'POST',
73        body: JSON.stringify(params),
74      })
75    } else {
76      return new Response(JSON.stringify({ error: 'Unknown action' }), {
77        status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
78      })
79    }
80
81    const data = await resp.json()
82    return new Response(JSON.stringify(data), {
83      status: resp.ok ? 200 : resp.status,
84      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
85    })
86  } catch (error) {
87    return new Response(JSON.stringify({ error: error.message }), {
88      status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
89    })
90  }
91})

With the Edge Function in place, use Lovable's chat to build the UI that consumes Zoho Books data. The most impactful first build is typically an invoice dashboard — a table showing invoice number, client name, amount, due date, and status with color-coded badges for Paid, Sent, Overdue, and Draft states. Use supabase.functions.invoke() from your React components to call the zoho-books Edge Function with the appropriate action and params. For an invoice list, invoke with action 'list_invoices'. For a specific invoice detail view, invoke with action 'get_invoice' and the invoice ID. Zoho Books API responses wrap data in a root key matching the resource: invoice list is at response.invoices[], a single invoice is at response.invoice, contacts are at response.contacts[]. Always destructure at the correct key to avoid undefined errors. For expense dashboards, the Zoho Books expenses endpoint is /expenses (action would be 'list_expenses' — add this case to your Edge Function). Expenses have category, account, amount, date, and status fields. A useful dashboard shows total spend by category using a bar chart built with Recharts (already available in Lovable's React environment). For complex integrations linking Zoho Books with your Supabase customer records, RapidDev's team can help design the data mapping between your app's user IDs and Zoho Books contact IDs.

1import { useEffect, useState } from 'react'
2import { supabase } from '@/lib/supabase'
3
4interface Invoice {
5  invoice_id: string
6  invoice_number: string
7  customer_name: string
8  total: number
9  currency_code: string
10  due_date: string
11  status: string
12}
13
14export function InvoiceDashboard() {
15  const [invoices, setInvoices] = useState<Invoice[]>([])
16  const [loading, setLoading] = useState(true)
17  const [statusFilter, setStatusFilter] = useState('all')
18
19  useEffect(() => {
20    async function fetchInvoices() {
21      setLoading(true)
22      const { data, error } = await supabase.functions.invoke('zoho-books', {
23        body: { action: 'list_invoices', params: { status: statusFilter } },
24      })
25      if (!error && data?.invoices) setInvoices(data.invoices)
26      setLoading(false)
27    }
28    fetchInvoices()
29  }, [statusFilter])
30
31  const statusColor = (status: string) => ({
32    paid: 'bg-green-100 text-green-800',
33    sent: 'bg-yellow-100 text-yellow-800',
34    overdue: 'bg-red-100 text-red-800',
35    draft: 'bg-gray-100 text-gray-800',
36  }[status.toLowerCase()] || 'bg-gray-100 text-gray-800')
37
38  return (
39    <div className="p-6">
40      <h1 className="text-2xl font-bold mb-4">Invoices</h1>
41      {loading ? <p>Loading...</p> : (
42        <table className="w-full border-collapse">
43          <thead>
44            <tr className="bg-gray-50">
45              <th className="p-3 text-left">Invoice #</th>
46              <th className="p-3 text-left">Customer</th>
47              <th className="p-3 text-right">Amount</th>
48              <th className="p-3 text-left">Due Date</th>
49              <th className="p-3 text-left">Status</th>
50            </tr>
51          </thead>
52          <tbody>
53            {invoices.map(inv => (
54              <tr key={inv.invoice_id} className="border-t">
55                <td className="p-3">{inv.invoice_number}</td>
56                <td className="p-3">{inv.customer_name}</td>
57                <td className="p-3 text-right">{inv.currency_code} {inv.total.toFixed(2)}</td>
58                <td className="p-3">{inv.due_date}</td>
59                <td className="p-3"><span className={`px-2 py-1 rounded text-xs font-medium ${statusColor(inv.status)}`}>{inv.status}</span></td>
60              </tr>
61            ))}
62          </tbody>
63        </table>
64      )}
65    </div>
66  )
67}