Zendesk Templating API v1-v3 EOL: The v4 Upgrade Guide

Zendesk removes help center Templating API v1, v2 and v3 on July 31, 2027. On that date, every remaining legacy theme is automatically upgraded to v4 — whether or not anyone on your team has looked at it.

Read that again, because it is the part most teams get wrong. This is not a shutdown. Your help center does not go dark, your articles are not deleted, and your URLs do not change. What you lose is control over when your theme changes, and therefore over when it breaks. If your custom theme depends on a Curlybars helper that no longer exists in v4, the breakage lands on Zendesk's schedule, on a Saturday in July, in front of customers.

The date that actually constrains your planning is earlier and quieter: March 1, 2027, when Zendesk blocks the import of v1, v2 and v3 themes for all accounts. After that, you cannot re-import your legacy theme. Your rollback option disappears five months before the forced upgrade arrives.

This guide covers the full timeline including a documented date discrepancy in Zendesk's own materials, the real breaking changes at each version step, why Marketplace theme customers have a vendor dependency they need to chase now, and how to test a v4 upgrade safely while you still have a way back.

The July 31, 2027 Forced Upgrade: Every Date That Matters

Here is the timeline from Zendesk's announcement, Announcing the removal of help center templating APIs v1, v2, and v3:

Date	Event
September 14, 2026	Import of v1, v2 and v3 themes blocked for all new Zendesk accounts
November 25, 2026	ZCLI upgrade tool launches to assist developers migrating custom-coded themes
March 1, 2027	In-product GUI upgrade tool launches; importing v1, v2 and v3 themes completely blocked for all accounts
July 31, 2027	All remaining legacy themes forcefully upgraded to v4; v1, v2 and v3 completely removed

Four dates, and they are not equally important. September 14, 2026 has already passed and only affects accounts created after it. November 25, 2026 is a tooling date, not a deadline. July 31, 2027 is the date everyone will put in the calendar.

March 1, 2027 is the one that should govern your project plan.

The support announcement is also the only source for the two tooling dates, so treat "a tool will exist by then" as a Zendesk commitment rather than a shipped fact. Building your upgrade plan around a tool that has not launched yet is how teams end up doing the work manually in June 2027 anyway.

Why March 1, 2027 Is Your Real Deadline

Blocking imports sounds like an administrative detail. It is the most operationally significant item on the list.

Upgrading a help center theme is not an in-place edit you can undo. The safe pattern — the one every experienced Zendesk developer uses — is to keep a ZIP of the working legacy theme and re-import it if the new one misbehaves in production. That pattern stops working on March 1, 2027.

After that date, if you publish a v4 theme and discover that ticket submission is broken for unauthenticated users, you cannot roll back to the v3 theme. It will not import. Your options narrow to forward-fixing under pressure or swapping to a stock Copenhagen theme and losing your branding until someone fixes the custom one.

Plan the upgrade to be finished, tested and published before March 1, 2027 — not before July 31.

Why Is Zendesk Removing Three Templating Versions at Once?

Zendesk's stated reason is maintenance burden and security posture. The announcement says newer API versions are hardened against modern web threats and address security and accessibility issues, and that organisations staying on legacy versions lose access to new features and pick up compliance gaps.

That framing is more honest than most deprecation notices, and the version history supports it. Each version bump did real structural work:

• v1 to v2 removed the bundled front-end libraries — jQuery, moment.js, normalize.css — and a pile of helpers that rendered fixed, uncustomisable markup. It also moved script.js to the end of the page body for performance.
• v2 to v3 was largely an accessibility and editor release: breadcrumb markup was restructured for accessibility across all pages, the community post topic selector became a native HTML <select>, and the rich text editor moved to CKEditor with mobile support.
• v3 to v4 removed the last of the black-box form rendering. The {{request_form}} helper, which emitted a fixed HTML template with limited customisation scope, is gone in favour of a data object your theme renders itself.

The pattern across all three is the same: Zendesk is getting out of the business of rendering opaque HTML inside your theme, and handing you data plus a reference implementation instead. That is the right long-term architecture. It also means every theme built against the old black boxes needs real work, not a find-and-replace.

There is a second, unstated reason: three legacy versions means three rendering paths to keep working against every new Zendesk feature. Removing them is how Zendesk stops paying that tax. This is the same logic behind the Zendesk bot builder and AI agents – Essential end of life, and it is a visible pattern across the vendor landscape right now — we track the wider picture in our 2026 software end-of-life calendar.

