---
title: System Configurations | Shopware Community Hub
description: >-
  Learn how to configure and manage system configurations in Shopware using the
  Admin API or static configuration files.
canonical_url: 'https://hub.shopware.com/learn/unit/system-configurations'
---

# System Configurations

<LearningObjectives>

- Understand how to configure system configurations via API.
- Recognize how to set system configurations statically.

</LearningObjectives>

# System Configurations

System configurations in Shopware define how the system behaves and how it interacts with the user. They are used to configure various aspects of the system, such as the **appearance of the storefront**, the **behavior of the administration**, and the **performance of the system** without changing the code.

In practice, system configurations act as a bridge between **flexibility** and **control**. You can change them dynamically through the **administration** or **Admin-API**, or define them **statically** to ensure consistent behavior across environments. As a developer, understanding system configurations allows you to adapt Shopware's behavior quickly without touching the codebase.

To explore all system configurations directly, run the following query in your database:

```sql
SELECT * FROM system_config;
```

This table includes both **core settings** and **plugin configurations** – for example, the SwagPaypal flag (`SwagPayPal.settings.sandbox`).

## Real-World Example

Imagine you have a Shopware shop, and you want to **disable the "Buy" button in the product listing** since your products are quite complex, and you want the customer to check out the product detail page.

You can do this by setting the system configuration `core.listing.allowBuyInListing` to `false`. This way, the **"Buy" button will not be displayed in the product listing**, and customers will have to click on the product to see the details and buy it.

![img](assets/add-to-cart-from-listing.jpg)

### Admin Settings

You can find the setting in the administration panel under `Settings > Shop > Products` (`https://YOUR_SHOP_DOMAIN/admin#/sw/settings/listing/index`).

It is a simple toggle and can be `true` or `false`. Per default, it is set to `true`.

![img](assets/buy-button-in-product-listing-enabled.jpg)

## Admin API

You can also configure system settings via the Admin API. In practice, you can use two different approaches.

### Via POST Request

Use this variant when you already know the exact configuration key that you want to update.

```http
POST /api/_action/system-config
Content-Type: application/json

{
  "core.listing.allowBuyInListing": false
}
```

### Via PATCH Request

You can also update a system configuration via `PATCH` if you already know the ID of the matching `system_config` entity (in this example, the ID of the system config for `core.listing.allowBuyInListing`).

This variant is a bit more technical because it works with the entity ID instead of the configuration key: [Update system configuration](https://shopware.stoplight.io/docs/admin-api/d4f8fb961b4c1-partially-update-information-about-a-system-config-resource)

```http
PATCH /api/system-config/<system-config-id>
Content-Type: application/json

{
  "configurationValue": false
}
```

<Callout title="Finding the `system_config` ID" type="info">

If you want to use the `PATCH` variant, you first need the ID of the matching `system_config` entity. You can get it from the database in the format expected by the API with this query:

```sql
SELECT LOWER(HEX(id)) AS id
FROM system_config
WHERE configuration_key = 'core.listing.allowBuyInListing';
```

</Callout>

This endpoint is different from the POST endpoint `/api/_action/system-config`. The `POST` example above updates a configuration by key, while this `PATCH` example updates an existing `system_config` entity by ID.

If you do not need to work with a specific `system_config` entity, the `POST` variant is usually the simpler option.

## Static System Configuration via `.env` or Config YAML

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

This feature is available since Shopware 6.6.4.0.

</Callout>

You can also set the `core.listing.allowBuyInListing` setting **statically** via the `.env` file or the `config/packages/shopware.yaml` file. Static configuration is ideal when:

- You manage **multiple environments** (e.g., dev, staging, prod).
- You want **version control** for key settings.
- You want to **prevent accidental changes** from the administration.

```yaml
shopware:
  system_config:
    default:
      core.listing.allowBuyInListing: true
    # Disable it for the specific sales channel
    0188da12724970b9b4a708298259b171:
      core.listing.allowBuyInListing: false
```

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

Static configuration has a higher priority over changes made via the administration. If a value is defined in **`shopware.yaml`**, it cannot be changed from the administration.

</Callout>

For all possible options and more information, check out the [official documentation](https://developer.shopware.com/docs/guides/hosting/configurations/shopware/static-system-config.html#static-system-configuration).

### Using Environment Variables in Static System Configuration

You may notice examples in the documentation where system configuration values are referenced from `.env` variables.

Shopware does **not** automatically derive environment variable names from the configuration key.

When using `.env` values inside `config/packages/shopware.yaml`, you are simply using **Symfony's standard** `env()` **processor**, for example:

```yaml
shopware:
  system_config:
    default:
      core.listing.allowBuyInListing: '%env(bool:ALLOW_BUY_IN_LISTING)%'
```

In this example:

- `ALLOW_BUY_IN_LISTING` is **not generated by Shopware**.
- It is **not** derived from `core.listing.allowBuyInListing`.
- It is simply a **custom environment variable name** that you choose yourself.

You can define any environment variable name you want. What matters is:

- The **system configuration key** must be correct, e.g., `core.listing.allowBuyInListing`.
- The **referenced env variable name** must match what you have defined in your `.env` file.

Example:

```yaml
shopware:
  system_config:
    default:
      core.listing.allowBuyInListing: '%env(bool:DISABLE_BUY_IN_LISTING)%'
```

Then your `.env` file must contain:

```dotenv
DISABLE_BUY_IN_LISTING=true
```

This means:

- Static system configuration always lives in `config/packages/shopware.yaml`.
- `.env` variables are optional and only used when you explicitly reference them using `%env()%`.

## Summary

In this learning unit, you have learned:

- What **system configurations** are and how they influence the Shopware instance.
- How to **find configurations** directly in the database (`system_config` table).
- How to **update system configurations** using the **administration panel** or the **Admin API**.
- How to **set configurations statically** via the `.env` file or the `config/packages/shopware.yaml` file.
- When and why to prefer **static configuration** (e.g., versioning, preventing admin overrides).
- That the `core.listing.allowBuyInListing` setting controls the visibility of the "Buy" button in the product listings.

With this knowledge, you can confidently manage system behavior in Shopware; either dynamically via API or statically for stable, environment-specific setups.