Most Zoho admins at Indian companies hit the same wall: workflow rules and approval processes take them 70% of the way, and then business logic gets too specific for the built-in automation tools to handle. GST invoice flagging, HSN code validation, GSTIN verification against the government API, TDS notification routing: none of these map cleanly to a standard Zoho workflow action. That is where the zoho deluge scripting tutorial becomes essential reading, not optional background knowledge.

Deluge (Data Enriched Language for the Universal Grid Environment) is Zoho’s own scripting language, built directly into Zoho CRM, Zoho Books, Zoho Creator, and Zoho Flow. You write it in the same browser tab where you configure your modules. No external IDE, no deployment pipeline. This post breaks down five patterns that collectively cover roughly 80% of the real automation tasks Indian SMB teams bring to us: fetch-and-condition logic, list and map manipulation, external API calls, triggered notifications, and cross-app data writing. Each pattern includes working code you can adapt and drop into your own Zoho instance today.

Professional woman using a laptop at her workspace with a whiteboard background.

What Is Deluge and Where Does It Run in the Zoho Ecosystem

Deluge is a server-side scripting language that executes inside Zoho’s infrastructure. You do not run it locally and you do not deploy it to a server you manage. The full Deluge language reference covers every built-in function and data type available across Zoho’s surfaces. When a workflow rule fires, a custom button is clicked, or a scheduled function triggers, Zoho’s servers execute your Deluge code against its data layer.

The four main surfaces where Deluge runs are:

Across all four surfaces, the core syntax is identical. A function receives an input map, performs operations, and can return a value. The built-in functions, zoho.crm.getRecordById, zoho.books.getInvoices, invokeUrl, sendMail, are what differentiate Deluge from general-purpose scripting languages. You are always working within Zoho’s own data connectors. If you are using ChatGPT or Claude to generate these functions, see the guide to writing Deluge scripts with AI for a prompt structure that reduces hallucinated function names.

Pattern 1: Fetch and Condition: Flag Overdue GST Invoices in Zoho Books

The fetch-and-condition pattern is the most common building block in Deluge. You retrieve a record or a list of records, check a value, and branch on the result. For Indian finance teams, one of the highest-value applications is automatically flagging GST invoices that have passed their due date without payment, which matters for GSTR-1 reconciliation and for managing your ITC (Input Tax Credit) claims.

How the pattern works

The function fetches invoices from Zoho Books using a search criteria map, iterates over the results, compares the due date to today’s date, and updates a custom field (or sends an alert) for any invoice past due. The key function is zoho.books.getInvoices(), which accepts an organisation ID and a criteria map.

// Scheduled function: runs daily, flags overdue GST invoices
void flagOverdueGSTInvoices()
{
  orgId = "YOUR_ORG_ID";
  today = today();

  criteria = map();
  criteria.put("status", "unpaid");
  criteria.put("date_before_due_date", today.toString("yyyy-MM-dd"));

  invoiceResponse = zoho.books.getInvoices(orgId, criteria);
  invoiceList = invoiceResponse.get("invoices");

  for each invoice in invoiceList
  {
    invoiceId = invoice.get("invoice_id");
    invoiceNumber = invoice.get("invoice_number");
    dueDate = invoice.get("due_date").toDate();
    gstNumber = invoice.get("gst_no");
    daysOverdue = today.diff(dueDate);

    if (daysOverdue > 0)
    {
      updateMap = map();
      updateMap.put("custom_fields",
        {
          "cf_overdue_flag": true,
          "cf_days_overdue": daysOverdue
        }
      );
      zoho.books.updateInvoice(orgId, invoiceId, updateMap);
      info "Flagged invoice " + invoiceNumber + " as overdue by " + daysOverdue + " days. GSTIN: " + gstNumber;
    }
  }
}

A few notes specific to Indian company setups: the gst_no field in Zoho Books maps to the customer’s GSTIN. If your Books is configured with GST enabled, invoices also carry tax_id values for CGST, SGST, and IGST line items. You can extend this loop to check whether the tax type is IGST (interstate) and apply a different escalation path than for intrastate invoices, which is a common requirement for companies with branches across multiple states.

