Shopify Liquid: Customize Theme Code Without Breaking Your Store

This article is for you if you want to customize your Shopify theme beyond the editor, are toying with Liquid or need to decide whether you need a developer. You'll learn what Shopify Liquid can and can't do, how to change code safely and when headless makes sense. The overview of themes, apps and tracking is in the hub Shopify design and technology.

The five levels of customization

Not every change needs code. In the Help Center, Shopify itself advises only editing theme code if a change can't be made with an app or the theme editor. So work your way from top to bottom:

Most stores in the DACH region get by with levels 1 to 3. How to work with the editor is shown in the article Customizing your Shopify theme. The base you choose also determines how much code you'll need later. More on this in the article Choosing a Shopify theme.

What Shopify Liquid is and what it can't do

Liquid is a template language. It runs on Shopify's servers, reads data such as products, collections, the cart or metafields and outputs HTML from it. You can use it to write conditions, loops and filters, for example "show this notice only for products with the tag bulky".

What Liquid can't do: store data, run your own database queries or process forms server-side like PHP. People coming from WordPress often look for this in vain. For forms, you use the built-in Shopify forms (contact, newsletter, customer account), additional fields in the contact form or an app. For logic that writes data or talks to external systems, you need an app with its own backend or Shopify Flow. Hence the common question "If I program everything myself, why use Shopify?": Shopify takes care of hosting, checkout, payments, security and the admin. Liquid only controls the presentation.

For Liquid, you need HTML and CSS as a foundation, and a bit of JavaScript for interactive elements. You don't need React for normal themes, only for headless projects or app development.

Custom Liquid: code without the code editor

The free Shopify themes such as Dawn usually include a "Custom Liquid" section in the theme editor, and so do many other themes. There you insert Liquid, HTML and CSS directly in one place, on any page, including landing pages. The advantage: the snippet is a setting in the editor, not a change to the theme files. It survives updates and can be removed with one click.

Typical uses:

• Showing a metafield on the product page, such as care instructions or manufacturer information under the GPSR: {{ product.metafields.custom.care_instructions }}
• A notice only for certain products: {% if product.tags contains 'bulky' %}Shipped by freight carrier{% endif %}
• Your own small inquiry form with an extra field, such as "order number": Shopify contact forms accept fields named contact[Order number]. Adding a field to the existing contact form section, on the other hand, is already a change to the theme code.
• Embedding a video or an external widget that isn't a block of its own.

If code suddenly shows up visibly on the page, a closing tag is usually missing or you've inserted text outside an HTML element. Clear the field completely and paste the code again. Don't use the section for tracking codes: pixels belong in customer events or the official channels. How that works is covered in the article Setting up tracking in Shopify.

Editing theme code safely

You'll find the code editor in the admin under "Online Store > Themes": click the three-dot menu on the theme you want and choose "Edit code". Here's how to proceed without putting your live store at risk:

1. Duplicate the theme. Shopify explicitly recommends this as a backup. Edit the copy, not the published theme.
2. Test in the preview. You can check the copy in the preview, including on mobile, before you publish it.
3. Comment your changes. Mark every custom spot in the code with a comment like "Customization October 2026: delivery time notice". That will save you hours at the next update.
4. Know the history. The editor saves older versions of individual files. You can use it to restore a file. You can't get back deleted files or a complete theme this way, and the history is limited.
5. Don't delete files whose purpose you don't know. According to Shopify, this can break the theme.

Theme updates: what happens to your changes

According to the Shopify Help Center, a theme update creates a new copy of your theme. Everything you've set in the theme editor is carried over: settings, sections, blocks, templates and app embeds. Code changes are only carried over if they don't conflict with the update; changes in the "Templates" folder and to the file settings_data.json don't count here. Afterwards, Shopify shows you whether your code changes could be included. If not, you have to transfer them to the new version by hand. You should check your custom CSS after every update, because class names may change.

This leads to a simple rule: the more you solve with editor settings, Custom Liquid and app blocks, the more relaxed updates are. Lots of code changes are a reason to postpone updates, and in the long run that costs you new features and bug fixes.

Developing locally: Shopify CLI, GitHub, development store

For more than a few lines, the editor in the browser isn't worth it. Developers work locally, for example in VS Code, with the Shopify CLI. With it, you download a theme, see changes in a live preview against real store data and upload them again. Liquid can't run without Shopify. The preview always runs against a store.

