Updating theme references after duplicating a resource — Asset API vs. theme app extensions?

Extensions
1

Hey all,

I’m building a public app (heading for the App Store), and I’ve hit a wall on the right way to handle theme integration, and I’d appreciate a sanity check from anyone who’s navigated this.

What the app does, briefly: it duplicates a Shopify resource (Shopify doesn’t allow the change in place, so a replacement has to be created), and then updates references to the original resource so the store keeps working after the swap. References live in a few places — metafields, navigation, etc. — and those I can handle cleanly through the Admin API. The one that’s giving me trouble is the theme.

The problem: when the original resource is replaced, any reference to it baked into the theme can break — section/block settings that point at it by ID, the occasional hardcoded reference in custom Liquid, and the original resource’s URL 404ing once the old one is removed.

Where I’m stuck: my first implementation rewrote the relevant theme files directly (via themeFilesUpsert / the Asset API equivalent). I now understand that’s the thing App Store requirement 5.1.1 / Built for Shopify 3.2.2 specifically prohibit - apps shouldn’t make code changes to a merchant’s theme, and Asset write access for public apps has been gated behind a protected scope since 2023-04.

So as I see it, the options are:

  1. Request the protected Asset API scope. The docs say it’s possible, but it reads like an approval tied to specific exception categories (page builder / backup-restore / SEO-content-locking-dev-tooling). I’m not sure my use case qualifies, and I’d rather not build on something that risks BFS or gets rejected in review.

  2. Theme app extension. I get that this is the sanctioned route, but as far as I can tell an app block only helps if the merchant adopts my block in place of their existing theme sections — it doesn’t retroactively fix references already sitting in their theme. So it feels like a net-new feature rather than a fix for the actual migration.

  3. Don’t touch the theme at all — reuse the original handle on the replacement so handle-based references resolve automatically, create a server-side 301 (urlRedirectCreate) for the old URL, and just detect leftover by-ID references (read-only Asset access is still allowed) and tell the merchant to re-point them in the theme editor.

My questions:

  • For an app that needs to repair theme references after replacing a resource, is there any compliant path other than option 3? Is “detect + prompt the merchant to re-point manually” genuinely the expected pattern here?

  • Has anyone actually been granted the protected Asset write scope for a use case like this, or does Shopify uniformly push you to theme app extensions?

  • Am I missing a cleaner mechanism for “this resource moved, update the storefront references” that I haven’t considered?

Trying to do this the right way rather than fighting the platform. Thanks in advance for any pointers.