---
title: API Integration Principles | Shopware Community Hub
description: >-
  Dive into Shopware’s API architecture, exploring Storefront and Admin APIs,
  authentication methods, and best practices for building robust integrations
  with…
canonical_url: >-
  https://hub.shopware.com/learn/unit/solutions-architect-api-integration-principles
---

# API Integration Principles

<LearningObjectives>

- Understand Shopware's **API structure** and how it supports integrations with external systems.
- Differentiate between the **Storefront API and Admin API** and their respective roles in Shopware integrations.

</LearningObjectives>

# API Integration Principles

Integrating Shopware with third-party systems is a common requirement in today's ecommerce projects. Whether it concerns an ERP application or fetching catalog data from a third-party catalog search, much of a webshop's data lives outside of Shopware. The Admin API and Storefront API are essential for backend and public data interactions, respectively, while webhooks and the event-driven Flowbuilder enable real-time data exchange without constant polling. Middleware and IPaaS add flexibility and scalability for businesses needing complex integrations, especially when connecting multiple systems.

For Solutions Architects, understanding the role of each integration method helps in recommending the most effective, scalable approach tailored to business needs.
Shopware is designed with an API-first approach, meaning that virtually all features and data within the platform can be accessed or manipulated via API. This enables seamless integrations with external systems like ERPs, CRMs, and PIMs, helping businesses manage their data and operations efficiently.

## API Structure

Shopware has two main types of APIs: the Storefront API and the Admin API. Both use RESTful principles, allowing external systems to interact with Shopware’s data in a structured way.

### Storefront API

The Storefront API is designed for public-facing data and handles information required for customer interactions. This includes accessing product details, categories, and customer-related data that powers the online shop.
The Storefront API does not require authentication. However, it will require an `sw-access-key` to identify the intended Sales Channel. You can find the correct access key within your admin panel's sales channel configuration in a section labeled API Access.  

<img src="../../assets/images/api-access.png"/>  

The `sw-context-token` is used as a session identifier to which a user's cart is tied, as well as data acquired after a user logs in.

Use Cases: Shopware Frontends uses the Storefront API to populate the frontend with data.

More on the Storefront API can be found on the [Shopware Stoplight](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) site.

### Admin API

The Admin API is the primary API for backend integrations, such as those with ERPs, CRMs, and PIMs. It supports full CRUD (Create, Read, Update, Delete) operations, making it ideal for entity-based data management.

Authentication is offered via an OAuth 2.0 integration, which ensures granular access control per user.

#### Writing Data to the Shopware Admin API

The Shopware Admin API simplifies creating, updating, and deleting entities while maintaining data consistency. Payloads are sent in JSON format to RESTful endpoints and must adhere to a strict schema. Validation returns errors for missing or invalid fields.
When creating or updating entities, a UUID serves as the primary key. This comes with benefits such as generating IDs client-side (opposed to Auto Increment IDs), and a small likelihood of ID collisions. However, Shopware ensures that the UUID format is correct, but it does not check whether the UUID is already used or valid in a business sense.

**Associations** allow developers to manage relationships between entities directly within payloads. For example, a product can be assigned to categories during creation, reducing the need for additional API requests.

**Bulk operations** optimize performance by enabling multiple write operations to be sent in a single request through the Sync API. A Sync request is executed transactionally: if a write operation inside the request fails with an exception, the request is rolled back and no data from that request is written. Bulk imports are useful for tasks like mass product updates, inventory adjustments, or ERP synchronization, but integrations should validate payloads carefully and use smaller batches when they need to isolate problematic records.

Use Cases: Typical use cases include syncing inventory with an ERP, updating product details from a PIM, or creating customer records in a CRM.

More on this in this article: [Admin API Guide](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide).

## Best Practices

Use the Admin API for Back Office Integrations: Reserve the Admin API for complex back-office integrations, which require secure access to internal data.
Optimize Requests to Avoid Throttling: Avoid large requests and frequent polling. Instead, use event-driven patterns or webhooks where possible to minimize API load.