Understanding GraphQL and REST APIs in Shopware

Shopware REST APIs explained

REST ( Representational State Transfer ) is a networked application architectural style. REST APIs are defined over HTTP, and common operations are defined using methods such as GET to read data, POST to write resources, PUT to update, and DELETE to delete. REST APIs in Shopware are designed according to two primary interfaces:

• Store API: The Store API is meant to be used in customer-facing interactions and is used to run frontend apps such as single-page apps (SPAs), mobile apps, or a custom storefront. It processes activities like search of products, cart and checkout.
• Admin API: The Admin API is designed to facilitate backend processes and can be used to perform administration tasks such as product, category, customer and order operations. It is perfect to connect to ERP systems, CRMs or custom dashboards.

Both APIs are REST-based with the JSON format being used to transfer data and standard HTTP status codes (e.g., 200 for success, 401 unauthorized) to communicated the result of a request. Detailed steps on how to use these APIs, authentication and sample requests are given in the following sections.

Configuring and Working with the Store API

The Store API acts as an entry point to the storefront of Shopware and allows developers to create exciting customer experiences. The following are the steps to authorize and submit requests to Store API.

Step 1: Take the sw-access-key

Authentication Against the Store API requires an sw-access-key, which is bound to a sales channel in Shopware. Just do the following:

1. Enter the Shopware administration panel with your admin credentials (default: username admin, password shopware on demo setups) at http://your-shop-url/admin .
2. In the left sidebar, go to Settings > Sales Channels.
3. Choose the preferred sales channel (e.g. “Storefront”).
4. Go to the settings of sales channels and find API access.
5. Note down the sw-access-key there.

Step 2: Swagger Authentication

Shopware offers a Swagger to discover and test Store API endpoints. To authenticate do the following:

1. Launch your browser and go to the following URL: http://your-shop-url/store-api/_info/swagger.html .
2. On the Swagger page, click on the Authorize button on the top right.
3. Copy and paste the sw-access-key into the given field and verify.
4. Your Swagger interface is now authenticated and you can test API endpoints.

Step 3: Sample Request to the Store API

After authentication, you are free to call the Store API. As an illustration, a request to get a list of products should be a GET request to /store-api/product . You can do it via a browser or a tool (such as Postman):

• With ModHeader Extension Browser:
  1. Get the ModHeader Chrome extension at the Chrome Web Store.
  2. Add a request header with key sw-access-key and the value of your copied key.
  3. Run GET at http://your-shop-url/store-api/product to view a JSON response with products data.
• Using cURL:
  curl -X GET https://your-shop-url/store-api/product \
-H "accesskey: yourswaccess_key" \
-H "Content-Type: application/json"

This query will result in a JSON output that contains an array of products containing their information such as names, prices and IDs.

Fetching Product Data – Example Use Case

Imagine that you wish to show products on a custom frontend. Product data is loaded by making a GET request to /store-api/product . The answer can be the following:

{
"elements": [
{
"id": "123456789",
"name": "Sample Product",
"price": { "gross": 19.99 },
"stock": 100
}
],
"total": 1
}

Configuring and Authenticating the Admin API

The Admin API is meant to be used in backend integrations and gives developers access to manage the core data of Shopware. It implements the secure authentication with OAuth 2.0.

Step 1 – Develop an Integration

You need to set up an integration in the Shopware admin panel in order to get API credentials to use Admin API:

1. Enter the Shopware back end.
2. Go to Settings > System > Integrations.
3. In the upper right corner, click Add integration.
4. Provide a name of the integration (e.g., “API Integration”).
5. Choose the permissions you need (e.g. have read/write access to products, customers).
6. Click on Save to obtain the Access Key ID and Secret Access Key.

Step 2: Get an Access Token

Get an OAuth 2.0 access token using the credentials of the integration. POST /api/oauth/token :

curl -d -X POST "http://your-shop-url/api/oauth/token" \
-H "Content-Type: application/json" -d '{
"grant_type": "client_credentials",
"client_id": "youraccesskeyid",
"client_secret": "yoursecretaccesskey"
}'

The reply contains an access token, which is good within 10 min:

{
"access_token": "youraccesstoken",
"expires_in": 600,
"token_type": "Bearer"
}

Step 3: Sample Request to the Admin API

Using the access token, you may make authenticated calls to the Admin API. E.g., to get a list of products, make a GET request to /api/product :

