---
title: Understanding the Manifest File | Shopware Community Hub
description: >-
  Learn how the manifest.xml file defines your App’s identity, permissions, and
  integration points within the Shopware App System.
canonical_url: 'https://hub.shopware.com/learn/unit/the-manifest-file'
---

# Understanding the Manifest File

<LearningObjectives>

- **Understand** the role of the **`manifest.xml`** file in the Shopware App System.
- **Identify** and **describe** the **key elements** that define an **App's configuration**.
- **Validate** the **manifest file** correctly to **avoid** installation issues.
- **Learn** how to **increment** the App's version number.

</LearningObjectives>

# Understanding the Manifest File

In the Shopware App System, every App is defined by a `manifest.xml` file. This file acts as the **entry point and central configuration** for your App. It tells Shopware everything it needs to know to install, activate, and communicate with it.

You can think of the `manifest.xml` as the **contract between Shopware and your App**: it tells Shopware what your App can do and how it communicates.

## Base Structure Overview

A minimal `manifest.xml` file looks like this:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
  <meta>
    <name>AppName</name>
    <label>AppLabel</label>
    <label lang="de-DE">AppLabelInGerman</label>
    <description>App Description</description>
    <description lang="de-DE">App Description in German</description>
    <author>App Author</author>
    <copyright>(c) [year] [Your Company]</copyright>
    <license>[License (MIT, proprietary, etc.)]</license>
    <version>1.0.0</version>
  </meta>
  
  <setup>
    <!-- The URL which will be used for the registration -->
    <registrationUrl>https://my.example.com/registration</registrationUrl>
    <!-- Dev only, the secret that is used to sign the registration request -->
    <secret>[mysecret]</secret>
  </setup>
  
  <permissions>
    <read>product</read>
    <create>custom_entity</create>
    <update>custom_entity</update>
    <delete>custom_entity</delete>
  </permissions>
  
  <webhooks>
    <webhook name="product-changed" url="https://my.example.com/event/product-changed" event="product.written"/>
  </webhooks>
</manifest>
```

## Key Sections Explained

### The App Metadata: The meta Tag

The `meta` section defines the **basic identity** of your App and is required, while all other sections are optional. Below are the most important elements:

| Tag                        | Purpose                                                                                                                        |
|----------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| name                       | The unique technical name of your App, must match the folder name of your App.                                                 |
| label                      | The human-readable title that appears in the Shopware administration. You can include translations using the `lang` attribute. |
| description                | Short explanation of what your App does. Here you can also include translations using the `lang` attribute.                    |
| version                    | For [semantic versioning](https://semver.org/): `major.minor.patch`.                                                           |
| author, copyright, license | Legal and informational fields for attribution.                                                                                |

<Callout title="Best Practice for App Store Naming" type="info">

If you plan to publish your App in the Shopware Store, follow the naming conventions for technical App names (`name` tag). The name should include your **company prefix** to ensure global uniqueness. For example, `CompanyMyApp`. But **not** `MyApp` because this is too generic.

Feel free to check [this part](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide.html#name-your-app) of the official documentation.

</Callout>

<Callout title="More Tags" type="info">

There are a few more tags that you can use to further customize your App. For a full list, see the [official documentation](https://developer.shopware.com/docs/resources/references/app-reference/manifest-reference.html#meta-information-required).

</Callout>

### Registration and Security: The setup Tag

The `setup` section defines how Shopware connects to your App Server. This section is required when your App communicates with an external App Server.

| Tag                 | Purpose                                                                                                                                                                                                                              |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `registrationUrl`   | The **public URL** of your App Server. This URL is used to exchange the App's secret for a token that is used to authenticate the App Server. This URL is required for communication with the App Server.                            |
| `secret`            | The **shared secret** defined by your App Server. It is stored in the App Server configuration (e.g., in a `.env` file). It is used to sign the registration request. This secret is required for communication with the App Server. |

<Callout title="Note" type="info">

The `secret` value is **generated and owned by your App Server**, not by Shopware. It acts as a **shared key** that ensures both sides (Shopware and your App Server) can trust each other.

You should:

1. Define the secret in your App Server's configuration (for example, in a `.env` file).
2. Copy the exact same value into the `secret` tag in your App's `manifest.xml` file.

During installation, Shopware sends a signed registration request to the `registrationUrl`. Your App Server validates this request using the shared secret. If the values don't match, the registration will fail.

</Callout>

If your App does not include a backend server, you can skip the `setup` section.

### Data Access Rights: The permissions Tag

The [permissions](https://developer.shopware.com/docs/resources/references/app-reference/manifest-reference.html#permissions) section defines what data your App can access in the Shopware API. Shopware uses this to enforce strict data isolation.

| Tag      | Purpose                                 |
|----------|-----------------------------------------|
| `read`   | Defines which data your App can read.   |
| `create` | Defines which data your App can create. |
| `update` | Defines which data your App can update. |
| `delete` | Defines which data your App can delete. |

<Callout title="Additional Permission Types" type="info">

Since Shopware 6.4.12.0, you can also define **non-CRUD privileges** by using the `permission` tag

From Shopware 6.7.3.0 onward, you can simplify CRUD permissions by using the `crud` tag. Instead of listing each operation (create, read, update, delete) separately, you can define them all in one line.

</Callout>

### Event Notifications: The webhooks Tag

Webhooks allow your App to **react to Shopware events in real time**. Whenever a configured event occurs, Shopware sends an **HTTP POST request** to the specified `url`.
Within the `webhooks` tag, you can define as many `webhook` entries as you need, for example:

```xml
<webhooks>
    <webhook name="product-changed" url="https://my.example.com/event/product-changed" event="product.written"/>
    <webhook name="order-created" url="https://example.com/event/order-created" event="order.written"/>
    <webhook name="customer-created" url="https://example.com/event/customer-created" event="customer.written"/>
    <webhook name="mail-sent" url="https://example.com/event/mail-sent" event="mail.sent"/>
