Developer docs

Breaking changes

A catalog of critical changes between major Ghost versions

New major versions typically involve some backwards incompatible changes. These mostly affect custom themes, and our theme compatiblity tool GScan will guide you through the updates. If you use custom integrations,the API or webhooks you should also expect things to change when switching between API versions.

How to update?

The update guide explains how to update from Ghost 1.0 or higher to the latest version.

When to update?

The best time to do a major version update is shortly after the first minor version - so for Ghost 4.x, the best time to update will be when 4.1.0 is released.

This is when any bugs or unexpected compatibility issues have been resolved but the team & community are still context loaded about the changes. The longer you hold off, the bigger the gap becomes between the software you are using and the latest version.

Ghost 4.0

Ghost 4.0 focuses on bringing Memberships out of beta. There are a few additional changes:

  • New /v4/ (stable) and /canary/ (experimental) API versions have been added.
  • The /v3/ (maintenance) endpoints will not receive any further changes.
  • The /v2/ (deprecated) endpoints will be removed in the next major version.
  • v4 Admin API /settings/ endpoint no longer supports the ?type query parameter.
  • v4 Admin API /settings/ endpoint only accepts boolean values for the key unsplash.
  • Redirects: definitions should now be uploaded in YAML format - redirects.json has been deprecated in favour of redirects.yaml.
  • Themes: must now define which version of the API they want to use by adding "engines": {"ghost-api": "vX"}} to the package.json file.
  • Themes: due to content images having width / height attributes, themes with CSS that use max-width may need to add height: auto to prevent images appearing squashed or stretched.
  • Themes: The default format for the {{date}} helper is now a localised short date string (ll).
  • Themes: @site.lang has been deprecated in favour of @site.locale.
  • Private mode: the cookie has been renamed from express:sess to ghost-private.
  • Other: It’s no longer possible to require or use Ghost as an NPM module.


Members functionality is no longer considered beta and is always enabled. The following are breaking changes from the behaviour in Ghost 3.x:

  • v3/v4 Admin API /members/ endpoint no longer supports the ?paid query parameter
  • v3/v4 Admin API /members/ endpoints now have subscriptions on the subscriptions key, rather than stripe.subscriptions.
  • v3/v4 Admin API /posts/ endpoint has deprecated the send_email_when_published flag in favour of email_recipient_filter.
  • Themes: The @labs.members theme helper always returns true, and will be removed in the next major version.
  • Themes: The default post visibility in foreach in themes is now all.
  • Themes: The default_payment_card_last4 property of member subscriptions now returns **** instead of null if the data is unavailable.
  • Portal: query parameters no longer use portal- prefixes.
  • Portal: the root container has been renamed from ghost-membersjs-root to ghost-portal-root.
  • Other: Stripe keys are no longer included in exports.
  • Other: Using Stripe related features in a local development environment requires WEBHOOK_SECRET, and live stripe keys are no longer supported in non-production environments.

Ghost 3.0

  • The Subscribers labs feature has been replaced with the Members labs feature.
  • The v0.1 API endpoints & Public API Beta have been removed. Ghost now has a set of fully supported Core APIs.
  • The Apps beta concept has been removed. Use the Core APIs & integrations instead.
  • Themes using GhostHunter must upgrade to GhostHunter 0.6.0.
  • Themes using ghost.url.api() must upgrade to the Content API client library.
  • Themes may be missing CSS for editor cards added in 2.x. Use gscan to make sure your theme is fully 3.0 compatible.
  • Themes must replace {{author}} for either {{#primary_author}} or {{authors}}.
  • New /v3/ (stable) and /canary/ (experimental) API versions have been added.
  • The /v2/ (maintenance) endpoints will not receive any further changes.
  • v3 Content API /posts/ & /pages/ don’t return primary_tag or primary_author when ?include=tags,authors isn’t specified (these were returned as null previously).
  • v3 Content API /posts/ & /pages/ no longer return page: true|false.
  • v3 Content + Admin API /settings/ no longer returns ghost_head or ghost_foot, use codeinjection_head and codeinjection_foot instead.
  • v3 Admin API /subscribers/* endpoints are removed and replaced with /members/*.
  • v3 Content + Admin API consistently stores relative and serves absolute URLs for all images and links, including inside content & srcsets.

Switching from v0.1 API

  • The Core APIs are stable, with both read & write access fully supported.
  • v0.1 Public API (read only access) is replaced by the Content API.
  • v0.1 Private API (write access) is replaced by the Admin API.
  • v0.1 Public API client_id and client_secret are replaced with a single key, found by configuring a new Custom Integration in Ghost Admin.
  • v0.1 Public API ghost-sdk.min.js and ghost.url.api() are replaced with the @tryghost/content-api client library.
  • v0.1 Private API client auth is replaced with JWT auth & user auth now uses a session cookie. The @tryghost/admin-api client library supports easily creating content via JWT auth.
  • Scripts need updating to handle API changes, e.g. posts and pages being served on separate endpoints and users being called authors in the Content API.

Ghost 2.0

  • API: The /v2/ API replaces the deprecated /v0.1/ API.
  • Themes: The editor has gained many new features in 2.x, you may need to add CSS to your theme for certain cards to display correctly.
  • Themes: {{#get "users"}} should be replaced with {{#get "authors"}}
  • Themes: multiple authors are now supported, swap uses of author for either {{#primary_author}} or {{authors}}.
  • Themes: can now define which version of the API they want to use by adding "engines": {"ghost-api": "vX"}} to the package.json file.
  • Themes: there are many minor deprecations and warnings, e.g. @blog has been renamed to @site, use gscan to make sure your theme is fully 2.0 compatible.
  • v2 Content+Admin API has split /posts/ & /pages/ endpoints, instead of just /posts/.
  • v2 Content API has an /authors/ endpoint instead of /users/.
  • v2 Admin API /posts/ and /pages/ automatically include tags and authors without needing ?includes=.
  • v2 Content + Admin API attempts to always save relative & serve absolute urls for images and links, but this behaviour is inconsistent ๐Ÿ›.

Ghost 1.0

  • This is a major upgrade, with breaking changes and no automatic migration path. All publications upgrading from Ghost 0.x versions must be upgraded to Ghost 1.0 before they can be successfully upgraded to Ghost 2.0 and beyond.
  • See announcement post and developer details for full information on what we changed in 1.0.
  • v0.1 Public API /shared/ghost-url.min.js util has been moved and renamed to /public/ghost-sdk.min.js
  • Ghost 0.11.x exports donโ€™t include clients and trusted_domains so these arenโ€™t imported to your new site - you’ll need to update any scripts with a new client_id and client_secret from your 1.0 install.
  • Themes: Many image fields were renamed, use gscan to make sure your theme is 1.0 compatible.