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

    • Zoho Social API for generating draft posts from a third-party app ?

      Hello everyone, I hope you are all well. I have a question regarding Zoho Social. I am developing an application that generates social media posts, and I would like to be able to incorporate a feature that allows saving these posts as drafts in Zoho Social.

    • How to list WorkDrive folder contents using API

      I'm trying to read folder contents using a Deluge script. The code below returns {"errors":[{"id":"F6016","title":"URL Rule is not configured"}]}". I've tried using the search API and seen similar errors. I have proved that the connection works by creating

    • Best practice to handle 50+ invokeurl calls in a loop without hitting the 30-second timeout?

      Hi everyone, I am working on a custom Deluge function where I have a Map containing around 50+ key-value pairs. I need to iterate through this Map using a for each loop and make a GET API call (invokeurl) for each item. The Problem: Because of the 50+

    • filter on sheets mobile (iOS, iPadOS) does not work

      re-posting this as a question because reporting as a problem netted zero responses... I have this issue on every spreadsheet, whether imported or created natively in Zoho Sheets. I can use on desktop without issue: but on iOS the filter dropdowns are

    • 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

    • Zoho Books' 2025 Wrapped

      Before we turn the page to a new year, it’s time to revisit the updates that made financial management simpler and more intuitive. This annual roundup brings together the most impactful features and enhancements we delivered in 2025, offering a clear

    • Speed (again!)

      Same old story again: impossible to work at this "speed". Category NOTES!

    • 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

    • sending email with another account

      Hello there, i write there for an our costumer request. They want to send email from CRM with a different email (confirmed and added to zoho profile). For example they use account@zilium.com but with this account they want to send (not only with email

    • All new Address Field in Zoho CRM: maintain structured and accurate address inputs

      Availability Update: 29 September 2025: It's currently available for all new sign-ups and for existing Zoho CRM orgs which are in the Professional edition exclusively for IN DC users. 2 March 2026: Available to users in all DCs except US and EU DC. 24

    • Comments aren't visible in shared spreadsheet

      I would like to send a spreadsheet to people who can use it to help solve a problem as a one off use unique to them. They will have to enter data in the sheet. I have comments attached to some of the cells to explain the purpose of the data being collected.

    • Custom button for list page

      Why is my 'List Page - Bulk Action Menu' button in the Packages module not autopopulating the List argument with selected record IDs?

    • Ask the Experts - Live Q&A webinar

      Hello Community, We’re excited to host our very first Ask the Experts session! Join us on 7 April 2026 from 11 a.m. to 12 p.m. (IST) for this live webinar Q&A session, where you will have an opportunity to connect directly with our product experts, gain

    • Designing Multi-Step Workflow System in Zoho Creator + Deluge (Startup Build – Exploring Advanced Architecture + Partnerships)

      Hi everyone, I’m currently building a Zoho-based system as part of an early-stage startup, and I’m looking to connect with others who have experience designing more advanced workflows in Creator + Deluge. This started as a standard application, but it’s

    • Bin Tracking with eBay integration

      When trying to setup bin tracking on items that are linked to eBay listings using the built-in Zoho eBay integration, I keep getting this error: "Storage Tracking cannot be enabled for items that are manually fulfiled or for serial/batch items tracked

    • Removing To or CC Addresses from Desk Ticket

      I was hoping i could find a way to remove unnecessary email addresses from tickets submitted via email. For example, a customer may email the support address AND others who are in the helpdesk notification group, in either the TO or CC address. This results

    • Update to CRM Custom Buttons: Collect Users' Location

      Hello everyone! Buttons in Zoho CRM allow you to extend the default CRM capabilities for your bespoke business needs. It provides the flexibility to connect to any third-party application to perform necessary actions. Wouldn't it be better, if those buttons

    • Is it possible to make tags "required"

      We would like to be able to make the tag field a requirement for agents before they can close a ticket. This would help with monthly reporting, where a lot of tickets end up with no tag, causing manual work to go back and add the correct tag for each

    • Prevent Automatic Milestone Inheritance for Newly Created Task Lists

      Hello Zoho Projects Team, We hope you are doing well. We would like to request an enhancement regarding how new task lists inherit Milestone association in Zoho Projects. Current Behavior: At the moment, when a new task list is created below an existing

    • I would like to know wich person viewed the file

      I have a franchise and my Operative Manual is in WorkdriveI, the user can´t download but despite I know How many views the file had, I would like to know wich person viewed the file Is it possible? thank you

    • Can I write a check in Zoho Books with no associated bill?

      This currently does not seem possible, and I have a client that desperately needs this function if I am able to convert them with Quickbooks. Thank you in advance for your reply. 

    • Cloning Module Customizations in Zoho FSM

      Hello Latha, I have two Zoho FSM accounts, each in a different data center. I would like to know if it is possible to clone the module customizations I have already completed in one account to my new account in the UAE from the backend. In other words,

    • Ordering of Teams

      Hi there, Currently, we cannot order Teams in Zoho Desk. Teams are ordered as they were created. It would be really helpful if we could customise the order of Teams. For example: We have the following Teams: Shipping Customer Service Sales Compliance

    • Estimate Module - Contact Field.

      Hello Latha and Team, Is it possible to make the Contact field optional in the Estimate module? Best regards, Chethiya.

    • Item with name in different languate

      Hello, is there a way to have an item with its name in different languages? For example: I sell an item in different markets and I'd like to have a Proposal and the Invoice with the Item Name in a specific language. Rino Bertolotto Zoho Specialist, STESA srl

    • How to keep track of bags, cans, drums of inventory?

      We buy and sell products that are packaged in bags 🛍️, cans🥫, drums🛢️, etc. with batch numbers. When we get a shipment of one of the products, how do we track we received (say) 10 cans each of 5L of a product and maybe we received 10 cans of another

    • This version of app doesn't support this notecard type Error

      So this problem is happening for any notes created within the last week, as well as any note recently edited on Android. I can open them on my phone fine, but they don't open on the website version. They DO work on the desktop app version. It's just web

    • PDF's Give Unsupported Type Error Message

      Many of the pdf files I add to Notebook work fine but in some cases when I try to open them on the Android App I get a message saying "Unsupported Type. Psst! You are using an older version of the app which does not support this note format. Please update

    • Cliq iOS can't see shared screen

      Hello, I had this morning a video call with a colleague. She is using Cliq Desktop MacOS and wanted to share her screen with me. I'm on iPad. I noticed, while she shared her screen, I could only see her video, but not the shared screen... Does Cliq iOS is able to display shared screen, or is it somewhere else to be found ? Regards

    • I am not able to check in and checkout in zoho people even location access allowed

      This issue i am facing in mackbook air m1, I allowed location in chrome browser and i also tried in safari but getting similar issue. Please have a look ASAP.

    • Is multiple invoice e-mailing possible?

      I wonder if following is possible: When you are in the invoice view, assume you have five invoices to five different customers that are pending (you have just created them, but not sent them away yet by email.) To the left of every invoice in the overview

    • Multiple packages in one shipment

      Guys we have been asking for this for years. we want to be able to ship multiple packages for one customer in the same shipment, so as to avoid entering shipping info repeatedly, and avoid customer getting multiple tracking emails. When does this arise?

    • I can't add a new customer in Zoho invoice? Anyone had this issue before?

      Ive been using Zoho invoice for over 6 years. Today I wanted to add a new customer to send an invoice to but it doesn't save when I try to access it from the pulldown menu when you go to send a new invoice.

    • set up an opportunity progress bar in canva

      Hi, set up an opportunity progress bar in canva I need help to set to reproduce the progress bar or equivalent of the opportunity steps in canva as in standard view (see capture ) Thank you in advance Amadou

    • Which Tool Is Best to Import MSG Files to HostGator?

      The best tool to import MSG files to HostGator is the MacGater Mac MSG Converter. This professional utility is specifically designed to simplify the migration of Outlook MSG files into web-based email services, including HostGator. It supports direct

    • Recurring event sync via Microsoft 365 Meetings

      I believe syncing Recurring through the Microsoft 365 Meetings integration is already in the works but I couldn't find a reference in the community to track the progress of this work.

    • What's New in Zoho Invoice | April - June 2025

      Hello everyone! We're excited to share the latest feature updates and enhancements we've made to Zoho Invoice from April to June 2025. In this, you will learn more about the following features: New Integrations via Zoho Marketplace Add Images to Email

    • Client Script | Update - Client Script Support For Custom Buttons

      Hello everyone! We are excited to announce one of the most requested features - Client Script support for Custom Buttons. This enhancement lets you run custom logic on button actions, giving you greater flexibility and control over your user interactions.

    • import customers

      Is there a way to bulk import customers? I'm moving from Acuity and would rather not have to enter everyone manually.

    • What's New in Zoho POS - February 2026

      Hello everyone, Welcome to Zoho POS’s monthly updates, where we share our latest feature updates, enhancements, events, and more. Let’s take a look at how February went. Purchase and sell items on different units We have introduced a unit conversion functionality

    • Next Page