Pattern 2: Map and List Manipulation: Aggregate HSN Codes from Sales Order Line Items

Maps and lists are the data structures you will use constantly in Deluge. A map is a key-value collection (equivalent to a dictionary or object in other languages). A list is an ordered collection. The manipulation pattern covers building these structures, iterating over them, deduplicating, and formatting them for output or for writing back to a record.

A practical example from GST compliance: when raising a sales order in Zoho Books or Zoho CRM, each line item carries an HSN (Harmonised System of Nomenclature) code. Before submitting to the e-invoice portal, finance teams often need a deduplicated summary of all HSN codes in the order, along with taxable values per code, to cross-check against the GST rate applicable to each.

// Custom button function on Sales Order record in Zoho CRM
// Input: salesOrderId (string)
void aggregateHSNCodes(string salesOrderId)
{
  soRecord = zoho.crm.getRecordById("Sales_Orders", salesOrderId);
  lineItems = soRecord.get("Product_Details");

  hsnMap = map();

  for each item in lineItems
  {
    hsnCode = item.get("HSN_Code").toString();
    taxableAmount = item.get("Total").toDecimal();

    if (hsnMap.containsKey(hsnCode))
    {
      existing = hsnMap.get(hsnCode).toDecimal();
      hsnMap.put(hsnCode, existing + taxableAmount);
    }
    else
    {
      hsnMap.put(hsnCode, taxableAmount);
    }
  }

  summaryLines = list();
  for each entry in hsnMap
  {
    hsnKey = entry.getKey();
    hsnVal = entry.getValue().toDecimal().round(2);
    summaryLines.add(hsnKey + ": INR " + hsnVal);
  }

  summaryText = summaryLines.toString(",");

  updateMap = map();
  updateMap.put("HSN_Summary", summaryText);
  zoho.crm.updateRecord("Sales_Orders", salesOrderId, updateMap);

  info "HSN aggregation complete: " + summaryText;
}

The containsKey() check prevents you from overwriting an existing total when the same HSN code appears on multiple line items, which is common in orders that mix product variants from the same category. The round(2) call keeps decimal values clean before writing back to a text field. For orders with 50+ line items, this pattern runs in well under a second on Zoho’s execution environment.

Hands working on financial data analysis with charts and graphs, using pens and highlighters.

Pattern 3: invokeUrl: Call the GST GSTIN Validation API

The invokeUrl function in Deluge lets you make HTTP requests to any external endpoint: REST APIs, webhook receivers, third-party services. For Indian businesses, the most common use case is hitting the GST government API, either the public GSTIN lookup endpoint or the NIC e-invoice portal.

This pattern handles the zoho crm api and webhooks handshake from the Deluge side: you construct the request, parse the JSON response, and act on the result, all within the same function.

GSTIN validation example

The GST public API endpoint returns registration status, legal name, and state jurisdiction for any GSTIN. Before creating a B2B invoice in Zoho Books, you can validate the buyer’s GSTIN programmatically.

// Custom function triggered on Contact save in Zoho CRM
// Input: contactId (string), gstin (string)
void validateGSTIN(string contactId, string gstin)
{
  if (gstin.length() != 15)
  {
    info "Invalid GSTIN length for contact " + contactId;
    return;
  }

  apiUrl = "https://api.gst.gov.in/commonapi/search?action=TP&gstin=" + gstin;

  headers = map();
  headers.put("Content-Type", "application/json");
  headers.put("Accept", "application/json");

  response = invokeUrl
  [
    url: apiUrl
    type: GET
    headers: headers
  ];

  responseCode = response.get("responseCode").toInteger();

  if (responseCode == 200)
  {
    taxpayerInfo = response.get("taxpayerInfo");
    legalName = taxpayerInfo.get("lgnm");
    status = taxpayerInfo.get("sts");
    stateCode = gstin.subString(0, 2);

    updateMap = map();
    updateMap.put("GSTIN_Legal_Name", legalName);
    updateMap.put("GSTIN_Status", status);
    updateMap.put("GSTIN_State_Code", stateCode);

    if (status != "Active")
    {
      updateMap.put("GSTIN_Flag", "Inactive GSTIN - verify before invoicing");
    }

    zoho.crm.updateRecord("Contacts", contactId, updateMap);
    info "GSTIN validated: " + legalName + " | Status: " + status;
  }
  else
  {
    info "GSTIN API call failed with code: " + responseCode;
  }
}

