> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tirdad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Zoho Books Connection Setup

> Complete guide to setting up and configuring Zoho Books connections in Tirdad

## Overview

A Zoho Books connection in Tirdad stores encrypted credentials that allow the system to interact with your Zoho Books organization for:

* Connecting to Zoho Books using OAuth
* Syncing invoices from Tirdad to Zoho Books
* Creating and matching contacts in Zoho Books when invoices sync
* Receiving webhook notifications from Zoho Books
* Reconciling invoice payments and voids between Zoho Books and Tirdad

## Prerequisites

Before setting up your Zoho Books connection, ensure you have:

1. **Zoho Books Organization** - Admin access to a Zoho Books organization with API access
2. **Zoho API Console Application** - Client ID and Client Secret from [Zoho API Console](https://api-console.zoho.com/) (or your region’s console)
3. **OAuth Redirect URI** - The callback URL Tirdad uses for OAuth, registered exactly under your app’s authorized redirect URIs in Zoho
4. **Tirdad Environment** - Valid Tirdad tenant and environment for the connection
5. **Webhook Secret** - A strong value **you invent** (Zoho does **not** provide one by default). **Type the exact same string** in Zoho’s webhook settings **and** in Tirdad (recommended; used to verify `X-Zoho-Webhook-Signature`)

## Step 1: Gather Zoho Books Credentials

### Required Credentials

| Credential          | Location                                                                                       | Required    | Purpose                                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------- |
| **Client ID**       | Zoho API Console                                                                               | ✅           | OAuth app identifier; starts the Zoho sign-in flow                                                      |
| **Client Secret**   | Zoho API Console                                                                               | ✅           | Completes token exchange after user consent                                                             |
| **Redirect URI**    | Zoho API Console → Authorized Redirect URIs                                                    | ✅           | Must match Tirdad’s OAuth callback URL for your deployment and region                                   |
| **Organization ID** | Zoho Books (organization settings / URL)                                                       | ✅           | Identifies which Zoho Books org Tirdad calls                                                            |
| **Accounts server** | Zoho Accounts region                                                                           | ✅           | OAuth and API host context (for example `https://accounts.zoho.in`, `https://accounts.zoho.com`)        |
| **Webhook Secret**  | **You type it** in Zoho Books (webhook action) **and** again in Tirdad—same string both places | Recommended | Zoho does **not** auto-generate this; both sides must match for `X-Zoho-Webhook-Signature` verification |

### Finding Your Client ID and Client Secret

1. Go to [Zoho API Console](https://api-console.zoho.com/) (or your Zoho region’s API console).
2. Create or open an application for **Server-based Applications** (or the application type your organization uses for Zoho Books).
3. Copy the **Client ID** and **Client Secret**.
4. Under **Authorized Redirect URIs**, add Tirdad’s OAuth callback (for example `https://app.tirdad.ai/tools/integrations/oauth/` for Tirdad Cloud—use the exact URL your deployment shows if it differs).
5. Save the application.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/tirdad/images/docs/integrations/zoho-books/zoho_console.png" alt="Zoho API Console — app details, homepage URL, and authorized redirect URI" />
</Frame>

## Step 2: Configure Zoho Books Webhooks

Zoho Books uses **webhook rules** (when something happens) and **actions** (for example **notify URL** / POST to an endpoint). For a full integration, configure **two** webhooks:

1. **Invoices** - So Tirdad can process **paid** and **voided** invoice events.
2. **Customers** - So Tirdad can create **customers** when a **customer is created** in Zoho Books (workflow on the **Customers** module; **customer inbound** sync is **on by default** on the connection).

Both webhooks should use the **same** Tirdad URL pattern below. Use the **tenant** and **environment** IDs from the Tirdad dashboard for the workspace where the connection will live.

**Webhook URL Format:**

```
https://<your-tirdad-api-host>/v1/webhooks/zoho_books/<tenant_id>/<environment_id>
```

For Tirdad Cloud, the host is often `https://api.tirdad.ai`. Replace `<tenant_id>` and `<environment_id>` with your Tirdad IDs. For other regions or deployments, use the API base URL your organization was given (for example `https://api.tirdad.ai`).

If webhooks return success but Tirdad does not update data, confirm the **tenant** and **environment** in the path match the environment where Zoho Books is connected.

### Webhook secret (type the same value in Zoho and Tirdad)

Zoho Books does **not** give you a webhook signing secret to copy. The field is empty unless **you** fill it: you choose a strong secret (for example a long random string), then **type that exact same characters** everywhere it is asked for.

1. **Choose one secret** and use it for **both** workflow webhooks (invoice and customer), so Tirdad only stores a single value.
2. When you add the **webhook** action in Zoho, **type** that secret into Zoho’s webhook / signing secret field (wording varies by screen)—do not look for a value Zoho generated; there isn’t one by default.
3. In Tirdad (**Step 3**), **type the same secret** into the **Webhook secret** field on the Zoho Books connection.

There is nothing to “copy from Zoho”—only the same string **typed** in Zoho and in Tirdad. It does not matter whether you enter it in Zoho or in Tirdad first, as long as both match. If you change the secret, update **both** places.

### Webhook 1 — Invoices (Paid and Voided)

Create a **workflow** on the **Invoice** module (for example when an invoice is **edited** and **status** is updated) so changes such as **Paid** or **Void** are sent to Tirdad. Add a **webhook** immediate action that **POST**s to your Tirdad webhook URL.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/tirdad/images/docs/integrations/zoho-books/zoho_invoice_webhook.png" alt="Zoho Books — Invoice workflow: status updates trigger webhook to Tirdad" />
</Frame>

### Webhook 2 — Customers (Inbound Customer Sync)

Create a second workflow on the **Customers** module for **customer created** (all customers or your criteria), with a webhook action posting to the **same** Tirdad URL as the invoice rule. **Customer inbound** sync is **on by default** on the connection; turn it off only if you do not want new Zoho customers to create Tirdad customers.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/tirdad/images/docs/integrations/zoho-books/zoho_customer_webhook.png" alt="Zoho Books — Customers workflow: customer created triggers webhook to Tirdad" />
</Frame>

## Step 3: Create Zoho Books Connection

### Using Tirdad Dashboard

You can create a Zoho Books connection from the Tirdad dashboard:

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Tirdad dashboard** → **Integrations** → **Zoho Books** (or **Accounting**) → **Connect** / **Add connection**.
  </Step>

  <Step title="Enter connection details">
    Fill in **Connection name**, **Client ID**, and **Client Secret** from the Zoho API Console. Add your Zoho Books **organization ID** and the **accounts server** for your region (for example `https://accounts.zoho.in` or `https://accounts.zoho.com`). Copy the **webhook URL** from the modal into each Zoho Books webhook. In **Webhook secret**, **type the same value** you use in Zoho’s webhook / signing-secret field (**character-for-character**). You pick that value yourself—Zoho does not provide one. You can update this field later if you rotate the secret.
  </Step>

  <Step title="Complete OAuth">
    Complete sign-in and consent in Zoho. Tirdad exchanges the authorization code for tokens, stores them encrypted, and associates the connection with your Zoho **organization**. Access tokens refresh automatically.
  </Step>

  <Step title="Review sync settings">
    **Invoice** outbound sync and **customer** inbound sync are **on by default** for a new connection. Change them only if you do not want invoices pushed to Zoho or new Zoho contacts imported into Tirdad.
  </Step>
</Steps>

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/tirdad/images/docs/integrations/zoho-books/zoho_tirdad_connection.png" alt="Tirdad — Connect to Zoho Books modal (credentials, org ID, accounts server, webhook URL and secret)" />
</Frame>

## Customer Sync

Tirdad can keep customers aligned **toward Zoho** (with invoice sync) and **from Zoho** (via webhooks). On the connection, **invoice outbound** and **customer inbound** sync are **on by default**; you can turn either off if you do not want that behavior.

### Tirdad → Zoho Books (contacts on the Zoho side)

**Default:** **Invoice outbound** sync is **on by default** (see [Sending invoices to Zoho](#sending-invoices-to-zoho-outbound)). If someone turned it off, enable it again on the connection to push invoices—and the related contacts—to Zoho.

**What happens:** Whenever Tirdad **creates an invoice in Zoho Books**, it also **creates or matches a contact** in Zoho for that invoice’s Tirdad customer. You do not maintain that contact separately before the invoice sync runs.

### Zoho Books → Tirdad (new customers in Tirdad)

**Default:** **Customer inbound** sync is **on by default** on the connection.

**Also required in Zoho:** Inbound only works when Zoho can reach Tirdad. In Zoho Books, configure the **customer created** webhook from [Step 2](#step-2-configure-zoho-books-webhooks) so Zoho notifies Tirdad when customers are created.

**What happens:** A **new customer** in Zoho Books can become a **new customer** in Tirdad. **Vendor** records are ignored. If the customer’s **email** already exists on a Tirdad customer, Tirdad **links** to that customer instead of creating a second one.

## Invoice Sync

### Sending invoices to Zoho (outbound)

**Default:** **Invoice outbound** sync is **on by default** on a new connection. Disable it only if you do not want Tirdad to create invoices in Zoho Books.

**What happens:** After a Tirdad invoice is **eligible to sync** to your accounting system (same rules as other Tirdad accounting integrations), Tirdad **creates a corresponding invoice** in Zoho Books. You do not manually re-enter that invoice in Zoho.

### How line items appear in Zoho

Zoho Books receives one line per Tirdad line so **totals stay aligned**:

* **Quantity** is always **1** per line.
* **Rate** is set to the **full amount** of that Tirdad line (so the line total in Zoho equals the Tirdad line amount).

### Currency and exchange rates

Zoho Books uses an organization **base currency**. If the Tirdad invoice uses a **different currency**:

1. In Zoho Books, open **Settings → Currencies**.
2. **Add** that invoice currency if it is missing.
3. Set a **positive exchange rate** from that currency to your **base** currency.

If this is missing or invalid, Zoho may **reject** the invoice Tirdad tries to create.

### Invoice updates from Zoho (webhooks)

This applies when the Zoho invoice was **originally created from Tirdad** (so both systems are linked).

| Event in Zoho      | What Tirdad does                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| Invoice **paid**   | Records payment and updates the Tirdad invoice status (safe to retry if Zoho sends the event more than once). |
| Invoice **voided** | Voids the linked Tirdad invoice when the workflow allows it.                                                  |

Other changes in Zoho (edits, partial updates, unrelated fields) are **not** continuously copied back into Tirdad; only these webhook-driven outcomes are handled.

## Security Best Practices

### Credential Management

1. **Environment separation** - Use separate Zoho API applications or organizations for development and production where possible.
2. **Secret rotation** - Rotate the Zoho **Client Secret** in the API Console if needed. For webhooks, set a **new** secret in both Zoho workflow actions and the Tirdad connection together.
3. **Encryption** - Tirdad stores connection secrets encrypted at rest.

### Webhook Security

1. **HTTPS only** - Use HTTPS for the webhook URL.
2. **Signature verification** - Store the **same** user-defined webhook secret on the Tirdad connection as in Zoho so Tirdad can verify `X-Zoho-Webhook-Signature`.
3. **Correct URL path** - Incorrect **tenant** or **environment** in the URL prevents Tirdad from loading the connection even when the HTTP request succeeds.

## Troubleshooting

| Issue                                             | Cause                              | Solution                                                                                                                           |
| ------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Webhook does not update Tirdad                    | Wrong tenant or environment in URL | Use the exact **tenant** and **environment** IDs from Tirdad for the org where the connection exists                               |
| Invalid webhook signature                         | Secret mismatch                    | The string in Zoho’s webhook action and in Tirdad must be **identical**; update both sides if you rotate the secret                |
| Invoice fails to sync to Zoho                     | Currency or exchange rate          | In **Settings → Currencies**, add the invoice currency with a **positive** rate against **base** currency                          |
| New Zoho customer does not create Tirdad customer | Inbound off or missing webhook     | Confirm **customer inbound** is on (default is on); ensure the **customer created** webhook in Zoho targets the correct Tirdad URL |
| Paid in Zoho but Tirdad invoice unpaid            | Missing entity mapping             | The Zoho invoice typically must have been created from Tirdad so entity integration mapping links both sides                       |

## Next Steps

After setting up your Zoho Books connection:

1. **Verify the connection** - Confirm the connection shows as active in Tirdad.
2. **Test invoice sync** - With outbound invoice sync on, create or finalize a test invoice and confirm it appears in Zoho Books.
3. **Test payment reconciliation** - Mark the invoice paid in Zoho and confirm Tirdad reflects payment status.
4. **Test customer sync (optional)** - With inbound customer sync on, create a customer in Zoho Books and confirm a customer appears in Tirdad.