</webhooks>
```

Each `webhook` tag requires the following attribute:

- `name` – defines a unique identifier for your webhook within your App.
- `url` – defines the **target endpoint** that receives the HTTP POST request.
- `event` – defines the Shopware event that triggers the webhook.

You can also register **multiple webhooks for the same event**, for example, if you want to send identical event data to multiple destinations:

```xml
<webhooks>
    <webhook name="mail-sent" url="https://example.com/event/mail-sent" event="mail.sent"/>
    <webhook name="mail-sent-internal-metrics" url="https://my.example.com/event/internal-metrics" event="mail.sent"/>
</webhooks>
```

<Callout title="Webhook Event Reference" type="info">

For a full list of available events, see the [official documentation](https://developer.shopware.com/docs/resources/references/app-reference/webhook-events-reference.html).

</Callout>

#### Webhooks Live Version Only

In real-world scenarios, you may want to **filter events to include only live data** (e.g., finalized orders). To achieve this, you can use the [onlyLiveVersion attribute](https://developer.shopware.com/docs/guides/plugins/apps/webhook.html#webhooks-for-live-version-only).

The `onlyLiveVersion` attribute is a boolean value that is `false` by default. The examples above implicitly use this default value. If set to `true`, the webhook will only be triggered for **live versions** of the corresponding data.

```xml
<webhooks>
    <webhook name="order-created" url="https://example.com/event/order-created" event="order.written" onlyLiveVersion="true"/>
</webhooks>
```

### Custom Fields: The custom-fields Tag

The `custom-fields` tag allows you to define **custom fields** that your App can use to extend the Shopware data model. You can use these fields to store additional information for entities such as **products**, **orders**, **customers** and more or even your **own custom entities**.

Custom fields appear in the administration under the respective entity detail page. They are especially useful when your App needs to **extend** the existing Shopware entities **without modifying the core**.

Custom fields are defined in your App's `manifest.xml` file. Below is an example of a basic custom field set definition:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
  <meta>
    ...
  </meta>
  
  <custom-fields>
    <custom-field-set>
      <name>MyCustomFieldSetTechnicalName</name>
      <label>MyCustomFieldLabel</label>
      <label lang="de-DE">Label in German</label>
      <related-entities>
        <order/>
      </related-entities>
      <fields>
        <text name="MyTextFieldTechnicalName">
          <label>MyTextFieldLabel</label>
          <position>1</position>
          <required>false</required>
          <help-text>This is my help text to describe what this field stands for.</help-text>
        </text>
      </fields>
    </custom-field-set>
  </custom-fields>
</manifest>
```