Note that the GST API requires authentication tokens in production. The above pattern shows the structural shape of the call. In a real deployment, you would store your auth token in Zoho’s encrypted custom field or retrieve it from a Zoho Creator record, then include it in the headers map as a bearer token. Never hardcode API credentials in Deluge function bodies.

For companies processing high invoice volumes, say, a Pune-based distributor processing 300 to 500 B2B invoices per month, running this validation on Contact save catches bad GSTINs before the invoice is even drafted, avoiding rejection at the e-invoice portal stage.

Pattern 4: sendMail and Notifications: TDS Deduction Alerts to Your Finance Team

The sendMail task in Deluge sends an email from within a function, with full control over recipient, subject, body, and dynamic field values. This is different from Zoho CRM’s built-in email alert action: here, you construct the email content programmatically, so you can include computed values, conditional text, and data pulled from multiple records.

A high-value application for Indian companies is TDS (Tax Deducted at Source) deduction alerts. When a vendor bill above INR 30,000 is recorded in Zoho Books (the threshold for TDS under Section 194C for contractor payments), the finance team needs a notification with the vendor’s PAN, the bill amount, the TDS rate applicable, and the computed TDS deduction amount.

// Workflow function on Vendor Bills in Zoho Books
void sendTDSAlert(string billId, string orgId)
{
  billRecord = zoho.books.getBill(orgId, billId);
  vendorId = billRecord.get("vendor_id");
  vendorName = billRecord.get("vendor_name");
  billAmount = billRecord.get("total").toDecimal();
  billNumber = billRecord.get("bill_number");
  billDate = billRecord.get("date");

  vendorRecord = zoho.books.getContact(orgId, vendorId);
  vendorPAN = vendorRecord.get("pan_no");

  vendorType = vendorRecord.get("cf_vendor_type");
  tdsRate = 2.0;
  if (vendorType == "Individual" || vendorType == "HUF")
  {
    tdsRate = 1.0;
  }

  tdsAmount = (billAmount * tdsRate / 100).round(2);
  netPayable = (billAmount - tdsAmount).round(2);

  emailBody = "TDS Deduction Notice\n\nVendor: " + vendorName + "\nPAN: " + vendorPAN + "\nBill Number: " + billNumber + "\nBill Date: " + billDate + "\nBill Amount: INR " + billAmount + "\nTDS Section: 194C\nTDS Rate: " + tdsRate + "%\nTDS Deduction: INR " + tdsAmount + "\nNet Payable to Vendor: INR " + netPayable;

  sendMail
  [
    from: zoho.loginuserid
    to: "finance@yourcompany.in"
    cc: "accounts@yourcompany.in"
    subject: "TDS Alert: " + vendorName + " | Bill " + billNumber + " | INR " + tdsAmount + " to deduct"
    message: emailBody
  ];

  info "TDS alert sent for bill " + billNumber + ". TDS: INR " + tdsAmount;
}

Extend this pattern by adding a list of recipients based on bill amount thresholds: bills above INR 5 lakh might also notify the CFO. You can build the to field as a list and pass it directly. The sendMail task accepts both string and list types for the recipient fields.

Pattern 5: Inter-App Data Push: Auto-Create a Zoho Books Contact on CRM Deal Won

Writing data across Zoho applications from a single Deluge function is one of the most powerful things you can do in the platform. When a deal moves to Closed Won in Zoho CRM, the corresponding account typically needs to exist as a customer contact in Zoho Books before the first invoice can be raised. Doing this manually adds a step that gets missed, leading to delays in billing.

This pattern reads the CRM account, maps its fields to the Books contact schema, and creates the record via zoho.books.createContact(). This is also where zoho crm automation workflows and Deluge functions work together most visibly: the workflow rule fires on stage change, which triggers the Deluge function, which writes to Books.

