# Theme Submission Guidelines

Requirements and best practices for submitting themes to the Finqu partner portal.

## Before you publish

Your theme is validated in the partner portal every time you publish for the first time or release an update. If a requirement is not met, you see a notification in the portal. When there are no notifications, you are ready to publish.

Before clicking **Publish**:

1. Confirm your theme meets the **requirements for its channel type** (required page templates).
2. Review the **theme summary** — name, author, demo URL, documentation URL, and preview image must be correct (editable in theme settings).
3. For updates: set a valid **semantic version** and write a **changelog** describing what changed.

## Submission requirements

### Required page templates

Your theme must support rendering the page types defined for its **target channel type**. The partner portal lists which templates are required — commonly including:

- Storefront pages: `frontpage`, `product`, `category`, `cart`, `search`, `page`, `404`, and customer account templates
- Checkout themes: `checkout`, `complete`, `download`, `order`, `orders`, `return`

Create a `.liquid` file for each required template under `templates/`. Use alternate templates (e.g. `product.campaign.liquid`) only as optional variants — the base type must exist.

See [Templates & Layouts](/build-with-finqu/liquid-themes/templates-layouts) for the full template list.

### Build and deploy

You must **build your theme at least once** before publishing. In practice this means:

- Run `finqu theme deploy` or your publish workflow so Finqu compiles assets (`.scss.liquid` → CSS in `public/`).
- Ensure `config/settings_schema.json` and `config/settings_data.json` are valid JSON.
- Include a `layout/theme.liquid` and at least one locale file per supported language.

Do not hardcode paths to `public/` — use `asset_url` so compiled filenames resolve correctly after deploy.

### Theme metadata

Set these in `config/settings_schema.json`:

| Field | Purpose |
|-------|---------|
| `theme_name` | Public name shown to merchants |
| `theme_author` | Your company or name |
| `theme_image` | Preview image path (e.g. `assets/theme-preview.jpg`) |
| `theme_demo_url` | Live demo store URL |
| `theme_documentation_url` | Link to your theme docs |

### Preview assets

The partner portal expects theme preview media. Include images in your `assets/` directory and reference them from `theme_image` and section/block defaults.

## Versioning and releases

Use [semantic versioning](https://semver.org/) for theme releases (`MAJOR.MINOR.PATCH`).

| Bump | When | Merchant impact |
|------|------|-----------------|
| **PATCH** | Bug fixes, small CSS tweaks | Safe update |
| **MINOR** | New sections/blocks, backward-compatible features | Safe update |
| **MAJOR** | Breaking schema or layout changes | May reset merchant presets to theme defaults |

Always fill in the **changelog** when releasing an update. An empty changelog is rejected.

## Quality standards

Themes submitted to the marketplace should meet these benchmarks:

- **Complete** — All required templates render without Liquid errors on empty and populated data.
- **Customizable** — Sensible defaults in `settings_data.json` presets; sections use schema settings instead of hard-coded copy where possible.
- **Accessible markup** — Semantic HTML, alt text on images, keyboard-friendly navigation.
- **Performance** — Optimized images, minimal render-blocking scripts, use `{% stylesheet %}` / `{% javascript %}` to avoid duplicates.
- **Documented** — `theme_documentation_url` points to setup and customization instructions.

## Review process

1. Develop and test locally with [Theme Development Kit](/apis-and-tools/theme-dev/overview).
2. Deploy to a test store and run through the [testing checklist](/build-with-finqu/liquid-themes/testing-previewing#testing-strategies).
3. Open the partner portal, fix any validation notifications.
4. Submit for publish or release an update with version + changelog.
5. Finqu reviews marketplace themes before they appear to merchants (timeline varies).

## Common rejection reasons

| Issue | Fix |
|-------|-----|
| Missing required template | Add the template file under `templates/` |
| Invalid `settings_schema.json` | Validate JSON; check setting types match [Settings](/build-with-finqu/liquid-themes/settings) |
| Theme not built | Deploy/compile so `public/` contains compiled assets |
| Empty changelog on update | Describe changes in the release form |
| Invalid version number | Use semver; do not reuse a published version |
| Broken demo URL | Ensure `theme_demo_url` is reachable |

## Post-submission updates

To ship fixes or features after your theme is live:

1. Make changes in your local theme repo.
2. Test with ThemeDev and on a staging store.
3. Bump the version (patch or minor for safe changes; major only when breaking).
4. Write a changelog entry.
5. Publish the update from the partner portal.

Merchants receive updates according to Finqu's theme update flow. Major version bumps may reset their customization presets — document breaking changes clearly in the changelog.

## Related articles

- [Theme Structure](/build-with-finqu/liquid-themes/theme-structure)
- [Testing & Previewing](/build-with-finqu/liquid-themes/testing-previewing)
- [Theme Development Kit](/apis-and-tools/theme-dev/overview)