---
title: Introduction to Custom Entities | Shopware Community Hub
description: >-
  Learn what Custom Entities are, why they exist, and when to use them to extend
  the Shopware data model in your App.
canonical_url: 'https://hub.shopware.com/learn/unit/introduction-to-custom-entities'
---

# Introduction to Custom Entities

<LearningObjectives>

- **Understand** what **Custom Entities** are and their role in Shopware Apps.
- Identify **when to use Custom Entities** versus other data storage approaches.
- Recognize the **benefits** and **limitations** of **Custom Entities** in App development.

</LearningObjectives>

# Introduction to Custom Entities

In this learning unit, you will learn the concept of **Custom Entities** in Shopware Apps. Before diving into the technical implementation, it's crucial to understand what Custom Entities are, why they exist, and when you should use them in your App development.

## What Are Custom Entities?

Shopware stores most of its data in the database, for example, products, customers, orders, categories, and much more. Each of these data types is managed as an **entity** in Shopware's data model.

Sometimes, you will need to store **additional or business-specific data** that doesn't fit into these standard entities, for example, product configurations that are unique to your App, or create new types of products like seasonal special products.

That's where **Custom Entities** come in. A **Custom Entity** is a data structure defined by your App that tells Shopware, "create a new table in the database for me; I will use it to store my own data." Shopware handles the rest automatically:

- It creates and updates the database schema.
- Makes your entity available via the Store API and Admin API.
- Ensures your data integrates smoothly with the rest of the system.

In short: Custom Entities let your App **extend Shopware's data model** without touching the core code or writing any PHP migrations.

### Key Characteristics

Custom Entities in Shopware Apps have several important qualities:

| Quality                           | Characteristic                                                                                                                                                |
|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Simple Definition**             | You define your entity in an XML file instead of writing PHP code. Shopware automatically reads this file and creates the necessary database fields.          |
| **Automatic Database Management** | When you install or update your App, Shopware manages the corresponding database tables for you – no migrations needed.                                       |
| **Ready-to-use API Access**       | Once your entity exists, it is instantly available through the **Store API** and **Admin API**, so you manage your data from anywhere.                        |
| **Global Naming, No Auto Scope**  | Custom Entity names are **global within a Shopware installation**. **They are not scoped per App**, so you must ensure unique names to avoid conflicts.       |
| **Prefix Requirement**            | Custom Entity table names must start with the `custom_entity_` prefix (or with the short prefix `ce_`). This keeps database table names short and consistent. |

<Callout title="Avoid Naming Conflicts" type="warning">

Custom Entities are **not app-scoped**. To avoid naming conflicts between Apps, choose **unique, namespaced names** for your Custom Entities.

A simple structure is: `custom_entity_<app_name>_<entity_name>`. To make the name fully unique, you can also add a vendor prefix: `custom_entity_<vendorname>_<app_name>_<entity_name>`.

Assume in this example that the vendor is **shopware AG**.

**Recommended examples:**

- `ce_storetracker_dispatch_note`
- `ce_swag_storetracker_dispatch_note`
- `custom_entity_storetracker_dispatch_note`
- `custom_entity_swag_storetracker_dispatch_note`

**Problematic example:**

- `ce_dispatch_note`

</Callout>

## Why Use Custom Entities?

Custom Entities make it easy to extend Shopware's data model with your own types of data, without touching the core or writing migrations. They are ideal whenever your App needs to store structured information that doesn't fix the default entities like **products** or **orders**.

**Typical examples include:**

- **Physical Store Locations:** Manage real-world shops and their opening hours.
- **Product Reviews and Ratings**: Add structured rating and feedback fields.
- **Customer Preferences:** Store user-specific behavior or loyalty data.
- **Inventory Extensions:** Track special stock data.

You see, there are a lot of scenarios where Custom Entities can be useful.

### Simple Setup, No Migrations, Automatic API Integration

Instead of writing PHP classes and migrations, you define your entity in a `entities.xml` file. Shopware automatically reads this file and knows which fields to create.

```xml
<!-- Simple XML definition -->
<entity name="ce_physical_shop">
    <fields>
        <string name="name" store-api-aware="true" />
        <json name="address" store-api-aware="true" />
        <bool name="open_to_public" default="true" />
    </fields>
</entity>
```

Once defined, Custom Entities are immediately available through:

- **Store API**: For storefront applications
- **Admin API**: For administrative interfaces

### **Relationships with Other Entities**

Custom Entities can also be connected to Shopware core entities. For example, a product review entity can reference both a product and a customer:

```xml
<entity name="ce_product_review">
    <fields>
        <string name="title" store-api-aware="true" />
        <text name="content" store-api-aware="true" />
        <many-to-one name="product" entity="product" store-api-aware="true" />
        <many-to-one name="customer" entity="customer" store-api-aware="true" />
    </fields>
</entity>
```

## When And When Not to Use Custom Entities

Custom Entities are great for most simple data needs, but not every App requires them.

**Use them when:**

- You need to store **structured data** that doesn't exist in Shopware core entities.
- You want **automatic API access** without writing controllers.
- You need **simple data models** without complex business logic.
- You want to **extend existing entities** with additional information.

**Avoid them when:**

- You want to **modify existing Shopware entities** directly (use plugins instead).
- You need **high-performance queries** or advanced indexing.
- You need **complex business logic**.

For deeper core integration or complex logic, you should consider using plugins.

## Summary

Custom Entities let your App extend Shopware's data model without complex migrations or backend logic. They offer:

- **Simple, declarative data modeling** via XML configuration
- **Automatic database management** and **API integration**
- **Seamless integration** with other App features

Knowing when to use them helps you design scalable, maintainable Apps that fit naturally into the Shopware ecosystem.

In the next learning unit, you will define your first Custom Entity in the `entities.xml` file and see how Shopware automatically creates the required database tables.