// CRM Workflow function: triggers on Deal Stage = "Closed Won"
void createBooksContactFromCRMDeal(string dealId)
{
  dealRecord = zoho.crm.getRecordById("Deals", dealId);
  accountId = dealRecord.get("Account_Name").get("id");
  accountRecord = zoho.crm.getRecordById("Accounts", accountId.toString());

  accountName = accountRecord.get("Account_Name");
  billingStreet = accountRecord.get("Billing_Street");
  billingCity = accountRecord.get("Billing_City");
  billingState = accountRecord.get("Billing_State");
  billingZip = accountRecord.get("Billing_Code");
  phone = accountRecord.get("Phone");
  website = accountRecord.get("Website");
  gstin = accountRecord.get("GSTIN__c");

  orgId = "YOUR_BOOKS_ORG_ID";

  searchCriteria = map();
  searchCriteria.put("contact_name_contains", accountName);
  existingContacts = zoho.books.getContacts(orgId, searchCriteria);

  if (existingContacts.get("contacts").size() > 0)
  {
    info "Books contact already exists for: " + accountName + ". Skipping creation.";
    return;
  }

  contactMap = map();
  contactMap.put("contact_name", accountName);
  contactMap.put("contact_type", "customer");
  contactMap.put("phone", phone);
  contactMap.put("website", website);
  contactMap.put("gst_no", gstin);
  contactMap.put("gst_treatment", "business_gst");

  billingAddress = map();
  billingAddress.put("address", billingStreet);
  billingAddress.put("city", billingCity);
  billingAddress.put("state", billingState);
  billingAddress.put("zip", billingZip);
  billingAddress.put("country", "India");
  contactMap.put("billing_address", billingAddress);

  createResponse = zoho.books.createContact(orgId, contactMap);
  newContactId = createResponse.get("contact").get("contact_id");

  crmUpdate = map();
  crmUpdate.put("Books_Contact_ID__c", newContactId);
  zoho.crm.updateRecord("Accounts", accountId.toString(), crmUpdate);

  info "Created Books contact: " + accountName + " (ID: " + newContactId + ")";
}

The duplicate check using getContacts with a name filter is important. Without it, re-triggering the workflow creates duplicate contacts in Books, which causes reconciliation problems later. The write-back of the Books contact ID to the CRM Account creates a reference link that your team can use for future lookups.

Software developer typing code on dual monitors at a wooden desk.

Debugging Deluge: Logs, Sandbox Testing, and Common Errors

The info statement is your primary debugging tool. Every info call writes to the Deluge execution log, which you can view under Setup > Developer Space > Deluge Logs in Zoho CRM, or in the function editor’s console panel in Zoho Creator. Use it liberally during development and strip it down to only essential logging in production.

Sandbox testing

Zoho CRM’s Sandbox environment (available on Enterprise and above) lets you test Deluge functions against a copy of your production data without affecting live records. For Books, you can use a test organisation. Always test functions that write to multiple apps in sandbox first.

Common errors and how to fix them

ErrorCauseFix
Type mismatch on arithmeticField returned as string, used in calculationCast with .toDecimal() or .toInteger() before any arithmetic
Null fetch returnRecord not found, or field does not existCheck if (record != null) before calling .get() on the result
invokeUrl timeoutExternal API too slow or unreachableAdd a responseCode check; log failures; do not block the workflow on API response
Concurrent execution limit hitScheduled function running too frequentlyUse criteria filters to limit result set; split into multiple scheduled batches
Connection not authorisedzoho.books or zoho.crm connection missing required scopeRe-authenticate under Setup > Connected Apps and add the missing scope

The most common production issue in our experience with Indian SMB Zoho deployments is the type mismatch error. Zoho CRM currency fields, number fields, and formula fields all return as strings when fetched via getRecordById. Cast them explicitly before any arithmetic, every time.

Where to Deploy Each Pattern in Zoho

