Solving the bug in Zoho Writer API for styling

Solving the bug in Zoho Writer API for styling

So... the Zoho Writer APIs for programatically creating a document do not respect a template's style. The result is that any document you generate via API needs to be manually, paragraph by paragraph, reformatted.  That bug alone is sufficient to render Writer almost unworkable for any real-world usage.  (Who is responsible for product management and design quality? Yes, it is another example of developer-led programming short-cuts in Zoho!)

However, after a day of messing about, I found a workaround.  See the following markdown exploration of the issue and how to manually set the fonts, etc to match a templated document. The big problem with this is, of course, it requires a manual update should any templates change, and it needs to be aligned to every possible template.  Not ideal.

Zoho - can you please alter the way Zoho Writer handles importing basic formatting (eg. HTML headers, etc.) so that they respect the Writer template's existing styles.  Sure it can't be that difficult.   Also not, this happens if you insert RTF into a merge field... so it is not just the APIs.  The lack of basical style support means the entire templating system and generation of docs is broken from the ground up.  There is no way we can risk generating docs for automatic download or emailing with the product ion the current state. 

If I have missed something obvious in the documentation, please let me know. I would be very happy to wrotng about this problem.

For everyone else, enjoy the code.



  1. # How to Preserve Template Styles When Using the Zoho Writer Merge API

    ## The Problem

    When using the Zoho Writer Merge API to generate documents from templates, the merged content does not inherit the template's custom paragraph styles. Instead, standard HTML tags like `<h1>`, `<h2>`, `<h3>`, and `<p>` are rendered with default styling (Liberation Serif, browser-default sizes, black text, bold headings) — completely ignoring the font families, colours, and sizes defined in the template's stylesheet.

    This means if your template defines Heading 1 as *Heuristica 18pt dark blue*, your merged `<h1>` content will appear as *Liberation Serif 24pt bold black* instead.

    ## Root Cause

    The Zoho Writer Merge API accepts HTML in richtext merge fields. However, when it processes standard HTML heading tags (`<h1>` through `<h6>`), it:

    1. Maps them to Writer's internal heading classes (`heading1`, `heading2`, etc.)
    2. Applies **default inline styles** on the rendered spans — overriding the template's CSS-defined styles
    3. HTML heading tags also carry **implicit bold** (`font-weight: bold`) which may not match the template

    The template's stylesheet defines styles like:

    ```css
    #editorpane div.heading1 span.zw-portion {
        font-family: Heuristica, Georgia;
        font-size: 18pt;
        color: rgb(0, 32, 96);
    }
    ```

    But the merge engine ignores these and applies its own defaults inline.

    ## The Solution

    Instead of using semantic HTML heading tags, use `<p>` tags for **all** content and apply the template's exact styles as inline CSS. This prevents Writer from applying default heading styles, and gives you full control over the rendered appearance.

    ### Step 1: Extract Your Template's Styles

    Open your template in Zoho Writer, save the page as HTML (browser "Save As"), and inspect the stylesheet block. Look for the `#editorpane div.headingN span.zw-portion` rules:

    ```css
    /* Example from an IBRS template */
    #editorpane div.heading1 span.zw-portion {
        font-family: Heuristica, Georgia;
        font-size: 18pt;
        color: rgb(0, 32, 96);
    }
    #editorpane div.heading2 span.zw-portion {
        font-family: Heuristica, Georgia;
        font-size: 14pt;
        color: rgb(192, 0, 0);
    }
    #editorpane div.heading3 span.zw-portion {
        font-family: Heuristica, Georgia;
        font-size: 12pt;
        color: rgb(128, 128, 128);
    }
    #editorpane span.zw-portion {
        font-family: 'Lato 2';
        font-size: 12pt;
    }
    ```

    ### Step 2: Build HTML with Inline Styles

    Instead of:

    ```html
    <!-- DON'T DO THIS — styles will be overridden -->
    <h1>Cloud Infrastructure Advisory</h1>
    <h2>Executive Summary</h2>
    <p>This report examines cloud adoption trends.</p>
    <ul>
        <li>Finding one</li>
        <li>Finding two</li>
    </ul>
    ```

    Do this:

    ```html
    <!-- DO THIS — inline styles match the template exactly -->
    <p style="font-family: Heuristica, Georgia; font-size: 18pt; color: rgb(0,32,96);">Cloud Infrastructure Advisory</p>
    <p style="font-family: Heuristica, Georgia; font-size: 14pt; color: rgb(192,0,0);">Executive Summary</p>
    <p style="font-family: 'Lato 2', Lato, sans-serif; font-size: 12pt;">This report examines cloud adoption trends.</p>
    <ul>
        <li style="font-family: 'Lato 2', Lato, sans-serif; font-size: 12pt;">Finding one</li>
        <li style="font-family: 'Lato 2', Lato, sans-serif; font-size: 12pt;">Finding two</li>
    </ul>
    ```

    Key points:
    - Use `<p>` tags for **everything** including headings — never `<h1>` through `<h6>`
    - Apply the template's exact `font-family`, `font-size`, and `color` as inline styles
    - Do **not** add `font-weight: bold` unless the template explicitly uses it
    - List items (`<li>`) also need inline styles

    ### Step 3: Pass to the Merge API

    Use the v2 Merge and Store endpoint to create a persistent Writer-native document:

    ```python
    import json
    import requests

    ACCESS_TOKEN = "your_access_token"
    TEMPLATE_ID = "your_template_id"  # The merge template document ID

    # Your styled HTML content
    styled_html = (
        '<p style="font-family: Heuristica, Georgia; font-size: 18pt; '
        'color: rgb(0,32,96);">Cloud Infrastructure Advisory</p>'
        '<p style="font-family: Heuristica, Georgia; font-size: 14pt; '
        'color: rgb(192,0,0);">Executive Summary</p>'
        '<p style="font-family: \'Lato 2\', Lato, sans-serif; font-size: 12pt;">'
        'This report examines cloud adoption trends.</p>'
    )

    # Merge data must be wrapped in {"data": [...]}
    merge_data = json.dumps({
        "data": [{"content": styled_html}]
    })

    # Output settings — use "zdoc" for native Writer documents
    output_settings = json.dumps({
        "doc_name": "My Report",
        "format": "zdoc"
    })

    response = requests.post(
        f"{BASE_URL}/writer/api/v2/documents/{TEMPLATE_ID}/merge/store",
        headers={"Authorization": f"Zoho-oauthtoken {ACCESS_TOKEN}"},
        data={
            "merge_data": merge_data,
            "output_settings": output_settings,
        },
    )

    result = response.json()
    record = result["records"][0]
    print(f"Document URL: {record['document_url']}")
    print(f"Document ID:  {record['document_id']}")
    ```

    ## Additional Gotchas Discovered

    ### 1. merge_data format

    The merge data **must** be wrapped in a `{"data": [...]}` array, even for a single record:

    ```json
    // WRONG — will return "Merge data not found" (R6001)
    {"content": "<p>Hello</p>"}

    // CORRECT
    {"data": [{"content": "<p>Hello</p>"}]}
    ```

    ### 2. Output format for editable documents

    Use `"format": "zdoc"` to create native Zoho Writer documents. Using `"format": "docx"` creates a Word file in WorkDrive that doesn't behave as a native Writer document.

    ### 3. No newlines in HTML content

    Do not include `\n` newline characters between HTML elements in the merge data. Writer renders these as literal line breaks in the document. Concatenate your HTML elements directly:

    ```python
    # WRONG — \n appears as visible line breaks
    html = "<p>Paragraph one</p>\n<p>Paragraph two</p>"

    # CORRECT
    html = "<p>Paragraph one</p><p>Paragraph two</p>"
    ```

    ### 4. OAuth scopes required

    The merge and store endpoint requires these scopes:

    ```
    ZohoWriter.documentEditor.ALL
    ZohoWriter.merge.ALL
    ZohoPC.files.ALL
    WorkDrive.files.ALL
    WorkDrive.organization.ALL
    WorkDrive.workspace.ALL
    ```

    The first two alone are not sufficient — the WorkDrive and ZohoPC scopes are also required, even for basic template and folder operations.

    ### 5. Template field type must be "richtext"

    Your merge template must have a field defined as `richtext` type to accept HTML content. You can verify fields via:

    ```
    GET /writer/api/v1/documents/{template_id}/fields
    ```

    Which returns:

    ```json
    {
        "merge": [
            {
                "id": "content",
                "type": "richtext",
                "display_name": "content",
                "category": "created"
            }
        ]
    }
    ```

    ## Helper Function: Content Builder

    Here is a reusable Python function that converts a structured content specification into correctly styled HTML for any template:

    ```python
    from html import escape

    # Define styles per template — extracted from the template's stylesheet
    TEMPLATE_STYLES = {
        "my_template": {
            "heading1": "font-family: Heuristica, Georgia; font-size: 18pt; color: rgb(0,32,96);",
            "heading2": "font-family: Heuristica, Georgia; font-size: 14pt; color: rgb(192,0,0);",
            "heading3": "font-family: Heuristica, Georgia; font-size: 12pt; color: rgb(128,128,128);",
            "paragraph": "font-family: 'Lato 2', Lato, sans-serif; font-size: 12pt;",
            "list_item": "font-family: 'Lato 2', Lato, sans-serif; font-size: 12pt;",
        },
    }

    def build_html(content_blocks, template_name=None):
        """
        Convert structured content blocks into styled HTML.

        content_blocks: list of dicts with keys:
            - type: "heading1", "heading2", "heading3", "paragraph",
                    "bullet_list", "numbered_list"
            - text: str (for headings/paragraphs)
            - items: list[str] (for lists)
        template_name: key into TEMPLATE_STYLES dict
        """
        styles = TEMPLATE_STYLES.get(template_name, {}) if template_name else {}
        parts = []

        for block in content_blocks:
            block_type = block.get("type", "paragraph")
            text = block.get("text", "")
            items = block.get("items", [])

            if block_type in ("heading1", "heading2", "heading3", "paragraph"):
                style = styles.get(block_type, "")
                attr = f' style="{style}"' if style else ""
                parts.append(f"<p{attr}>{escape(text)}</p>")

            elif block_type == "bullet_list":
                style = styles.get("list_item", "")
                attr = f' style="{style}"' if style else ""
                li = "".join(f"<li{attr}>{escape(item)}</li>" for item in items)
                parts.append(f"<ul>{li}</ul>")

            elif block_type == "numbered_list":
                style = styles.get("list_item", "")
                attr = f' style="{style}"' if style else ""
                li = "".join(f"<li{attr}>{escape(item)}</li>" for item in items)
                parts.append(f"<ol>{li}</ol>")

        return "".join(parts)  # No \n between elements!


    # Usage
    content = [
        {"type": "heading1", "text": "Cloud Infrastructure Advisory"},
        {"type": "heading2", "text": "Executive Summary"},
        {"type": "paragraph", "text": "This report examines cloud adoption."},
        {"type": "bullet_list", "items": ["Finding one", "Finding two"]},
        {"type": "heading3", "text": "Recommendations"},
        {"type": "numbered_list", "items": ["Action one", "Action two"]},
    ]

    html = build_html(content, template_name="my_template")
    ```

    ## Summary

    | What | Don't | Do |
    |------|-------|----|
    | Heading tags | `<h1>`, `<h2>`, `<h3>` | `<p style="...">` |
    | Styling | Rely on template CSS inheritance | Inline the template's exact styles |
    | Bold | Let heading tags add implicit bold | Only add `font-weight` if the template uses it |
    | merge_data | `{"field": "value"}` | `{"data": [{"field": "value"}]}` |
    | Output format | `"docx"` | `"zdoc"` for native Writer |
    | HTML joins | `"\n".join(parts)` | `"".join(parts)` |

    This approach preserves the visual identity of your Zoho Writer templates when programmatically generating documents through the Merge API.

    ---

    *Tested with Zoho Writer API v1/v2, April 2026*




    • Sticky Posts

    • [Announcement] Insert image from URL changes in Zoho Writer

      Hi Zoho Writer users! We'd like to let you know that we've changed the behavior of the Insert image from URL option in Zoho Writer for security reasons. Earlier behavior Once you inserted an image URL in a Writer document, the image would be fetched from

    • Deprecation of certain URL patterns for published Zoho Writer documents

      Hi Zoho Writer users! We'd like to let you know that we have deprecated certain URL patterns for published and embedded documents in Zoho Writer due to security reasons. If the published or embedded documents are in any of these URL patterns, then their

    • Introducing plagiarism checker in Zoho Writer

      Zia, Zoho Writer's AI-driven writing assistant, now highlights plagiarized and duplicated content in addition to offering contextual grammar and writing suggestions to help you write clearly and concisely in English. Zoho Writer's plagiarism reports Here

    • [Important announcement] Impact of Google's new email guidelines for Zoho Writer automation users

      Hi users, Google has recently announced new guidelines for sending emails to Gmail and other Google-hosted domains. These guidelines will be effective starting Feb. 1, 2024, and can impact the delivery of emails sent from Zoho Writer. Your organization

    • Transitioning from MS Word to Writer: A complete walkthrough

      Hello everyone! We understand moving to a new word processing tool can be difficult, especially if it means switching from a legacy software like MS Word. That's why we've organized an exclusive webinar where we talk you through ways to make your switch from MS Word to Writer as easy as possible. In this webinar, you'll learn: - Why Writer is a simple yet powerful alternative to MS Word. - How to locate your favorite MS Word features and functions in Writer.  - How to migrate your Word documents

    • Recent Topics

    • WhatsApp Business Message Pricing Update: Effective October 1, 2026

      Hi everyone, Starting October 1, 2026, Meta is updating how WhatsApp Business messages are charged. This guide explains the new per-message pricing model, how message categories work, and what changes for service messages specifically. How Meta charges

    • Spam Quarantine: Manage suspicious emails in Zoho Mail

      When an email is quarantined by spam processing, it need not always be blocked right away. Some emails may be marked incorrectly, or may need to be reviewed before a final decision is made. The Spam Quarantine feature in the Zoho Mail Admin Console gives

    • What is the difference between "Reply" and "Public Comment" in a ticket?

      Hey, my company is thinking about switching to Zoho Desk but we do not understand the difference between the "Reply" and the "Public Comment" feature. When should we use which? And why? What is the difference between them? Thank you for your help! Kindest

    • Comments Vs. Replies

      I'm curious as to the difference between a "Reply" and a "Comment" on a ticket. It appears that "Replies" are what's used to determine response time SLA's and there are also used to automatically re-open tickets. I'm just trying to understand the key differences so I can educate both our clientele and our back-end users on which function/feature to use to better improve the ticket lifecycle. If anyone has any insight it would be appreciated. Thanks!

    • Widget Height were destroyed

      All widget heights in the Details Canvas view are broken.

    • CRM Address Field - States with Countries in brackets

      Hi, Could you please remove the country in brackets from the Global State List, or at least allow us to edit these entries? It looks like the brackets were added during the initial data population, perhaps by someone building the list in a spreadsheet

    • What's New in Zoho Inventory | July & August 2026

      Hello users, The July and August 2026 releases bring a range of new features and improvements across the product. From the Nigeria Edition and Super Admin enhancements to Sri Lanka IRD-compliant invoicing, Loyalty Program Management, and improvements

    • Forms data export bug

      The export csv with a password has changed for the worst. It is less secure by not allowing complex passwords. Just last week and the last year (at least) I was able to use a complex, secure password. Export CSV moreover doesn't even work if I use a simple

    • Fax and email questions

      Does Zoho offer faxing capability? If so, how to do it? And, why is has my email inbox stopped in 2019? There are no more emails since then. Also if I delete all of those emails, will they delete it from my gmail account (I'm linked to a gmail email address).

    • Create a single record from multiple images with ICR

      Hello all, Zia's Intelligent Character Recognition can now create a single record from multiple images. Users can upload up to three images at once, such as an ID, a passport, and a business card, and Zia will extract the relevant information from all

    • How to present an Analytic on a CRM dashboard and filter it on loginuser id

      How to present an Analytic on a CRM dashboard and filter it on loginuser id? I want to display an Analytics pivot table (as a widget) on a CRM dashboard and have the pivot filtered on the loginuser. I want additional user-filters available, such as date,

    • CNIL - Suivi de Pixel

      Bonjour à tous, À la suite de la nouvelle recommandation de la CNIL sur les pixels de suivi dans les e-mails, savez-vous si Zoho Campaigns permet : de conditionner le suivi des ouvertures au consentement de chaque contact ; de proposer un lien permettant

    • Convert MBOX to PST File Using Free Methods

      MBOX is a mailbox format that is used by various email clients and services, such as Thunderbird, Apple Mail, Eudora, and Google Takeout. Yet, in order to be able to open your MBOX emails in Microsoft Outlook, you have to convert them from MBOX to PST

    • Live connection to DS files in Zoho Creator / ChatGPT

      As an idea, we are using ChatGPT to build with Zoho Creator (outside of Zia), which is works brilliantly to assist write deluge, provide test suggesitons etc. Currently we are uploading the DS files which are very point in time, it would be great to have

    • Setting default From address when replying to request

      At the moment, if I want to reply to a request, the From field has three options, company@zohosupport.com, support@company.zohosupport.com, and support@company.com. The first two are really internal address that should never be seen by the customer and

    • Zoho Payroll: Product Updates - Q3, FY2026

      Over the past quarter, Zoho Payroll has added several updates to make payroll easier to process, configure, and manage. The most notable improvements cover bank integrations, reimbursement support, payslip enhancements, employee exit documentation, payroll

    • Convert OLM to PST on Mac and Windows Using Free Methods

      When your Outlook for Mac data is stored in an OLM file and you want to use it with Outlook for Windows, the simplest approach to transfer your emails and other mailbox information is to convert the OLM file to a PST file. OLM is primarily associated

    • Add Payment Information (like Bank details)

      I am using the Free plan of Zoho Books. I need to add the bank details/ UPI details on the invoice. How can I do that. I have added the details in the Bank Section.

    • Placeholders for Multi-Level Discount

      I am using custom templates for Invoices and all other modules. Since i have activated multi-level discount (an early-access feature from zoho) "discount at line-item and transaction level", I need placeholders for using them in my custom templates. With

    • Running Balance

      Please add automatically Running balance in ledger view. Taking lot of time, every time to add manually

    • Accounting on the Go Series-47: Effortless GSTIN Management- Auto Populate TaxPayer Details in Zoho Books Mobile App

      Hello everyone, Welcome back! Today, we're focusing on a feature specifically designed for our Indian users in the Zoho Books-Indian edition, particularly those who deal with GST compliance regularly. We understand the importance of accurate and efficient

    • URGENT: Stalled DC Migration >72 Hours - Records Locked [Ticket #: 167813877

      The DC migration was started on 1st October at 6 pm and we were informed migration period as 48 hours but even after more than 72 hours, the migration seems still in progress. We sent two emails to check the status but no responses. We need the migration

    • Zoho Webinar - Sharing System Audio (NOT AVAILABLE)

      Hi, We are having a serious problem with Zoho Webinar. In the webinars we run, we very often share the audio from a video we are streaming directly from YouTube or other applications. Until recently we were using Zoom, but as we use other Zoho applications

    • Cash Recipt

      You can not receive cash more than 10000 from one party in a day and two lakh in a year. In statement you can't differentiate cash or bank receipt. zoho does not support this

    • Need to set workflow or journey wait time (time delay) in minutes, not hours

      Minimum wait time for both Campaigns workflows and Marketing Automation journeys is one hour. I need one or the other to be set to several minutes (fraction of the hour). I tried to solve this by entering a fraction but the wait time data type is an integer

    • Concern Regarding Stock Validation in Inventory Management

      Hi Zoho Team, We would like to highlight a concern regarding stock validation in the inventory system. As per standard inventory management practices, if the stock level is zero, the system should not allow users to create a shipment, packing slip, or

    • Change from OST to PST on Windows 10/11 Using Free Method

      There is an advantage in converting OST files to PST format if you need to access your Outlook data on a different computer, want to keep a local copy, or are trying to recover items from an old Outlook profile. The good point is that users of Windows

    • Meet PageHealth by Zoho PageSense: a free way to find out what's holding your page back

      We all know the feeling. You've spent days tweaking headlines, moving buttons, and rewriting copy, and you're still not sure why visitors aren't sticking around. Revamping your website is hard, and figuring out what's actually getting in the way is even

    • Important: Whitelist new proxy outgoing IPs for IN, SA, and UAE data centers

      Hello everyone, We're expanding the pool of proxy outgoing IP addresses for our IN, SA, and UAE data centers by introducing new IPs alongside the existing ones. This helps ensure high availability, optimal load distribution, and redundancy for outgoing

    • Zoho Flow Custom Function Issue

      I have a use case where I will be needing to post data to a wordpress site. Specifically to a custom post type with a bunch of ACF fields. I have setup trigger event correctly for Tookan and can receive data from the webhook. In order to post the data

    • How to Open .mbox file in Gmail with Attachments?

      Gmail offer users to backup INBOX folder in .mbox file format via Google Takeout Feature. Howver there is no such option to Restore Gmail MBOX. Thus I would like to suggest you to choose an alternate approach i.e. MBOX to Gmail Wizard. This utility will open .mbox file in Gmail with attachments.  Steps to open MBOX file in Gmail are; Run MBOX to Gmail Wizard Click Add File and add .mbox file. Enter your Gmail login credentials. Click Convert button. Finished! This is how you can open MBOX file in

    • Custom Validation for On Duty

      Hi Team, We would like to have custom validation support for the On Duty form in the Attendance module. We need to apply some restrictions, such as: Limit the number of On Duty requests per month. Restrict On Duty requests on selected days. Allow employees

    • Integrating FaceBook Ads into MarketingHub

      I would like to track the clicks from a FB Ad campaign into my website via marketinghub.  I cannot currently add a MH form directly to my FB page, as I receive an error telling me I need at least 2000 subscribers on FB to be allows to do that (yikes!) What is the best way to set up MH so I can track which FB are converting well?  I know I can reach the FB reports directly, but these do not track conversions from the MH forms on my website. Best regards, Joe

    • Migration from GoDaddy to Zohomail

      Hi All, I am trying to migrate all the emails from Go Daddy to zohomail account using the migration tool. i tried with imap method, its not working. when i try it with pop method, then only the emails from the go daddy account inbox ( not other folders), is getting transferred, how can i transfer all the folders in the email account from go daddy to zoho. and also the emails which are coming from go daddy are like new unread emails ( is there any where i can differentiate from read and unread emails)

    • How do I migrate from Office 365 to Zoho Mail?

      Check out Advik Email Migration Wizard, this software is specially developed to move mailboxes from Office 365 to Zoho Webmail. In addition you can migrate from Gmail, Yahoo, Rediffmail and 80+ webmail servers to ZOHO MAIL. Isn't it amazing? This is an all in one email migration solution. Steps to export emails from Office 365 to Zoho Webmail are as follows; Run Advik Email Migration Tool in your system. Select Office 365 as source and enter its login credentials. Select mailbox folders and choose

    • How to Backup Zoho to PST?

      I'm looking for a simple way to backup Zoho Mail emails to PST format. I tried the IMAP method with Outlook, but it seems slow and complicated for large mailboxes. I need a solution that can: Export Zoho emails to PST Preserve attachments and folder hierarchy

    • Shopify connector – product cost ("Cost per item") not synced, so COGS/gross margin can't be calculated

      Hi Zoho Analytics team, I use the native Shopify connector in Zoho Analytics (cloud) to build reporting dashboards for Shopify stores. As far as I can tell, the connector does not sync product cost, so there's no way to calculate Cost of Goods Sold (COGS),

    • Zoho Sprints - Q3 Updates for 2026

      Another quarter, another set of productive features. This time our focus was mainly to simplify in-app navigations and control all your work related activities within Zoho Sprints. We delivered 7 major features and 9 enhancements, which include Zoho Sprints

    • Which Zoho CRM tasks would you want an AI assistant to handle?

      I’ve started delegating my Zoho CRM work to AI – and many tasks now take me half the time. It has been so useful that we’re now working to make it available to everyone. Instead of clicking through records and tabs, I simply describe what needs to be

    • The Social Wall: August 2024

      Hi everyone, We're thrilled to bring you the latest updates, features, and improvements to help you get the most out of Zoho Social. Let's see what was new for us at Social in August. Post documents on LinkedIn You can now reach a lot more people and

    • Next Page