---
title: App Configurations | Shopware Community Hub
description: >-
  Learn how to add configuration fields to your Shopware App to make it more
  flexible, reusable, and customizable.
canonical_url: 'https://hub.shopware.com/learn/unit/app-configurations'
---

# App Configurations

<LearningObjectives>

- Know where to define App configurations.
- Understand the basic structure and file format used for App configurations.

</LearningObjectives>

# App Configurations

In this learning unit, you will learn how to **add app configurations** to your Shopware App. App configurations allow you to **predefine values** or **load default data** during installation. This can save time and reduce manual setup steps.

## Real-World Example

Imagine you are developing a **shipping provider app**. Adding the shipping methods with a plugin can be cumbersome – you need to add the shipping methods manually in the Shopware administration. To make this process easier, you can add a configuration file to your App that contains the shipping methods. This way, the user can easily select the predefined shipping methods directly in the Shopware administration.

## Add the `manifest.xml` File to Your App

Every Shopware App starts with a **`manifest.xml`** file. This file defines the app's metadata, permissions, and configuration setup. It is located in the **root directory** of your App.

The basic `manifest.xml` 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-2.0.xsd">
    <meta>
        <name>ShippingApp</name>
        <label>Shipping App</label>
        <description>This app adds 2 new shipping methods</description>
        <author>shopware AG</author>
        <copyright>(c) shopware AG</copyright>
        <version>1.0.0</version>
        <license>MIT</license>
    </meta>
</manifest>
```

For an in-depth explanation of the manifest.xml file, please refer to the [official Shopware documentation](https://developer.shopware.com/docs/guides/plugins/apps/).

In this learning unit, we will not cover the entire `manifest.xml` file, but focus specifically on the **configuration section**.

## Shipping Methods

Shopware Apps support predefined XML tags such as `shipping-methods` and `shipping-method`. These tags allow you to **define new shipping methods directly in the App's manifest.xml file** without writing additional code.

This is particularly useful for **shipping provider apps**, as they often need to register custom shipping methods during installation.

Here is how you can add shipping methods to the app configuration:

```xml
<shipping-methods>

    <shipping-method>
        <!-- The identifier should not change after the first release -->
        <identifier>FastShippingMethod</identifier>
        <name>Fast shipping method</name>

        <delivery-time>
            <!-- Requires a new generated UUID for your new delivery time -->
            <id>c8864e36a4d84bd4a16cc31b5953431b</id>
            <name>From 1 to 2 days</name>
            <min>1</min>
            <max>2</max>
            <unit>day</unit>
        </delivery-time>
    </shipping-method>

    <shipping-method>
        <!-- The identifier should not change after the first release -->
        <identifier>CargoShippingMethod</identifier>
        <name>Cargo shipping method</name>

        <delivery-time>
            <!-- Requires a new generated UUID for your new delivery time -->
            <id>46177c36a84b418b8ae1a22028aeb1c5</id>
            <name>From 1 to 2 weeks</name>
            <min>1</min>
            <max>2</max>
            <unit>week</unit>
        </delivery-time>
    </shipping-method>

</shipping-methods>
```

<Callout title="Identifier" type="warning">

Avoid changing the **`identifier`** after the App is released. If you do so, Shopware will treat it as a new shipping method and create a duplicate entry, which you will have to remove manually.

</Callout>

Great, we added two shipping methods that can be selected in the Shopware administration. This will make the process of adding shipping methods easier for the user.

For a complete list of all available tags within shipping methods, please refer to the [official Shopware documentation](https://developer.shopware.com/docs/guides/plugins/apps/shipping-methods.html).

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

Besides shipping methods, you can also define **[payment providers](https://developer.shopware.com/docs/guides/plugins/apps/payment.html)** and **[tax providers](https://developer.shopware.com/docs/guides/plugins/apps/tax-provider.html)** via the `manifest.xml` file.

</Callout>

## CLI Commands

After adding or changing configurations in your App, you need to **refresh the App**, so Shopware can re-read the updated `manifest.xml` file. It is done in **two steps**:

**Step 1:** You have to increase the version number manually in the `manifest.xml` file. Only then Shopware detects the change and re-reads the file. For example, update the version number from `1.0.0` to `1.0.1`.

Before:

```xml
<version>1.0.0</version>
```

After:

```xml
<version>1.0.1</version>
```

**Step 2:** Now refresh your App using the following command in your shop's directory:

```bash
bin/console app:refresh
```

This command updates the App's configuration and re-registers any changes defined in the `manifest.xml` file in the database.

Here is a list of all **App-related CLI commands** available in Shopware:

```bash
Available commands for the "app" namespace:
  app:activate            Activates an app
  app:create              Creates an app skeleton
  app:deactivate          Deactivates an app
  app:install             Installs an app
  app:refresh             [app:update] Refreshes an app
  app:uninstall           Uninstalls an app
  app:update              Refreshes an app
  app:url-change:resolve  Resolves app url changes
  app:validate            Validates an app
```

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

Before refreshing your App, you can run the **`bin/console app:validate`** command to check if your **`manifest.xml`** file is valid. This helps you catch syntax or schema errors early.

</Callout>

## Summary

In this learning unit, you have learned:

- That the **`manifest.xml`** file contains the configuration section.
- How to **add shipping methods** to the configuration.
- Why you must **increase the version number** before refreshing the App.
- How to **refresh the app** after making configuration changes.
- That adding shipping methods via **Shopware Apps** is easier than doing it in a plugin.

With this knowledge, you have a solid overview of how to add App configurations which fundamentally differ from plugins.