• Requirement: Node.js and npm. You install the CLI via npm.
• Windows: If PowerShell reports that scripts are disabled, that's due to Windows' execution policy, not Shopify. Allow scripts for your user or use the Command Prompt. If "npm" isn't recognized, Node.js isn't installed or the terminal wasn't restarted after installation.
• Access: You need staff or owner access with theme permissions. For client stores, agencies work via staff accounts or collaborator access.
• GitHub: Themes can be connected to a GitHub repository. Changes in the repository then end up in the theme. That's clean for teams and versioning.
• Development store: You don't need a paid plan for learning and testing. You create development stores through a free partner or developer account.

You can include frameworks like Tailwind or Bootstrap; technically it's just CSS. But keep in mind: an additional framework alongside the theme CSS makes the page heavier and can worsen load time, which matters for Shopify SEO and conversion.

Headless with Hydrogen: when does it make sense?

Headless means: Shopify only supplies data and checkout, and you build the frontend completely yourself. Shopify's own framework for this is Hydrogen, a scaffold built on React Router. It is hosted on Oxygen. According to Shopify, Oxygen is available on the paid plans at no extra cost, so not only on Shopify Plus. But headless doesn't save you a Shopify plan. You keep paying for it, plus development.

Who it's worth it for:

• Brands with their own development team and a budget for ongoing maintenance
• Projects where Shopify is only one building block, for example alongside an app or a large content portal
• Very specific experiences that aren't possible with themes

For most small and medium-sized stores, it's the wrong choice. You lose the theme editor for marketing changes, many apps only work with Online Store themes, and every detail has to be programmed. Shopify continues to develop Liquid themes in parallel. So there's no reason to believe that Hydrogen will replace Liquid any time soon. Existing stores are better off building individual interactive areas with JavaScript in the theme instead of rebuilding everything.

"Liquid error" in your store: how to find the cause

If "Liquid error (internal)" or a similar error appears at the top of your store, a piece of code is almost always broken. Typical causes and fixes:

1. Undo the last change: Who last changed code? Restore the affected file via the history.
2. Leftovers from uninstalled apps: Older apps inserted snippets directly into theme files. After uninstalling, the code refers to a snippet that no longer exists. Search the code for the app name and remove the reference, ideally with help from the app's support.
3. Check Custom Liquid: Hide your own Liquid sections as a test.
4. Switch to a backup: Publish the last working theme copy so the store runs again immediately, and look for the error at your leisure.

Modern apps use theme app extensions: they add app blocks and app embeds that you control in the editor instead of changing theme files. Pay attention to this when choosing apps. More on this in the article Shopify apps for beginners.

When you need a developer

Get help if at least one of these points applies: the change affects the cart, prices or product logic. It has to work on all devices and in all languages. You've searched for more than two hours without a result. Or it involves a connection to external systems such as an inventory management system or an ERP. How to find a suitable partner and what it costs is covered in the article Hiring Shopify experts. AI assistants help with understanding and writing Liquid. What AI can do for building a store overall is shown in our test of AI store builders. But you still have to test the code in a theme copy.

FAQ

Do I have to learn Liquid for Shopify?

No. Most merchants get by with the theme editor, Custom Liquid for small snippets, and apps. Liquid is worth it if you make customizations regularly or want to work with Shopify as a developer. Then start with HTML and CSS, read Shopify's official Liquid reference and practice on a free development store instead of your live store.

Does it cost anything to edit Liquid code?

The code editor is included in every Shopify plan; you don't need an add-on. For learning and developing, you use a free development store through a partner or developer account. Costs only arise if you buy a premium theme, use apps or hire a developer. For a live store, you of course need a paid plan.

Can I bring a Figma design into Shopify?

Not as a clean theme at the push of a button. A Figma design is a template that a developer translates into a theme's sections and blocks. It usually makes more sense to choose a good existing theme and adapt the design to it, instead of building a completely custom theme. That way the theme editor and updates remain usable, and costs stay manageable.

How do I work on an existing store without breaking anything?

Duplicate the published theme and only work in the copy. Test all changes in the preview on desktop and mobile, with real products and a test order. Document every change. Only when everything is right do you publish the copy. The old theme stays in your theme library as a backup and can be reactivated at any time.

Do ChatGPT or GitHub Copilot work with Liquid?

Yes, AI assistants know Liquid and can explain or write snippets. But they sometimes invent objects or filters that don't exist, or don't know new theme structures. So check suggestions against the official Shopify documentation and test them exclusively in a theme copy before you take them live.

Will Hydrogen replace Liquid soon?

It doesn't look like it. Shopify maintains both paths: Liquid themes for the Online Store, including the new Horizon themes, and Hydrogen for headless projects. For the vast majority of stores, the Liquid theme remains the standard, because the editor, apps and updates work best with it. Hydrogen is an option for projects with a development team, not a successor.

As of: October 2026. Information on theme updates, checkout and Hydrogen according to the Shopify Help Center and Shopify developer documentation.