You can see that each `custom-field-set` tag defines a **group of related fields.** Inside it, you can declare **meta-data**, the **related entities** and the **fields** that belong to the set:

- `name` – defines the unique technical name of the custom field set.
- `label` – defines the display label of the custom field set, translatable using the `lang` attribute.
- `related-entities` – defines the Shopware entities that the custom field set is related to (e.g., order, product, etc.).
- The `fields` tag defines the custom fields within the custom field set. You can define as many fields as you need with various types.

#### Supported Field Types

There are a few types for fields that you can use in your field definitions. These are:

- `text` - A **single-line text** input; ideal for short strings such as titles, notes, or identifiers.
- `float` - Stores **decimal numbers** (e.g., weights, measurements, percentages, etc.).
- `int` - Stores **whole numbers** (e.g., quantities, counter values, etc.).
- `text-area` - A **multi-line** text box for longer descriptions or comments.
- `bool` - A simple **true/false** toggle.
- `datetime` - A combined **date and time picker**, stored in **ISO-8601 format** (`YYYY-MMM-DDTHH:MM:SS+00:00`), equivalent to PHP's [DateTimeInterface](https://www.php.net/manual/en/class.datetimeinterface.php) constant.
- `single-select` - A **drop-down menu** where users can pick **one** predefined option.
- `multi-select` - A **list** where users can select **multiple** predefined options.
- `single-entity-select` - Lets users link **one** existing Shopware entity (e.g., product, category, etc. Even a custom entity.).
- `multi-entity-select` - Lets users link **multiple** entities.
- `color-picker` - Displays a **color-selector** that store **hex color codes** (e.g., `#FFFFFF`).
- `media` - Allows users to **upload** or **select** media files from the **Media Library**.
- `price` - Provides a structured price input that supports multiple currencies and tax configurations.

With these types, you can cover a wide range of business cases without touching the core.

### Administration Extension: The admin Tag

You can also extend the Shopware administration by defining **custom modules** or settings pages using the `admin` tag. This allows your App to integrate directly into the **Shopware administration UI**, for example, by adding navigation entries, creating custom configuration pages, or embedding dashboards.

The following example shows you how to define a custom module in the administration:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
        <module name="MyCustomMarketingModule"
                source="https://example.com/promotion/view/promotion-module"
                parent="sw-marketing"
                position="50"
        >
            <label>Awesome Marketing Module</label>
            <label lang="de-DE">Hervorragendes Marketing-Modul</label>
        </module>
    </admin>