curl -X GET "http://your-shop-url/api/product" \
-H "Authorization: Bearer youraccesstoken" \
-H "Content-Type: application/json"

Use Case Example: Updating Stock of Products

To change the stock of a product, make a PATCH request to /api/product/{product_id} :

curl -X PATCH \
-H "Authorization: Bearer youraccesstoken" \
-H "Content-Type: application/json" \
-d '{ "stock": 150 }'

Shopware and GraphQL Integration: A Look at the Possibilities

GraphQL is a query language that enables clients to specify exactly the data they require, to minimise over-fetching and to be more efficient than REST. GraphQL, unlike REST which makes use of various endpoints, makes use of a single endpoint usually /graphql . Shopware however does not feature an official GraphQL API in June 2025. Rather, GraphQL functionality can be realized through community-driven projects such as SwagGraphQL.

What is SwagGraphQL?

SwagGraphQL is a proof-of-concept (POC) plugin by shopwareLabs to provide a GraphQL API on top of the core API of Shopware. It is based on the webonyx/graphql-php library to process GraphQL and is integrated into the framework of Shopware 6. It is however, not maintained anymore and was built for early releases of Shopware 6 and should not be used in production without major updates.

Installing SwagGraphQL

To play with SwagGraphQL, do the following:

1. Clone the SwagGraphQL repository into the custom/plugins folder of your Shopware installation:
   git clone -q -b main https://github.com/shopwareLabs/SwagGraphQL.git custom/plugins/SwagGraphQL
2. In the directory of the plugin, run dependencies:
   cd custom/plugins/SwagGraphQL
composer install
3. Go back to the Shopware root and run the following plugin installation command:
   cd ../../..
composer require swag-graphql/plugin
4. To activate the plugin:
   bin/console plugin:enable SwagGraphQL

Working with the GraphQL Endpoint

When installed, the GraphQL endpoint can be reached at http://your-shop-url/graphql/query . You may communicate with it through such tools as GraphiQL. An example GraphQL request to retrieve products can be as follows:

query {
products {
id
name
price
}
}

SwagGraphQL shortcomings

• It is designed on old Shopware 6 versions and might not be supported on newer ones such as 6.7.
• Completely supported data connections (nests) are not supported.
• The project is not maintained, which raises the chance of bugs or security problems.

Alternatives to GraphQL Solutions

The most prominent GraphQL project on Shopware is SwagGraphQL, but there can be other third-party integrations. Projects such as Alumio (Shopware & GraphQL Integration) provide a middleware to integrate Shopware with GraphQL-based systems. Nevertheless, those solutions usually need further setup and might fail to offer a native GraphQL API over Shopware core.

Shopware REST vs GraphQL comparing

Feature	REST (Shopware Store/Admin API)	GraphQL (through SwagGraphQL)
Official Support	Completely supported by Shopware	Unsupported, community driven
Endpoint Structure	Multiple endpoints (e.g., /store-api/product)	Single endpoint (/graphql/query)
Data Fetching	Set answer format, possible over-fetching	Accurate data retrieval, query defined by the clients
Authentication	sw-access-key (Store API), OAuth 2.0 (Admin API)	Plugin dependent
Production Readiness	Production ready and stable	POC, not intended to be used in production

Shopware API Integration Best Practices

• Secure Authentication: API keys and access tokens should be stored securely inside environment variables or a vault solution.
• Error Handling: Verify HTTP status codes and handle transient errors with retry logic.
• Rate Limiting: Observe Shopware rate limits to prevent throttling.
• Testing: Use Swagger or Postman to test requests before implementing.
• Version Compatibility: Ensure plugins (e.g., SwagGraphQL) match your Shopware version.

Common Troubleshooting Basic Problems

• 401 Unauthorized Error (Store API): Confirm the sw-access-key is valid and provided correctly.
• 401 Unauthorized Error (Admin API): Ensure the access token is valid and not expired.
• SwagGraphQL Installation Fails: Confirm Composer dependencies and Shopware compatibility.
• API Responses are slow: Minimize requested data and cache responses where possible.

Conclusion

The REST APIs provided by Shopware—the Store API and the Admin API—allow you to integrate and expand the platform’s functionality. While Shopware lacks an official GraphQL API, community initiatives like SwagGraphQL offer flexibility for experimental projects. By configuring APIs properly and following best practices, developers can unlock the full potential of the Shopware ecosystem for custom frontends, CRM syncs, and beyond.