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

# Zoho Billing

> Connect Zoho Billing to Numeral to automatically calculate and apply accurate sales tax on your subscriptions, invoices, and quotes.

Numeral connects to your Zoho Billing account and automatically calculates the correct sales tax on your **subscriptions, invoices, and quotes**, then writes that tax back onto them in Zoho.

Once connected, whenever a subscription, invoice, or quote is created or changed, Numeral calculates the tax for the customer's address and applies it in Zoho — no manual tax entry needed.

***

## Before you begin

You'll need:

* A **Numeral account** with access to the **Connections** page.
* A **Zoho Billing account**, and you must be signed in as a user with **admin permissions** (you'll be asked to authorize Numeral, and later to add webhooks in Zoho's settings).
* Your business's **ship-from (origin) address** — the address your products or services are sold from. Numeral uses it as the origin for tax calculations. (If you've already set this in Numeral, you won't be asked again.)

Keep both browser tabs handy — you'll finish in Numeral, then do one step inside Zoho Billing.

***

## Step 1 — Start the connection

1. In Numeral, go to **Connections**.
2. Click **Add connection**.
3. Choose **Zoho Billing**.
4. On the "Connect Zoho Billing" screen, click **Connect to Zoho Billing**.

## Step 2 — Authorize Numeral in Zoho

You'll be redirected to Zoho to sign in and approve the connection.

1. Sign in to Zoho (if you aren't already).
2. Review the permissions and click **Accept** to grant Numeral access.

You'll be returned to Numeral automatically.

<Note>
  Numeral requests access to your Zoho Billing data so it can read your subscriptions, invoices, and quotes and write the calculated tax back onto them.
</Note>

## Step 3 — Select your organization

If your Zoho account has more than one organization, choose the one you want to connect from the dropdown, then click **Continue**.

## Step 4 — Confirm your ship-from address

If Numeral doesn't already have an origin address on file, enter your business's **ship-from address** and click **Save & continue**. This is used as the origin address for every tax calculation on your Zoho Billing transactions.

## Step 5 — Add webhooks in Zoho Billing (important)

This is the one step you complete **inside Zoho Billing**. Webhooks are how Zoho tells Numeral when something changes so tax can be calculated in time. Numeral can't add these for you, so the final screen gives you everything to paste.

On the final Numeral screen you'll see:

* A **shared secret** — paste this into *every* webhook you create.
* One **section per webhook**, each with a **label**, a **Zoho module**, the **events** to check, and a unique **URL**.

In Zoho Billing:

1. Open **Settings → Automation → Workflow Actions → Webhooks**.
2. For **each** section shown in Numeral, create **one webhook**:
   * Set the **method** to **POST**.
   * Set the **Module** to the one listed for that section.
   * **Check the events** listed for that section.
   * Paste that section's **URL**.
   * Turn on **"I want to secure this webhook"** and paste the **shared secret**.
3. Save each webhook.
4. Back in Numeral, click **Done**.

### The webhooks Numeral asks for

| Webhook                                            | Zoho module   | Events to check                                                                                                                        | Why                                                                                                                                |
| -------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Subscription changes**                           | Subscriptions | New Subscription, Subscription Activation, Upgrade Subscription, Downgrade Subscription, Reactivate Subscription, Billing Date Changed | Calculates tax and applies it to the subscription whenever it changes.                                                             |
| **Subscription renewal (upcoming)**                | Subscriptions | Subscription Renewal Ahead *(under the Scheduled Events tab)*                                                                          | Refreshes tax a few days before renewal so the renewal invoice bills the current rate.                                             |
| **Standalone invoices**                            | Invoices      | Invoice Created, Invoice Modified                                                                                                      | Calculates tax on one-off (non-subscription) invoices. Subscription-generated invoices are handled automatically and skipped here. |
| **Quotes (estimates)**                             | Estimates     | Estimate Created, Estimate Modified                                                                                                    | Calculates tax on quotes/estimates.                                                                                                |
| **Product changes (plans & add-ons)** *(optional)* | Products      | Product Added, Product Updated, Product Activated, Product Inactivated                                                                 | Keeps your plan/add-on catalog in sync with Numeral so each can be tax-classified.                                                 |

<Note>
  Most webhook events live under **Immediate Events**. The one exception is **Subscription Renewal Ahead**, which is under the **Scheduled Events** tab.

  The exact URLs are unique to your connection and are shown on the setup screen — always copy them from there rather than typing them.
</Note>

Your Zoho Billing account is now connected. 🎉

***

## After connecting: classify your products

Numeral taxes each product based on its **tax category**. When your plans and add-ons first sync in, they're assigned a **default category**, which may not be right for what you sell — for example, a plan may default to a general "services" category that is tax-exempt in some states.

To make sure tax is calculated correctly, review your products in Numeral and assign each one the correct tax category. A misclassified product is the most common reason a tax rate looks wrong (for example, showing 0% when you expected tax to apply).

***

## What to expect

* **Subscriptions:** Numeral writes the tax rate onto the subscription's plan and add-ons. The next invoice the subscription generates bills that rate automatically.
* **Standalone invoices & quotes:** Numeral writes the tax directly onto each line item (and onto shipping, if the document has a shipping charge).
* **Subscription-generated invoices:** already taxed via the subscription, so Numeral leaves them alone (no double-taxing).
* **Credit notes:** keep the tax from the invoice they credit — Numeral does not recalculate them, so you always credit back exactly what was charged.
* **Tax-exempt customers:** if a customer is marked not taxable in Zoho, Numeral skips them and applies no tax.

<Note>
  Numeral only ever changes the **tax** on your documents — it never edits your prices, quantities, or other details.
</Note>

***

## Troubleshooting

**"No organizations found" after authorizing.**
Make sure you signed in to the correct Zoho account and that it has at least one Zoho Billing organization, then try connecting again.

**"This organization is already connected."**
That organization is already linked to Numeral. Pick a different organization, or disconnect the existing connection first.

**A tax rate looks wrong (e.g. 0%).**
Almost always a product classification issue — check that the product's tax category in Numeral matches what you actually sell (see *classify your products* above).

**Tax isn't being applied to new documents.**
Confirm the relevant webhook exists in Zoho Billing (**Settings → Automation → Workflow Actions → Webhooks**), that its events are checked, and that the shared secret was entered. Re-open the connection in Numeral to view the webhook setup again if needed.

**Need to reconnect.**
You can re-run the setup from the **Connections** page at any time; the webhook setup screen (including the secret and URLs) is shown again during setup.

***

## Need help?

Reach out to your Numeral implementation contact or email [support@numeralhq.com](mailto:support@numeralhq.com).