Knowing where to wire a Deluge function is as important as writing it correctly. The deployment surface determines when your function fires, what inputs it receives, and what permissions it runs under.

PatternRecommended Deployment SurfaceTrigger Type
Fetch and condition (GST invoice flag)Zoho Books Scheduled FunctionDaily schedule (e.g., 8:00 AM IST)
Map and list manipulation (HSN aggregation)CRM Custom Button on Sales OrderOn-demand, user-triggered
invokeUrl (GSTIN validation)CRM Workflow Rule on Contact saveRecord create or edit event
sendMail (TDS alert)Books Workflow Function on Vendor BillRecord create, when amount exceeds threshold
Inter-app data push (Books contact creation)CRM Workflow Rule on Deal stage changeField update event (Stage = Closed Won)

Blueprint functions in Zoho CRM are worth adding to your deployment toolkit for any pattern that needs to enforce a sequence. If your sales process requires GSTIN validation to be completed before a deal can progress from Proposal to Negotiation, a Blueprint transition with a Deluge function check is more reliable than a workflow rule, because the Blueprint blocks the stage change if the function returns false.

Frequently Asked Questions

Does a zoho deluge scripting tutorial apply equally to Zoho CRM and Zoho Books, or is the syntax different between apps?

The core Deluge syntax is the same across all Zoho applications. The differences are in the built-in connector functions available on each surface. In Zoho CRM you use zoho.crm.* functions; in Zoho Books you use zoho.books.* functions; in Zoho Creator you have access to both plus zoho.creator.* for Creator-specific data. The data types, loop syntax, map and list methods, and control structures are identical everywhere.

How do I handle GST-specific fields like CGST, SGST, and IGST in Deluge when fetching invoice data from Zoho Books?

When you fetch an invoice using zoho.books.getInvoiceById(), the response includes a taxes list. Each element contains a tax_name (such as “CGST 9%” or “IGST 18%”), a tax_amount, and a tax_percentage. You iterate over this list and check the tax_name string to identify which component you are working with. For interstate transactions, you will find only an IGST entry; for intrastate, you will find CGST and SGST entries.

What is the execution time limit for a Deluge function, and does it affect how I design the patterns above?

Zoho enforces a maximum execution time of around 60 seconds for most Deluge functions, with a 16MB memory cap for data fetched in a single function run. For scheduled functions that process large data sets, use the page parameter in getInvoices() to paginate results and process 200 records per run rather than attempting to load all records at once. Design for pagination from the start on any function that touches more than a few hundred records.

Can I call the NIC e-invoice API directly from Deluge using invokeUrl, or does that require a middleware layer?

You can call the NIC e-invoice API directly from Deluge using invokeUrl. The API uses OAuth 2.0 and requires a session token obtained by a prior authentication call. Make a first invokeUrl call to the authentication endpoint, extract the AuthToken from the response, and pass it in the headers of subsequent calls. Store the token in a Zoho Creator record or an encrypted custom field with an expiry timestamp, so you are not re-authenticating on every function call.

How do I test a Deluge function that writes to Zoho Books without affecting real financial data?

Create a separate Zoho Books organisation for testing and use its organisation ID in your Deluge function during development. Zoho allows multiple organisations under one account. Switch the orgId variable to your production org ID only after the function has been validated end-to-end in the test environment. For CRM functions, use Zoho’s built-in Sandbox environment if you are on an Enterprise plan.

Need these patterns deployed in your Zoho instance? Aaxonix builds production-ready Deluge functions for Indian SMBs: GST automation, TDS workflows, inter-app integrations, and custom reporting logic.

Talk to a Zoho Developer

The five patterns above cover the majority of real automation requirements that Zoho admins at Indian companies encounter: conditional record processing for GST compliance, data aggregation across line items, external API calls to government endpoints, dynamic email notifications for TDS, and cross-app data writing between CRM and Books. Pick the pattern closest to your current problem, adapt the code to your field names and organisation IDs, and deploy it to the appropriate surface using the deployment table above. If you get stuck on a specific pattern or need a custom variation built for your industry, see our full range of Zoho implementation and development services or reach out to the Aaxonix team directly.