---
title: Designing Custom Entities | Shopware Community Hub
description: >-
  Learn more on how to introduce custom entities for persisting project-specific
  data
canonical_url: >-
  https://hub.shopware.com/learn/unit/solutions-architect-designing-custom-entities
---

# Designing Custom Entities

<LearningObjectives>

- Learn how to create **custom entities** to extend Shopware functionality.
- Understand how custom entities **integrate** with Shopware’s existing database structure.
- Identify **best practices and options** for storing additional data on core entities, like products and orders.

</LearningObjectives>

# Designing Custom Entities

Shopware offers several ways to store additional data on core entities such as **product** and **order**. Choosing the best approach depends on the type of data, its frequency of use, and whether it needs to be compatible with other systems or accessible via Shopware’s API.

## Storing Additional Data on Product and Order Entities

Shopware supports three main methods for adding extra data to core entities, each with unique benefits:

### 1. Custom Fields

<img src="../../assets/images/custom-fields-overview.png" width="550"/>

Custom fields are a straightforward way to extend existing entities like `product` or `order` without creating entirely new database tables. They are useful for simple data points that don’t require complex relationships with other data.

- **Use Cases**: Adding custom labels, additional specifications for products, order notes, or simple tracking data.
- **Management**: Custom fields can be created and managed in the **Shopware Admin** interface under Settings > Custom Fields.
- **API Access**: Custom fields are accessible via Shopware’s API, making them easy to read or update through integrations.

**Example**:
For a product requiring additional attributes, you could create custom fields for `material_type`, `warranty_period`, and `usage_guidelines`, which will appear directly within the product configuration in the Shopware Admin.

<img src="../../assets/images/custom-fields-product.png" width="550"/>

**Best Practices**:

- Use custom fields for simple, non-relational data points.
- Group related custom fields together into sets for better organization.
- Avoid using custom fields for data that requires complex relationships, as this may impact performance.

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

Since Shopware 6.7.0.0, custom field names and field set names must be valid Twig variable names. This means **hyphens (-)** and **dots (.)** are no longer allowed.
Existing custom fields will continue to work. The validation only enforced when creating new custom fields.

</Callout>

### 2. Associating Custom Entities

For more complex data that involves relationships or needs to support additional functionality, creating a **custom entity** is the best approach. Custom entities are standalone data structures that can link back to core entities like `product` or `order`.

- **Use Cases**: Adding data with relationships, such as custom product specifications, detailed order tracking history, or metadata tied to specific products or customer groups.
- **Management**: Custom entities can be created through apps, using Shopware’s **Custom Entity** framework to define fields, relationships, and data types.
- **API Access**: Custom entities are fully accessible through the API, making them suitable for integrations requiring detailed data.

**Example**:
A `product_warranty` custom entity can be created to manage different warranty details for each product, or introduce one-to-many relationships, linking back to the `product` entity. This custom entity could include fields like `warranty_duration`, `warranty_provider`, and `terms_url`.

**Best Practices**:

- Use custom entities for data that involves complex relationships or frequently changes.
- Ensure that custom entities have well-documented field definitions and naming conventions.
- Add an admin interface to edit data, or offer access only via API, depending on project needs.

Read more: [Add custom complex data](https://developer.shopware.com/docs/guides/plugins/plugins/framework/data-handling/add-custom-complex-data.html).

### 3. Extensions via Plugins

For cases where you need more bespoke integration or custom logic, extending core entities through extensions can be a more flexible solution.

- **Use Cases**: Adding business-specific logic, like advanced calculations, custom workflows, or data handling requiring custom processing within Shopware.
- **Implementation**: Extensions via plugins can define additional fields, database tables, or methods and integrate them directly with core entities.

**Example**:
An extension might extend the `order` entity to include complex fee handling fields or custom calculations based on order totals and item-specific fees.

**Best Practices**:

- Reserve extensions for advanced requirements where standard approaches (custom fields or custom entities) are insufficient.
- Document all modifications thoroughly to support long-term maintenance.
- Be mindful when interfacing with the core, using only public APIs, to maintain compatibility with future updates.