A Forced Upgrade Is Worse Than a Shutdown

A shutdown is loud. An API returns 410, your monitoring fires, someone gets paged, and the failure is unambiguous.

A forced theme upgrade is quiet. On July 31, 2027, your help center keeps serving pages. Search still works. Articles still render. But a category page might now show empty section listings because the articles property your template loops over no longer exists on sections. The New Request page might render an empty div where the ticket form used to be. A "was this helpful" widget might stop voting because {{vote}} now renders buttons instead of anchor tags and your CSS selector targets a.

None of that throws a 500. None of it triggers an alert. It just degrades, silently, and you find out when a customer support manager notices ticket volume dropped by a third because nobody could submit a ticket.

The Failure Modes Are Asymmetric

Consider what each stakeholder loses:

Theme type	What the forced upgrade does	Who fixes it
Stock Copenhagen, unmodified	Nothing meaningful — already v4-compatible	Nobody
Copenhagen with CSS tweaks only	Mostly survives; selector-based styling may drift	Your front-end developer
Custom theme, heavy Curlybars use	Silent rendering regressions on New Request, home and category pages	Your front-end developer, urgently
Marketplace theme	Depends entirely on whether the author shipped a v4 build	The theme vendor, or nobody
Custom theme, original developer gone	Nobody knows what the template does	Whoever is on call

The last two rows are where the real risk sits, and neither is solved by engineering effort alone.

Treat this as a change-management problem with an engineering component, not the reverse.

What Actually Breaks Between Templating Versions

The upgrade path is cumulative. A v1 theme has to absorb the v1-to-v2, v2-to-v3 and v3-to-v4 changes. Zendesk publishes a per-version upgrade guide for each step; the specifics below come from those guides.

Upgrading from v1: The Biggest Jump

If you are still on v1, this is the step that will consume most of your budget. Helpers removed outright:

Removed helper	Replacement
{{logo_url}}	{{settings.logo}}
{{chat}}	None — removed
{{trending_questions_list}}	None — removed
{{chat_about_my_ticket}}	None — removed
{{category_tree_with_article}}	Rebuild using the category object
{{section_tree_with_article}}	Rebuild using the section object
{{article_results}} / {{post_results}}	Unified results collection
{{user_info}}	{{user_avatar}}, {{user_name}}, {{my_profile}}, {{change_password}}
{{unsubscribe}}	{{subscribe}}, which now toggles

Object properties also changed: {{section.internal}} was deprecated with no replacement, and {{filter_by}} on the user profiles page becomes {{current_filter.identifier}}.

The part that catches teams by surprise is the library removal. From v2 onward, Zendesk no longer bundles jQuery, moment.js or normalize.css, and the entypo icon font was migrated to inline SVGs. Dropdown behaviour that Zendesk used to inject is now implemented in theme files. If your script.js opens with $(document).ready(...), every line after it stops running the moment you bump to v2 — and you get no error in the Zendesk UI, just a dead page.

Behaviour changes in the same step:

• {{request_form}} shows "(optional)" on optional fields instead of marking required fields with *
• {{subscribe}} no longer refreshes the page; it is a toggle button
• {{pagination}} no longer emits page numbers, in preparation for cursor-based pagination
• {{asset}} no longer supports the cdn="legacy" attribute
• {{vote}} renders buttons instead of anchor tags, and the role attribute was removed
• The mobile-specific layout, deprecated back in 2017, is gone
• Helpers can no longer be used inside conditional expressions — a template validation change that will reject templates that previously imported fine

That last one is worth flagging separately. It is a validation change, so a v1 theme with helpers inside conditionals will fail import rather than render incorrectly. You find it immediately, which is the good news.

Upgrading from v2: Accessibility and the Editor

The v2-to-v3 step is smaller but it moves DOM structure, which is exactly what custom CSS is coupled to:

• {{breadcrumbs}} — markup structure changed to support accessibility across all pages. On Request and Request List pages, the final breadcrumb text changed from "My Activities" to "Requests". Any CSS targeting the old structure, and any automated test asserting on the old string, breaks.
• {{select}} — on the New Community Post page the topic selector became a native HTML <select> element, and the placeholder changed from - to "Choose a topic". Custom dropdown styling applied to the old markup no longer applies.
• {{recent_activity}} — gained aria-relevant="additions" and aria-atomic="false" for screen reader compatibility.
• {{actions}} — the permalink popover and escalation modal now render in shadow DOM to prevent style conflicts. This is the one that surprises people: if your theme was restyling those elements from style.css, that styling stops reaching them. Shadow DOM is doing its job, and your override is now outside the boundary.
• {{wysiwyg}} and {{request_form}} — the rich text editor migrated to CKEditor and became available on mobile. The rich text editor only renders when the wysiwyg="true" attribute is set.

