What Is the write_themes Scope in Shopify?

What the Shopify write_themes access scope grants, how it differs from read_themes, why extension apps request it, and how to check an app's scopes.

4 min readUpdated

Part of our guide to Shopify Theme App Extensions, Explained.

When you install a Shopify app that works with your storefront's design, the permission screen may list "manage themes" — the merchant-facing name for the write_themes access scope. It's reasonable to want to know exactly what that grants before you approve it. This guide explains what read_themes and write_themes cover, why an app that ships a theme app extension requests them, and how to check an app's scopes for yourself.

For where theme app extensions fit overall, see the parent hub, Theme App Extensions, explained.

The two theme scopes

Shopify's Admin API gates access with access scopes. Two apply to themes:

  • read_themes — lets an app read theme data through the Admin API: list the shop's themes, read theme files (assets) and their contents. Read-only.
  • write_themes — lets an app modify theme data through the API: create, update, and delete theme assets, and manage themes. It implicitly includes the read capability.

In the merchant permissions dialog these appear as "View your Online Store" / theme-read language and "Manage your Online Store" / theme-write language. The scope name (write_themes) is what you'd see in an app's configuration; the plain description is what you see at install.

What write_themes actually lets an app do

Granting write_themes means the app can, via the Admin API:

  • Read the list of themes and each theme's files.
  • Create, update, or delete theme assets — the .liquid, JSON, CSS, and JS files that make up a theme.
  • Perform theme-level management actions the API exposes.

That's a real capability, and it's fair to treat it seriously: an app with write_themes can write into theme files. The scope describes what's possible, not what a given app does — which is the important distinction in the next section.

Why an extension-based app requests theme access

Here's the part that trips people up. A theme app extension is the non-destructive integration path — its whole point is that the app's blocks render from the extension and are only referenced by the theme, so they don't live in theme files (that's covered in App blocks vs. Liquid sections). So why would such an app ask for theme scopes at all?

A few legitimate reasons:

  • Onboarding and setup. An app may need to read the active theme to confirm it's an Online Store 2.0 theme that supports app blocks, or to deep-link the merchant into the theme editor at the right spot to enable an app embed.
  • Reading theme structure. Detecting which templates and sections exist, so the app can guide placement, is a read operation.
  • Optional file operations. Some apps offer to write a snippet or adjust a setting on request — for example, a one-click install that adds a block for you. That specific action needs write access.

The honest reading: write_themes is commonly requested for setup convenience and theme detection, and the scope an app declares should match what it actually does. An extension app doesn't need to keep code in your theme to function — the extension model exists precisely so it doesn't have to.

How to check an app's scopes before installing

You don't have to take it on faith. Before or during install:

  1. Read the permissions screen carefully. Shopify shows every scope an app requests at install, in plain language ("Manage your Online Store"). This is the authoritative list for that app.
  2. Check the app listing. App Store listings surface the data an app accesses. If the requested access looks broader than the app's stated job, that's worth a question to the developer.
  3. Review granted access anytime. In your admin under Settings → Apps and sales channels, open an installed app to see what it can access, and use Develop apps / API access there to inspect custom-app scopes. You can uninstall to revoke everything at once.
  4. For custom or dev-store apps, the requested scopes are declared in the app's configuration (for CLI apps, the [access_scopes] block in shopify.app.toml), so a developer can read them directly.

A quick way to think about it: read scopes let an app look; write scopes let it change. If an app that should only be adding blocks via an extension is asking to manage themes, it's fair to ask why — a good developer will have a straight answer (usually onboarding and detection).

The bigger point: extensions don't overwrite your theme

Whatever scope an app holds, the durable-content story comes down to how it renders, not just what it can touch. An app that renders through a theme app extension places its blocks so a theme update or swap doesn't remove them — because they were never written into theme files in the first place. That's the same reason hand-pasted .liquid gets wiped on update while app blocks don't, laid out in Update your theme without losing customizations.

SectionGuard uses this model: sections render through a theme app extension rather than being written into your theme, and you can review exactly what it requests on the standard Shopify permissions screen before you approve it.