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*





      Zoho Campaigns Resources


        • Desk Community Learning Series


        • Digest


        • Functions


        • Meetups


        • Kbase


        • Resources


        • Glossary


        • Desk Marketplace


        • MVP Corner


        • Word of the Day


        • Ask the Experts


          • 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

          Zoho CRM Plus Resources

            Zoho Books Resources


              Zoho Subscriptions Resources

                Zoho Projects Resources


                  Zoho Sprints Resources


                    Zoho Orchestly Resources


                      Zoho Creator Resources


                        Zoho WorkDrive Resources



                          Zoho CRM Resources

                          • CRM Community Learning Series

                            CRM Community Learning Series


                          • Tips

                            Tips

                          • Functions

                            Functions

                          • Meetups

                            Meetups

                          • Kbase

                            Kbase

                          • Resources

                            Resources

                          • Digest

                            Digest

                          • CRM Marketplace

                            CRM Marketplace

                          • MVP Corner

                            MVP Corner




                            Zoho Writer Writer

                            Get Started. Write Away!

                            Writer is a powerful online word processor, designed for collaborative work.

                              Zoho CRM コンテンツ






                                ご検討中の方

                                  • Recent Topics

                                  • Invalid value passed for line_item_category

                                    duplicating a previous used invoice and trying to save it (new invoice number / po number used) I keep encountering this error when trying to save the invoice Invalid value passed for line_item_category

                                  • What is the different between Zoho invoice and Zoho book

                                    Hi, both product do invoice and Zoho book having all function / feature Zoho invoice, please explain more, thanks

                                  • Mastering Zia Match Scores | Let's Talk Recruit

                                    Feeling overwhelmed by hundreds of resumes for every job? You’re not alone! Welcome back to Let’s Talk Recruit, where we break down Zoho Recruit’s features and hiring best practices into simple, actionable insights for recruiters. Imagine having an assistant

                                  • Insert Template not inserting

                                    I have been using the "Insert Template" feature for years and I use it every single working day. Yesterday it was working fine. Today, on two different browsers (Chrome and Edge), I can select "Insert Template", select the template I want to insert, but

                                  • Option for - CSV Export from Pipeline Deals by Stage (Including Products, Companies, and Contacts)

                                    I would like to know when we will be able to export a simple CSV file from pipeline deals, with the option to select a specific stage within the pipeline. This export should include data for products, companies, and contacts, all in a single view. For

                                  • What is the difference between workflows, journeys, and blueprints?

                                    I semi-understand what they are individually but they all say they can be used to automate processes in your CRM. What makes these three different? What are the benefits and cons of using each?

                                  • Free webinar! Simplify hiring and HR workflows with Zoho Sign for Zoho People & Zoho Recruit

                                    Hello! Managing recruitment, onboarding, and employee paperwork doesn’t have to be complex or time-consuming. Discover how Zoho Sign, integrated with Zoho People and Zoho Recruit, helps you digitize and streamline your document workflows from hire to

                                  • Multiple Blueprints on different fields at the same time.

                                    It looks only 1 Blueprint can run at the same time, it makes sense for many Blueprints on the same field (Eg. Stage). But what about multiple Blueprints on "different" fields? the multiple options must be available. (Eg. Stage, Documents Status, Contract

                                  • Edit 'my' Notes only

                                    The permissions around Notes should be more granular, and allow to user to be able to edit the notes he created only. The edit Notes permission is useful as it allows the user to correct any mistakes or add information as needed. However, with this same

                                  • Need to make a specific canvas my default view for contacts

                                    Need to make a specific canvas my default view for contacts How do I do it?

                                  • Add Zia matching jobs on the main screen of candidates module

                                    It will be good if it is added in the main screen as a column so that we can quickly hover over and see if they match for any job openings. That will save from two additional clicks

                                  • Domain Disclaimer: A standardized footer for your entire organization

                                    Every email sent from an organization represents its identity externally. Most teams require consistent line of text at the bottom of outgoing messages. It can be a confidentiality notice, a legal statement, a compliance requirement, or a uniform sign-off.

                                  • SalesIQ Email Delivery Issues to Microsoft

                                    Is anyone else having delivery issues to Hotmail, Outlook, and Live inboxes when sending transcripts and replies via email from SalesIQ? We’ve detected that emails sent from SalesIQ to these accounts aren't arriving—they don’t even bounce back; they simply

                                  • Zia flags the deal as at risk - but leaves my customers figuring out the rest themselves

                                    I implement Zoho for many businesses. Team sizes vary, some clients have 3 reps, some have 40. But I keep hearing the same complaint across all of them and I figured it's worth raising here. Zia's deal scoring has genuinely improved over the past year.

                                  • How do we change system field names?

                                    I found some very old discussions, but looking for more recent. Very confused on mapping the addresses correctly, due to different names for some reason between. for example: leads: city, state, zip etc... as normal contacts: Mailing adddress & Other

                                  • Remove "Subject" as a required field on Quotes

                                    Currently, when you create a quote in CRM, the field "Subject" is mandatory. The properties of a system defined field cannot be edited which means we cannot de-select the mandatory requirement. A 'subject' on a quote is a little vague and not something

                                  • Adding Multiple Products (Package) to a Quote

                                    I've searched the forums and found several people asking this question, but never found an answer. Is ti possible to add multiple products to a quote at once, like a package deal? This seems like a very basic function of a CRM that does quotes but I can't

                                  • Unattended - Silent

                                    How can I hide the tray icon / pop up window during unattended remote access for silent unattended remote access?

                                  • What is the Potential field for in expense submissions?

                                    I'm trying out Zoho Expense in Zoho Project so I can record project expenses which aren't time related. On the expense form there is an option called Potential but I don't understand what this is for. When I click the dropdown it just shows the name of

                                  • 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,

                                  • how do i add more than one google my business location?

                                    they are connected to one account, but while connecting social channels it makes me pick one location. I have 3 and growing.

                                  • Control Fields on Mobile App

                                    On the mobile app, how do we control which fields appear on the screen for records that have a related list? In the example below I want the Inspection Stage and Inspection Type fields to appear, not the record owner (Dev Admin). I changed the Inspections

                                  • Unable to switch existing AWS RDS connection to DataBridge after moving RDS behind VPN

                                    Hi everyone, I’m facing a problem with an existing Zoho Analytics setup and would like to know the best migration path. Originally, my Zoho Analytics connection to AWS MySQL RDS was configured using direct public access to the RDS endpoint. Everything

                                  • Hotmail

                                    I am sending an email to a hotmail, and this guy does not receive the email, either in his SPAM nor inbox. Can you help me? thanks!

                                  • No Ability to Rename Record Template PDFs in SendMail Task

                                    As highlighted previously in this post, we still have to deal with the limitation of not being able to rename a record template when sent as a PDF using the SendMail Task. This creates unnecessary complexity for what should be a simple operation, and

                                  • Updating Sales orders on hold

                                    Surely updating irrelevant fields such as shipping date should be allowed when sales orders are awaiting back orders? Maybe the PO is going to be late arriving so we have to change the shipment date of the Sales order ! Not even allowed through the api - {"code":36014,"message":"Sales orders that have been shipped or on hold cannot be updated."}

                                  • How do I change the Subject header when I reply please, it contains Re which I want to remove.

                                    Hi Zohodesk, When a customer logs a call we have amended the Acknowledge on new Ticket template so the subject header has "Ticket Id" at the start of it.  When we reply the customer gets Re: and then the Id and I can't see a template for this? Can you

                                  • Zia Agent built in ChatKit UI does not render markdown

                                    Hi, You have a major shortcoming in the Zia Agent UI. The test UI that is embedded in agents.zoho.com allows you to test the agent has full support for rendering markdown, but your ChatKit UI does not have support for rendering markdown. If I embed it

                                  • Can't add my domain to Zoho zeptomail because of error code DE_150

                                    Hello there, I'm trying to add my domain to ZeptoMail but it's rejected I checked the network tab and I'm getting { "error": { "code": "TM_3601", "details": [ { "code": "DE_150", "message": "Antispam validation failed for your domain in Accounts." } ],

                                  • Automated entries past the current month in a calendar report

                                    Hi all, I have an automation problem. I have a form which on successfull entry adds either 5 or 10 more of these entries with a slight change so our customers can see it throug a calendar report on the webiste. The entry put in manually shows up perfectly

                                  • [Bug] WebAuthn passkey registration blocked on rpIds with TLDs longer than 6 characters (.accountant, .technology, etc.) — isValidDomain regex too strict

                                    Hi, Filing on behalf of an enterprise customer where Zoho Vault is deployed across the company. The Chrome extension blocks WebAuthn passkey registration on legitimate sites whose Relying Party ID (rpId) has a TLD longer than 6 letters. This affects every

                                  • Get Files Associated to Data Template via API

                                    I have a data template with multiple files associated to it, and trying to write a Deluge script that will fetch files associated with this data template. I created the script below based on the WorkDrive API documentation, one request uses the data templates

                                  • ZOHO CRM User management or role

                                    I need guidance regarding Zoho CRM licensing and user management. I want to purchase one Zoho CRM license and create multiple team users under the same account with the following hierarchy: Super Admin User Manager User Executive Users (with limited access)

                                  • Tip #72 - Exploring Technician Console: Setup Unattended Access - 'Insider Insights'

                                    Hello Zoho Assist Community! You joined a live session, diagnosed the issue, and got the user back on track. Fix delivered, user happy, session closed. But you know this machine. It needs a follow-up. A cleanup, a patch, maybe a deeper maintenance run.

                                  • #1 New to Zoho Invoice? Do this First!

                                    "Zoho Invoice has made our company's tax invoices look more elegant and professional. It is effortless to raise an invoice and track payments with it", says Arunkumar Balakrishnan, Director GA Technologies. Generating professional invoices usually begins

                                  • Automation Series #5: Supervisor Rule vs Schedule in Zoho Desk

                                    Supervisor Rules vs Schedules: Choosing the right time-based automation This post is part of the "Desk Automation Series," Chapter 1. Through this series, we will help you choose the right automation type in Zoho Desk by comparing commonly confused automations

                                  • Error when changing user permission from read only to user.

                                    Hi there, Ive tried to change one of my users to be able to edit, however i kept getting the error user license exceed.

                                  • Need Help Preventing Overselling in Zoho Inventory

                                    Hi fellow Zoho Inventory users, I'm reaching out for advice on managing inventory control in our growing business. We've recently encountered situations where sales orders get confirmed despite insufficient stock, creating operational challenges. Our

                                  • Conditional Layouts On Multi Select Field

                                    How we can use Conditional Layouts On Multi Select Field field? Please help.

                                  • Smart Feature Compatibility Indicators for CRM Field

                                    Zoho CRM offers a wide range of field types and advanced customization options. However, several field types have feature-specific limitations that are currently documented only in help articles. For example, while configuring a Rich Text field, admins

                                  • Next Page