Upgrading from v3: The New Request Page Rebuild

This is the step every theme must take, and it concentrates almost entirely in one template.

Removed:

• {{request_form}} — replace with a container div, <div id="new-request-form"></div>
• {{follow_up}} — use the parent object instead

Added:

• {{new_request_form}} — the data object your theme renders the form from
• {{json}} — a helper for passing objects into JavaScript
• {{answer_bot}} — displays AI agent article suggestions on the New Request page

Changed data shapes, which is where the silent breakage lives:

• The categories object no longer exposes articles, articles_count or more_articles on sections, and is limited to five sections and five child-sections
• The sections object is limited to five child-sections and five articles per section
• Outside Article pages, the article object no longer carries body or vote, and exposes a new snippet property instead

The required template edits, per Zendesk's v3 upgrade guide:

1. manifest.json          → set "api_version": 4
2. new_request_page.hbs   → remove <span class="follow-up-hint"> {{follow_up}} </span>
                          → replace {{request_form}} with <div id="new-request-form"></div>
                          → add the Copenhagen <script type="module"> block
3. document_head.hbs      → add the Copenhagen polyfill + import map scripts
4. home_page.hbs          → remove article references
5. assets/                → copy updated assets from the latest Copenhagen theme

Zendesk's reference implementation of the new request form in the Copenhagen theme is built with React and Garden components and is described as fully accessible. In practice that means the path of least resistance is to take Copenhagen's implementation wholesale and restyle it, rather than hand-rolling a form from {{new_request_form}}.

One functional change to test explicitly: the attachments field is hidden when authentication is required. If your help center is open to anonymous submitters and your support process depends on customers attaching screenshots, verify that flow with a logged-out browser session, not just as an admin.

The Marketplace Theme Problem You Cannot Engineer Around

If your help center runs a theme bought from the Zendesk Marketplace, your upgrade is not primarily a technical project. It is a vendor management project.

Zendesk's guidance is direct: check with your theme developer to ensure you upgrade to a v4-ready version of the theme. That is the whole of it. Zendesk will not port a third-party theme for you, and the ZCLI and GUI tools are aimed at custom-coded themes.

Practical steps, in order:

1. Identify the theme and its author. Check the Marketplace listing for a last-updated date. A theme untouched since before v4 shipped is a warning sign.
2. Email the author with a specific question. Not "do you support v4?" but "what is your committed ship date for a Templating API v4 build of this theme, and will it be a free update for existing licences?" Vague answers are answers.
3. Set an internal go/no-go date of December 2026. That gives you a quarter to execute a fallback before imports are blocked.
4. Price the fallback before you need it. The fallback is usually re-implementing your branding on top of a current Copenhagen theme. Get that quoted while it is a planned project, not an incident.

The uncomfortable case is a theme from a vendor that has quietly stopped maintaining its catalogue. There is no remedy for that except doing the work yourself, and the earlier you learn it, the cheaper it is.

The Hidden Costs Teams Underestimate

The manifest edit takes ten seconds. Everything around it is the project.

Multi-Brand Multiplies Everything

Zendesk accounts with multiple brands have a theme per brand. Every one of them is in scope for the forced upgrade, including the ones nobody has touched in three years. Teams scoping "the theme upgrade" routinely scope exactly one theme and discover four.

Unpublished draft themes count too. If a half-finished redesign is sitting in the account on v2, it either gets upgraded on July 31, 2027 or it becomes unusable. Decide now which drafts you are keeping.

Custom JavaScript Is Not Covered by Any Upgrade Guide

Zendesk's guides document what changes in their helpers and objects. They cannot document what changes in your script.js. Custom JS in help center themes tends to accumulate:

• Analytics and tag-manager bootstrapping
• Third-party chat or survey widget injection
• DOM manipulation that rewrites Zendesk-rendered markup after page load
• Form field logic — conditional fields, validation, prefill from query parameters
• Deflection or search-tuning scripts

Every one of these is coupled to DOM structure that changed. The form field logic is the highest risk, because the New Request page is rebuilt from scratch in v4 and any script that queried the old form's elements now finds nothing. Scripts that fail silently are the default here — a querySelector that returns null throws once and stops, and nothing surfaces it.

