Guide · Templating API v4
Zendesk Templating API v4 migration: what breaks and how to move
Zendesk is retiring Templating API v1, v2 and v3 for Help Center themes. Here is the timeline, how to check your theme, what breaks and what to do about it.
Updated
If your Help Center theme is older than Copenhagen 4, it runs on an old Templating API. Zendesk will stop accepting those themes and then upgrade the rest. This guide covers what that means for a custom theme.
The end-of-life timeline
These dates come from Zendesk's announcement, checked on October 9, 2026. Zendesk's developer notes for v3 give August 3, 2027 as the end-of-life date. The announcement says July 31, so plan for the earlier one. For what to do before each date, see the theme deadline guide.
- September 14, 2026
- Importing v1, v2 and v3 themes is blocked for new accounts.
- November 25, 2026
- Zendesk releases a command-line (ZCLI) upgrade tool for custom-coded themes.
- March 1, 2027
- An in-product upgrade tool arrives. Importing v1, v2 and v3 themes is blocked for all accounts.
- July 31, 2027
- Remaining legacy themes are upgraded to v4 by Zendesk, and v1 to v3 are removed.
The practical deadline is July 31, 2027. Before that, imports of old themes stop working, so you cannot restore a backup or move a theme to a new account.
How to check your theme version
- In Guide, open Customize design.
- On the theme, open its options menu and choose Download.
- Unzip the file, open
manifest.jsonand findapi_version.
Zendesk documents the download as the way to reach the manifest. Some accounts also list it under Edit code. If you cannot download a theme, for example one a vendor supplies, ask the vendor which version it uses.
A value of 4 means you are done. A value of 1, 2 or 3 means the theme needs to move. Check every theme in the list, not only the live one.
What breaks on a custom theme
Zendesk's own v3 to v4 upgrade notes list the changes. These are the ones that hit custom themes:
- The new request page loses
{{request_form}}and{{follow_up}}. You build the form from{{new_request_form}}, and Copenhagen renders it with a React component. - The document head needs new script blocks, and the theme needs Copenhagen's
assetsfolder. - On the home page, sections no longer carry
articles,articles_countormore_articles. - Lists are capped: 5 sections on the home page when there is more than one category, 5 child sections per category, and 5 articles per child section. Outside the article page, an article has no
bodyorvote. It has asnippetinstead.
A theme that has never touched these areas can be quick to move. A heavily forked one rarely is, because the request form is where most custom code lives.
A short migration checklist
- List your themes and note each
api_version. - Export a copy of every theme you plan to keep.
- Diff your theme against the current Copenhagen release, so you know which files you changed.
- Set
api_versionto4inmanifest.jsonand copy in Copenhagen'sassetsfolder. - Rebuild the new request page and the document head from Copenhagen, then re-apply your changes on top.
- Fix home page code that read section articles.
- Test as a visitor and as a signed-in user: search, an article, the request form with attachments, and the request list.
- Publish, and keep the old copy until you are sure.
If you bought a theme from a vendor, ask them whether it is on v4. The announcement tells Marketplace theme owners to check this with their vendor. Zendesk also plans two upgrade tools, a ZCLI tool for developers and an in-product tool for everyone else. Neither replaces testing: Zendesk says the in-product tool still needs a manual check.
Looking for a theme that is already on v4? See free Zendesk Help Center themes or ZenTheme Nightfall, which is free and on v4.
Questions about your theme? Write to hello@zenthemelab.com. Not affiliated with Zendesk.