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

    • Automating CRM backup storage?

      Hi there, We've recently set up automatic backups for our Zoho CRM account. We were hoping that the backup functionality would not require any manual work on our end, but it seems that we are always required to download the backups ourselves, store them,

    • Zoho CRM Kiosk question – Passing Screen Fields to a Function

      I am building a Kiosk in Zoho CRM to create new Supplier (Vendors) records. Current setup: Screen 1 contains user input fields: Supplier Name (Vendor_Name) First Name (First_Name) I created a Deluge function: createSupplier(vendor_name, first_name) The

    • Introducing Spotlight Forms

      Hey form builders! If someone opens your form, sees the wall of fields ahead, and quietly closes the tab. It may not be because the questions were hard. It could be because the experience felt like too much. Which is why we have now introduced a new form

    • Client Script Button in Related List become invalid

      Hi, I am the admin of our organization. And I setup a client script button in related list to raise payment refund request While this button become non selectable recently. I believe there is something wrong from zoho as this button had run for a year.

    • BUG and HANGUP - Add Row with Fields DOUBLES the amount of rows instead of Adding Just 1 Row

      As it says in the title, there is a bug with forms generated with Zoho Writer where the Add Row With Fields ends up DOUBLING the amount of rows instead of Adding just 1 row.

    • Delivery Note without services

      Hi all, It there a possibility to create a delivery note from an invoice without the listed services "idem type: service"? Thank you in advance, Michel

    • Forms cannot be accessed.

      https://forms.zoho.com/ is not available, please help to fix

    • Digest Mai - Un résumé de ce qui s'est passé le mois dernier sur Community

      Chers utilisateurs, Un nouveau mois se termine au sein de la communauté Zoho France. Découvrons ensemble un résumé des activités du mois de mai. Quatre ans après son lancement, Zoho Marketing Plus continue d’évoluer avec une ambition claire : offrir aux

    • Ability to run report over 180 days

      Is there a reason Zoho limits the ability to run reports for records older than 180 days? In my view, the only reason I can think of is that it forces us to pay for Advanced Analytics (which I do).

    • [URGENT] Cannot access Functions tab in CRM

      Navigating to /settings/functions/myFunctions gives this error message: "Sorry, something went wrong. Please try again later." I raised this issue with Zoho Support on Monday (3 days ago) but have not heard back. I'm sure it's clear how important it is

    • Important changes to note for Zoho Sign users in Saudi Arabia

      Dear Zoho Sign users, If your Zoho Sign account is hosted in our Saudi Arabia data centre, here's an important update on digital signature certificates in the Kingdom of Saudi Arabia. What's changing Going forward, the "Sign via Zoho Sign" option will

    • Cloning a View

      When I clone a View, it doesn't make a copy; it only creates a new copy with the same default fields as if I were creating a new view. What is the purpose of cloning if it doesn't bring in the same fields? Thanks Rudy

    • Zoho Desk MCP doesn't expose all functions

      Hello, I'd like to be able to draft (rather than send) ticket replies using Claude Cowork. However, the Zoho Desk MCP doesn't currently offer that, despite it being available in the API (https://desk.zoho.com/DeskAPIDocument#Threads#Threads_DraftEmailReply).

    • Number of Reopn

      Hi Zoho, Is there any appropriate API call for This URL "http://support.zoho.com/api/v1/dashboards/reopenedTickets?...." what I thought is the resulting output of this call has data for number of reopen... "https://desk.zoho.com/api/v1/tickets/" + Ticket_ID

    • Can I use merge tags with a conditional clause?

      Similar to Mailchimp's "IF / ELSE / ENDIF" functionality, I want to be able to display a sentence with a personalised field only if that merge tag is not empty for the given record. Is this possible on Zoho Campaigns? See http://kb.mailchimp.com/article/how-do-conditional-smart-merge-tags-work for how it works on Mailchimp. Thanks Phil

    • Question - why no way to input a 'tool description' and 'tree of 'tools'

      Every business is different, with different business processes. To be truly useful Zoho MCP needs to have user editable tool descriptions (or ruleset) and a 'tool tree' so that the LLM is context aware when being used. For example, the tool description

    • Personalize your booking pages with Custom CSS

      Greetings from the Zoho Bookings team! We’re introducing Custom CSS for Zoho Bookings, designed to give you complete control over the look and feel of your booking pages. With this new feature, you can upload your own CSS file to customize colors, fonts,

    • CRM API v9?

      v8 has been around for a while. any plans / estimates for v9?

    • Calendar report with order options and more quick view templates

      I think many of us regularly work with calendar-style reports. It would be great to be able to customize the quick view with new templates and have options to sort the entries for each day of the calendar by different criteria. I think this is an interesting

    • Kaizen #125 Manipulating Multi-Select Lookup fields (MxN) using Zoho CRM APIs

      Hello everyone! Welcome back to another week of Kaizen. In last week's post in the Kaizen series, we discussed how subforms work in Zoho CRM and how to manipulate subform data using Zoho CRM APIs. In this post, we will discuss how to manipulate a multi-select

    • Zoho Books and TRAINING SALES receipt label for eTims?

      Hi, Can Zoho Books implement TRAINING SALES receipts and push them to eTims for test? In other words how can we send to Zoho or even create in Zoho training mode invoices and TEST the workflow POS>Zoho Books>eTims and back without actually registering

    • Workflow Assistance in Zoho CRM

      Our client's sales team visits customers on-site and currently fills a physical paper form to capture customer details, and then separately re-enters the same data into Zoho CRM via the mobile app — resulting in double data entry. We want the salesperson

    • How do I post a new question in Zoho Community forums?

      Hi everyone, I’m new to the Zoho Community and I’m trying to figure out how to properly create and publish a new topic in the forum. When I visit the community page, I can’t clearly find the option like “Add Topic” or “Post Question.” Could someone guide

    • Any Zoho Books users in the Kenyan Hospitality industry? How to set service items for eTims?

      Hello, We are opening a coffee shop in Kenya and would like to know if there are any Zoho books users in hospitality service industry in Kenya? We would love to know: 1. how do you cope with the absence of the mandatory Tourism Levy 2% tax option? 2.

    • Cloning Item With Images Or The Option With Images

      Hello, when I clone an item, I expect the images to carry over to the cloned item, however this is not the case in Inventory. Please make it possible for the images to get cloned or at least can we get a pop up asking if we want to clone the images as

    • Zoho Books | Product updates | May 2026

      Hello users, We're back with the latest updates and enhancements we've rolled out in Zoho Books. From sales tax automation to scanning receipts for free, explore the updates designed to upgrade your bookkeeping experience. Sales Tax Automation [US & Canada

    • Zoho Books | Product updates | June 2026

      Hello users, Welcome to this month's roundup of what's new in Zoho Books! We have an exciting line-up this time. The highlight is the launch of the all-new France Edition with full ISCA compliance. We're also introducing features such as Layout Rules

    • [Product Update] Locations module migration in Zoho Books integration with Zoho Analytics

      Dear Customers, As Zoho Books are starting to support an advance version of the Branches/Warehouses module called the Locations module, users who choose to migrate to the Locations module in Zoho Books will also be migrated in Zoho Analytics-Zoho Books

    • Does Zoho Learn integrate with Zoho Connect,People,Workdrive,Project,Desk?

      Can we propose Zoho LEarn as a centralised Knowledge Portal tool that can get synched with the other Zoho products and serve as a central Knowledge repository?

    • Request to Update Billing Information and Payment Method

      Hello, I’m using Zoho and I would like to update the billing information and change the payment card to our company card. Could you please let me know how I can do this? Thank you in advance for your help.

    • Zoho Analytics "Esc" key problem

      I frequently use the Escape (Esc) key while building dashboards, reports, and writing SQL queries. Since the recent updates to Zoho Analytics, the Esc key no longer behaves as expected. When writing SQL queries, pressing Esc to dismiss a suggestion now

    • Zoho Analytics Filter Bug

      I encountered a bug where typing the letter "A" in the drop-down filter of a table or query table causes the drop-down to close unexpectedly. For example, when typing "Today", the drop-down list closes as soon as "a" is entered. I tested this on another

    • Using Email Triggers on Zoho Flow

      Hello, I'm sending the email to create the variables as this article says: https://help.zoho.com/portal/en/kb/flow/user-guide/create-a-flow/articles/email-trigger#How_email_trigger_works But the collection of the variables only seems to work when the

    • How to customize the "Placeholder Text" separately from the "Field Label" on the Booking Form?

      Hi, I am currently customizing the Booking Form for one of my Workspaces in Zoho Bookings, and I need some help adjusting a custom text field. Right now, when I create a custom text field, the gray "placeholder text" inside the text box automatically

    • What's New in Zoho Inventory | April & May 2026

      Hello users, We're excited to roll out the latest Zoho Inventory updates for April and May 2026. These enhancements are designed to make your daily operations smoother and more efficient, from advanced inventory management and flexible pricing to automated

    • Why don't Zia agents support file uploads?

      I am trying to build a Zia Agent that allows uploading of a PDF file and uses the GLM5 model to process it and extract information. But agents.zoho.com has no way to enable file uploads on the agent. Additionally, GLM5 based agents keep outputting their

    • Pasting Images in Zoho Desk ignores cursor location

      My team has reported an issue which started recently where when we paste an image into a new or existing reply or comment, the pasted image seems to ignore the current cursor location instead paste itself at the last character present in the reply/comment,

    • 'Pinned' notes feature of a pipeline record

      Hi team, Could you please implement a feature which will allow users to pin different notes so that they will appear at the very top of the notes tab in a pipeline record. Sometimes we have a wide range of notes on a record which means more important

    • Dynamically prefill ticket fields

      Hello, I am using Zoho Desk to collect tickets of our clients about orders they placed on our website. I would like to be able to prefill two tickets fields dynamically, in this case a readonly field for the order id, and a hidden field for the seller

    • Announcing new features in Trident for Mac (1.37.0)

      Hello everyone! We’re excited to introduce the latest updates to Trident, which are designed to take workplace communication to the next level. Let’s dive into the details. Import EML archives directly into Trident. You can now import EML archives into

    • Next Page