Content and Theme Are Separate Problems

Worth stating plainly because the two get conflated in planning meetings: this change affects presentation, not content. Your articles, sections, categories, user segments and permissions are untouched by the templating version. If you need to move or back up the underlying Guide content — a separate job with its own API limits and format constraints — we cover it in exporting data from Zendesk Guide.

The reason to keep them separate is sequencing. A theme upgrade and a content migration running concurrently makes every regression ambiguous: you cannot tell whether a broken category page is a template bug or a missing section.

QA Surface Is Larger Than It Looks

A help center has more distinct page types than most teams remember: home, category, section, article, search results, new request, request list, request detail, community topic list, community post, new community post, user profile, subscriptions, sign-in and error pages. Each has its own template and its own helpers.

The v2-to-v3 breadcrumb and community-selector changes, for instance, only show up on pages that many QA passes never open.

Your Three Options

Option 1: Upgrade the Existing Theme In Place

Best for: Custom themes with a maintainer who understands them, and a version gap of one step.

Bump api_version, work the per-version guide, fix what breaks, test, publish. If you are on v3 and your theme is a lightly modified Copenhagen, this is genuinely a days-not-weeks job dominated by the New Request page rebuild.

Where it goes wrong: themes on v1. Three cumulative version steps, dead front-end libraries, and helpers with no replacements mean you are not upgrading a theme so much as archaeologically reconstructing one. Before committing to this path on a v1 theme, honestly compare the effort against option two.

Option 2: Rebuild Branding on Current Copenhagen

Best for: v1 and v2 themes, themes whose original developer is unavailable, and Marketplace themes with no v4 commitment.

Start from the latest Copenhagen theme — which is v4-compatible and is the reference implementation Zendesk's own upgrade guides point you at — and reapply your branding. You end up with a theme that matches Zendesk's current structure, uses the supported request form implementation, and is far easier to carry through the next templating version.

The trade-off is honest: you will lose bespoke layouts that Copenhagen does not model, and "reapply the branding" is a design conversation as much as a code one. But you are not paying down years of accumulated drift, and every future Zendesk change will document itself against the structure you are now on.

For most teams two or more versions behind, this is the cheaper path, not the more expensive one.

Option 3: Use the Forced Date to Re-Evaluate the Platform

Best for: Teams already questioning whether the help center belongs in Zendesk.

If your theme is heavily customised because Zendesk Guide did not do what you needed, a mandated rewrite is a reasonable moment to ask whether you are customising your way around a platform fit problem. Some teams run their public knowledge base on a documentation platform and keep Zendesk for ticketing; others consolidate elsewhere entirely.

Be clear-eyed about the cost comparison. A v4 theme upgrade is a front-end project measured in weeks. A knowledge base platform migration is a content, URL, SEO and permissions project measured in months — our knowledge base migration checklist lays out the sequencing. Do not pick this option because v4 looks annoying. Pick it only if the platform decision was already open, and see our breakdown of Zendesk alternatives and what migration off actually involves before committing.

How Do You Test a v4 Upgrade Safely Before March 1, 2027?

You test it on a copy, never on the live theme, and you finish while re-importing the old one is still possible.

Step 1: Establish Your Rollback Artifact

Download the current live theme as a ZIP and commit it to source control with the templating version in the commit message. This file is your only route back, and it becomes un-importable on March 1, 2027. Verify the download actually re-imports cleanly now — a corrupt or incomplete export you discover in a crisis is the same as no export.

Step 2: Preview Before You Bump

Zendesk's documentation on templating versions notes that previewing a theme surfaces warnings for deprecated helpers. Run a preview on the unmodified theme first so the warnings are about your current state. That list is your work queue.

You can confirm the version you are on in Knowledge admin under Customize design: open the theme, click Edit code, and the version number sits under the theme name, matching api_version in manifest.json.

Step 3: Bump in a Duplicate, Import Unpublished

Duplicate the theme, set api_version to 4 in the duplicate's manifest, work through the template edits, and import the result as an unpublished theme. Unpublished themes can be previewed without affecting live traffic.

Zendesk documents no downgrade path. Editing api_version back down is not a supported rollback, which is precisely why the work happens in a copy.

Step 4: Walk the Full Page Matrix

Test every page type, logged in and logged out, on desktop and mobile:

