Uploading Custom Themes

In addition to the built-in themes, you can upload custom themes to give your store a unique look. Custom themes are distributed as ZIP files and can be installed directly from your admin panel.

How to Upload a Theme

1. Log in to your Admin Panel
2. Go to Themes in the sidebar
3. Click the Upload Theme button
4. Select the theme .zip file from your computer
5. Wait for the upload and extraction to complete

Once uploaded, the new theme will appear in your theme grid alongside the built-in themes. It will not be activated automatically -- you need to activate it yourself.

Activating the Uploaded Theme

After the upload is complete:

1. Find the new theme in your theme grid on the Themes page
2. Click Activate on the theme card

Your storefront will immediately switch to the new theme.

Theme ZIP Requirements

For a theme ZIP to be accepted, it must meet these requirements:

• The ZIP must contain a valid theme.json manifest file
• The theme.json file must include at least a name and slug field
• The theme slug must use only lowercase letters, numbers, and hyphens (e.g., my-custom-theme)
• The slug must be unique -- you cannot upload a theme with the same slug as an existing one

Here is an example of a minimal theme.json file:

{
    "name": "My Custom Theme",
    "slug": "my-custom-theme",
    "version": "1.0.0",
    "description": "A custom theme for my store.",
    "author": "Your Name"
}

WARNING

If the ZIP file does not contain a valid theme.json, the upload will fail and you will see an error message. Make sure you are uploading the correct file as provided by the theme developer.

After Uploading

Important

Custom themes that include new page templates or components require a frontend rebuild (npm run build) on the server after uploading. If you are on shared hosting without terminal access, this step may need to be handled by the theme developer or by using a pre-built theme package. Contact your theme provider if you are unsure.

Pre-built themes (those that ship with compiled assets) will work immediately after upload and activation without any additional steps.

Deleting a Custom Theme

If you no longer need a custom theme:

1. Go to Admin Panel > Themes
2. Find the theme you want to remove
3. Click the Delete button on the theme card
4. Confirm the deletion

WARNING

If you delete a theme that is currently active, your store will automatically switch back to the Default theme. The Default theme cannot be deleted.

Troubleshooting

Upload fails with "Failed to open ZIP file"

• Make sure the file is a valid .zip archive and is not corrupted
• Try downloading the theme file again from your provider

Upload fails with "Theme must contain a theme.json file"

• The ZIP may have the wrong folder structure. The theme.json file should be either at the root of the ZIP or inside a single top-level folder

Upload fails with "A theme with slug already exists"

• A theme with the same identifier is already installed. Delete the existing version first, then upload the new one

Theme looks broken after activation

• The theme may require a frontend rebuild. Contact your theme provider for a pre-built version or ask your hosting provider for help running npm run build