</manifest>
```

The `admin` tag serves as the **root element** for defining your custom administration modules. Within it, you can declare one or more **modules** that integrate into the existing structure. As you can see, the module has some attributes:

- `name` – defines the unique technical name of your module.
- `source` – specifies the path or URL to your module's entry point.
- `parent` – defines the parent module in which your custom App module appears (e.g., `sw-marketing` for the marketing module, `sw-settings` for the settings module, etc.).
- `position` – determines the order in which the module appears in the navigation menu (lower = higher position).

After your App is installed, the module appears in the **Shopware administration sidebar** under the defined parent category. When the user clicks the module, Shopware loads your JavaScript module located under the specified `source` path.

This mechanism enables you to create highly interactive features directly inside the administration. Common use cases are:

- Adding a **custom configuration page** for your App.
- Providing an **analysis dashboard** or detailed report view.
- Embedding **data from your App server** via API requests.
- Extending or enhancing existing **Shopware administration modules**.

<Callout title="Note" type="info">

Custom administration modules defined in your App are **embedded via an `iframe`** inside the Shopware administration.

This means that the module is **loaded from the URL defined in the `source` attribute** of your manifest and runs in an isolated context. They do **not automatically inherit** the administration's style or JavaScript.

</Callout>

<Callout title="Further Reading" type="info">

If you want to dive deeper, feel free to check out the official documentation:

- [App Reference – Admin extension](https://developer.shopware.com/docs/guides/plugins/apps/administration/add-custom-modules.html)
- [Administration – Add custom module](https://developer.shopware.com/docs/guides/plugins/apps/administration/add-custom-modules.html)

</Callout>

### Further Possible Extensions

In addition to the sections covered in this learning unit, the `manifest.xml` file supports several other configuration options. Below is an overview of the missing sections:

- `shipping-methods` – define new shipping methods that integrate with your App
- `payment-methods` – define new payment methods that integrate with your App
- `rule-conditions` – introduce new rule conditions for the Rule Builder
- `tax` – register an external tax provider for complex tax setups
- `cookies` – define new cookies to the cookie consent manager
- `storefront` – configure the storefront template loading priority
- `allowed-hosts` – define which external domains your App is allowed to communicate with for security reasons

Each of these extensions follows its own structure and XML schema. Feel free to explore the [official documentation](https://developer.shopware.com/docs/resources/references/app-reference/manifest-reference.html) for further information.

## Validation and Versioning

Before you release or install your App, it's important to **validate** your `manifest.xml` file and **maintain a proper versioning strategy**. App Updates are a crucial process within App Development because they **perform essential database operations**, such as **creating custom entity tables**.

### Validation

Shopware validates the `manifest.xml` file during the installation process. If the file does not follow the official XML schema or contains missing or misplaced tags, the installation will fail.

To manually verify the manifest of your App, you can run the following command in your Shopware's root directory:

```bash
bin/console app:validate <MyExampleApp>
```

<Callout title="Validate All Apps" type="info">

If you want to validate all your Apps, you can run the following command:

```bash
bin/console app:validate
```

</Callout>

### Versioning Your App

Shopware Apps use **Semantic Versioning** (`major.minor.patch`) to determine the version of your App.

- **Major** (`1.0.0` -> `2.0.0`): Breaking changes, **not** backwards compatible with previous versions.
- **Minor** (`1.0.0` -> `1.1.0`): New features or improvements, backwards compatible with previous versions.
- **Patch** (`1.0.0` -> `1.0.1`): Bugfixes, hotfixes or small adjustments, backwards compatible with previous versions.

When performing an App Update, you first need to increment your App's version. Open your app's `manifest.xml` file and increase the version number. For small changes, increment the last digit (e.g., `1.0.0` -> `1.0.1`). Once done, save the file.

After that run the `app:update` command in your Shopware root directory:

```bash
bin/console app:update
```

If changes are detected, you will see a message like this:

```bash
 1 apps will be installed, 0 apps will be updated and 0 apps will be deleted.
Do you want to continue? (yes/no) [yes]:
```

Confirm with `yes` and wait for the command to finish.

If the version in the manifest is **lower or equal** to the version of the currently installed App, the update process will be **skipped**.

<Callout title="Force Parameter for Experienced Users" type="info">

The `app:refresh` command also supports the`--force` flag. When using `--force`, you will skip any confirmations required in the process of running the command.

</Callout>

#### Versioning Your App when Using the registrationUrl Tag

The `app:update` and `app:activate` commands may ask you for confirmations before you proceed. For example, if you have [configured a `<registrationUrl>` parameter](https://developer.shopware.com/docs/resources/references/app-reference/manifest-reference.html#setup) in your `manifest.xml` file, then you will see a prompt like this:

```bash
 !                                                                                                                      
 ! [CAUTION] The App "ShopwareStoreTracker" should be installed but requires communication with the following hosts:        
 !                                                                                                                      

 ----------- 
  Domain     
 ----------- 
  localhost  
 ----------- 

 Do you consent to sharing or transferring data to the domains listed above? (yes/no) [no]:
```

For this step to succeed, your App Server must be running and listening on the configured port at command runtime.

## Summary

In this learning unit, you learned that the `manifest.xml` file is the **heart of every Shopware App** and defines how the App integrates with Shopware. You now understand how to:

- Structure and validate the `manifest.xml` file correctly
- Configure essential sections like **meta**, **permissions**, **setup**, **webhook** and more
- Extend Shopware entities and the administration via **custom-fields** and **admin**
- Recognize additional extension points within the manifest (e.g., shipping methods, payment methods, etc.)

Excellent work! You have mastered the foundation that every App relies on, the manifest file.

In the next learning unit, you will be introduced to the **App Server** and learn how it fits into the App System.