Flow	What to verify
New request, logged out	Form renders; attachments behave as expected when auth is required
New request, logged in	Field logic, prefill, validation, submission
Follow-up request	The parent object renders the follow-up context that {{follow_up}} used to
Home page	Section and article listings render within the five-item limits
Category and section pages	No reliance on removed articles_count or more_articles
Article page	Voting works — {{vote}} renders buttons, not anchors
Search results	Unified results collection renders both articles and posts
Request list / detail	Breadcrumb reads "Requests"; styling intact
New community post	Native <select> topic picker with the "Choose a topic" placeholder
Rich text editor	CKEditor loads on mobile as well as desktop
Every brand	Repeat for each brand's theme

Step 5: Publish With Time to Spare

Publish the v4 theme with enough runway that a rollback is still an option — meaning comfortably before March 1, 2027. Watch ticket creation volume for the following week. A drop in submitted tickets with no corresponding drop in traffic is the signature of a broken New Request page, and it is the failure mode most likely to go unnoticed by everyone except your revenue.

The Full Upgrade Checklist

Work this list in order. Dates assume you are starting from today.

1. Inventory every theme in the account — published, unpublished, and one per brand. Record the api_version of each.
2. Classify each theme: stock Copenhagen, lightly customised, heavily custom, or Marketplace.
3. Export a ZIP of every theme you intend to keep, into source control, before March 1, 2027.
4. For Marketplace themes, get a written v4 ship date from the vendor. Set an internal go/no-go for December 2026.
5. Grep every theme for removed helpers — logo_url, chat, trending_questions_list, chat_about_my_ticket, category_tree_with_article, section_tree_with_article, article_results, post_results, user_info, unsubscribe, request_form, follow_up.
6. Grep script.js and style.css for jQuery, moment.js, normalize.css and entypo references, and for selectors targeting the permalink popover or escalation modal — the latter moved into shadow DOM in v3.
7. Run a preview to collect deprecation warnings and turn them into tickets.
8. Decide upgrade-in-place versus Copenhagen rebuild per theme. Themes on v1 should default to rebuild unless someone can defend otherwise.
9. Do the work in a duplicate theme, never on the live one.
10. Port the New Request page from the latest Copenhagen theme, including the document_head.hbs polyfill and import map, and the updated assets.
11. Audit custom JavaScript against the new DOM, with particular attention to anything that queried the old request form.
12. Test the full page matrix logged in and logged out, on mobile and desktop, per brand.
13. Publish before March 1, 2027 so that a failed launch is a rollback rather than a rebuild.
14. Re-test after the vendor tooling lands if you used the ZCLI or GUI upgrade tool — automated conversion is a starting point, not a finished theme.

When to Bring In Help

Be honest about which situation you are in, because two of the three are ordinary front-end work.

If you run stock Copenhagen or a lightly restyled version of it, do nothing dramatic. Confirm the version, keep an eye on the dates, and bump it when convenient. You do not need help and you should not buy any.

If you have a custom theme on v3 with a maintainer who wrote it, this is a normal sprint. The New Request page rebuild is well documented, the Copenhagen reference implementation is available, and the failure modes are visible in testing. A competent front-end developer with Zendesk context will finish it.

Where it stops being a DIY job is when three things are true at once: the theme is on v1 or v2, the person who built it has left, and the help center carries meaningful ticket-deflection or self-service volume. At that point you are reverse-engineering undocumented templates against a hard date, and the cost of getting it wrong is measured in support tickets that never got filed.

Separate two questions that get blurred together: who owns the theme runtime after the upgrade, and who preserves the content and structure underneath it. The first is front-end engineering — Curlybars, CSS, JavaScript, the Copenhagen reference implementation. That work usually belongs with your own developers or a Zendesk theme specialist, and we will tell you so.

The second is where ClonePartner works. We handle the data layer: article and section structure, category hierarchies, user segments and permissions, attachments, URL and redirect continuity, and the sequencing of a cutover so nothing goes dark mid-migration. Across 1,500+ migrations and 500+ integrations, the pattern we see is that theme upgrades go wrong quietly and content migrations go wrong loudly — and teams that treat them as one project get the worst of both.

We are typically the right call when the templating deadline has forced a larger question — whether the knowledge base should stay in Zendesk Guide at all, whether content needs consolidating from several help centers into one, or whether a brand restructure is happening at the same time. If your only problem is that {{request_form}} no longer exists, hire a front-end developer and point them at Zendesk's v3 upgrade guide.