Edit a theme package and submit it to the Theme Store
Download a theme package from your dev store, change its design settings, page layouts and CSS in the zip, upload it as a submission, check which edits were used, preview it, and get it approved for the Theme Store.
Download this guide: PDF · Word (.docx)
On this page
You need an approved partner account and a dev store (see “Build apps and themes from start to finish”). The easiest way to make a theme is still to design it in the real theme editor on your dev store and submit it with “From a development store”. Editing the zip is for changes you prefer to make in files, or for moving a theme between stores. A package carries design settings, the section layout of every page, the header, footer and password page, and custom CSS, JavaScript and head snippets. It can't add new section types or carry image files: images must already be uploaded to your dev store, and they are copied automatically.
Download the package
Open your dev store's admin, go to Online Store → Themes, open the “…” menu on the theme and choose “Download theme file”. You get a zip. Built-in themes such as Crave can only be downloaded once they are in one of your stores: add the theme to your dev store first, then download it from there.
Know which files you can edit
Unzip the package. These files are read back when you upload it:
- shopwise-theme.json: the main file. It holds name, settings, customCss, sections, codeFiles and presetKey, plus a “shopwise” block. Keep “version” at 1 (that is the file format). Put your own theme version in “themeVersion”, for example "2.0.0" (numbers and dots only, up to 20 characters).
- config/settings_data.json: design settings (colours, fonts, spacing) under “current”. A setting you delete goes back to the preset's default.
- templates/index.json, product.json, collection.json, cart.json, blog.json, search.json, page.json and suffix templates such as page.contact.json: the sections on each page, as {"sections": {…}, "order": […]}.
- config/groups.json: header, footer and password page.
- assets/custom.css: your extra CSS.
- sections/*.json and the README files are reference only and are never read back. Use sections/ to see which section types exist.
- custom.js and head snippets are only read from codeFiles inside shopwise-theme.json.
Make your changes
Edit either the main file or the separate files. Each export records a fingerprint of every separate file, so the upload can tell which ones you changed. A file you didn't touch is ignored. If you change the same thing in both shopwise-theme.json and a separate file, the main file wins and the upload warns you. Re-formatting a file (spacing, key order) doesn't count as a change.
- Example: change the colours in config/settings_data.json → current, re-order or add sections in templates/index.json using types listed in sections/, add CSS to assets/custom.css, and set "themeVersion": "2.0.0".
- Section types that don't exist are left out and listed after upload.
- Hidden blocks stay hidden when you edit a template.
- An emptied template file is skipped (with a warning), so you can't clear a page by uploading an empty file.
Zip it again
Zip the files again. A wrapping folder inside the zip is fine, and so are the extra files macOS adds. Keep the zip under 5 MB and include only one theme.
Upload it as a new submission
In the partner portal, select “New submission” on the Dashboard, choose a theme, pick the upload option and select “Upload a file”. Fill in the listing details and screenshots, then save. If the file can't be read, the page says exactly why: the JSON position of a syntax error, a missing shopwise-theme.json (with the list of files it found), two themes in one zip, or a changed “version” number. Fix it and choose the file again. You don't need to reload the page.
Check which edits were used
The submission page lists “Your edits to these files were used: …” and any warnings, such as settings or section types that were left out. The “Theme package” card shows the theme name, preset, how many settings differ from the preset, the sections on the home page and the version. If you edited the home page, Sections no longer says “stock default layout”.
Preview it
On the submission page, select “Preview in a development store”, then “Open in theme editor”. A new draft theme named after your submission opens in the real theme editor on your dev store, where you can look at every page. This works for drafts and for submissions waiting for review.
Fix and upload again
While the submission is a draft, use “Upload a new package” on the submission page to replace the file. The listing details stay as they are. If you already submitted it, select “Withdraw submission” first. That turns it back into a draft you can change.
Submit for review and get approved
Use “Save and submit” (or submit from the draft). If the submit step fails, the submission page shows the reason, for example a missing screenshot. When the Lulu team approves it, the theme is published on the Theme Store with your screenshots and the version from themeVersion, and buyers install exactly the package you submitted. After approval, the Listings page lets you download the package, upload a new zip, open the editor, or sync from your store.
- A Theme Store “View demo” button is not available for partner themes yet. Buyers see your screenshots.
CHECK YOUR WORK
You’re ready when…
- The package was downloaded from your dev store with “Download theme file”.
- “version” in the shopwise block is still 1, and themeVersion looks like 2.0.0.
- The upload shows “Your edits to these files were used” for the files you changed.
- The preview in your dev store looks the way you expect.
- Screenshots are attached before you submit.
IF SOMETHING DOESN’T LOOK RIGHT
Troubleshooting
The upload says the package is for a newer version of the platform.
You changed “version” in the shopwise block. That number is the file format: set it back to 1 and put your theme's version in “themeVersion” instead.
My theme still looks like the original after uploading.
Check the list of used edits on the submission page. A file with no changes from the export is ignored. If you edited both shopwise-theme.json and a separate file for the same thing, the main file wins. Packages downloaded before 9 October 2026 have no fingerprints, so their separate files are ignored: download a fresh package and apply your changes to it.
The upload says it looks like a Shopify theme export.
Shopify themes (Liquid files) can't be uploaded. Use a package downloaded from a Lulu store.
Choosing the same file again does nothing.
After a failed upload the file field is cleared, so choose the file again. If you edited the file after choosing it, choose it again too.
Some sections or settings were “left out”.
Only section types that exist on the platform (listed in sections/) and settings the theme knows can be imported. Rename them to existing ones, or build the layout in the theme editor instead.