> For the complete documentation index, see [llms.txt](https://merchant-help.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://merchant-help.violet.io/platform-guides/shopware.md).

# Shopware

This guide is intended for Shopware 6 merchants who are connecting their store to Violet. During this process, you will create an API Integration in your Shopware Administration, copy the generated credentials, and provide them to Violet through the Violet Connect onboarding tool. You will retain full control of the Integration and can modify or remove it at any time from within your Shopware Administration. *Total time for completion is around 5 minutes.*

## Prerequisites

* A Shopware 6 instance with Administration access.
* Permission to create Integrations in **Settings > System > Integrations**.
* At least one **Sales Channel** configured in your Shopware instance.

## Step 1: Create an Admin API Integration

Violet authenticates with your Shopware store using an **Admin API Integration**. This produces a pair of credentials that Violet uses to read your product catalog, pull orders, and register webhooks.

1. Sign in to your **Shopware Administration**.
2. Navigate to **Settings > System > Integrations**.
3. Click **Add integration**.
4. Enter a label for the integration (e.g., `Violet`).
5. Enable the **Administrator** toggle to grant full API access.
6. Click **Save**.

After saving, Shopware displays two credentials:

* **Access key ID** — begins with `SWIA`. This is the integration's public identifier.
* **Secret access key** — a long random string. This is only shown once at creation.

Copy both values and store them securely for the next steps.

{% hint style="warning" %}
**The Secret access key is only displayed once.** If you lose it, you will need to delete the integration and create a new one. The Access key ID can be viewed again at any time.
{% endhint %}

{% hint style="info" %}
**Why Administrator access?** Violet requires broad read access across your store's products, orders, customers, and sales channels, as well as the ability to register webhooks for real-time sync and update order payment states when processing orders through connected channels. The Administrator role grants all of these permissions in a single step and is the fastest way to get connected.
{% endhint %}

### Granular Permissions (Alternative to Administrator)

If your organization requires more limited access, you can disable the **Administrator** toggle and instead assign a custom ACL role with the following permissions:

| Permission           | Required | Why Violet Needs It                                                                           |
| -------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `sales_channel:read` | Yes      | Read sales channel configuration for shop profile                                             |
| `product:read`       | Yes      | Sync your product catalog to connected channels                                               |
| `order:read`         | Yes      | Pull orders for status synchronization                                                        |
| `order:update`       | Yes      | Update payment state after order placement (e.g., mark as paid)                               |
| `customer:read`      | Yes      | Read customer data associated with orders                                                     |
| `currency:read`      | Yes      | Resolve currency for product pricing and order submission                                     |
| `webhook:create`     | Yes      | Register webhooks for real-time product, order, and customer updates                          |
| `webhook:read`       | Yes      | Check for existing webhooks to avoid duplicates                                               |
| `system_config:read` | No       | Read shop name and contact email; if unavailable, Violet falls back to the sales channel name |

{% hint style="warning" %}
If any required permission is missing, Violet will report a permissions error during onboarding. You can update the ACL role at any time without recreating the integration.
{% endhint %}

## Step 2: Locate Your Sales Channel API Access Key (Optional)

If you want Violet to submit orders directly into your Shopware store (Direct Order Submission), you will also need the **Sales Channel API access key**. This is a separate credential from the Admin API Integration created in Step 1.

1. In your Shopware Administration, open the **Sales Channels** section from the left sidebar.
2. Select the sales channel you want to connect to Violet (e.g., your **Storefront**).
3. Scroll down to the **API access** section.
4. Copy the **API access key** — this value begins with `SWSC`.

{% hint style="info" %}
**This credential is optional.** If you skip it, Violet will still sync your products, orders, and shop data. However, Direct Order Submission (allowing connected channels to place orders into your store) will be unavailable until a Sales Channel API access key is provided. You can add it later by updating your credentials in Violet.
{% endhint %}

{% hint style="warning" %}
**Do not confuse the two keys.** The Admin API Integration credentials (Step 1) begin with `SWIA` and are found under **Settings > System > Integrations**. The Sales Channel API access key (Step 2) begins with `SWSC` and is found under **Sales Channels > \[Your Channel] > API access**. Pasting one into the wrong field will cause validation to fail.
{% endhint %}

## Step 3: Identify Your Sales Channel ID (Optional)

If your Shopware instance has multiple sales channels, you can specify which one Violet should use as the default for shop profile data (name, currency, language, country) and storefront URL resolution.

1. In your Shopware Administration, open the sales channel you want to connect.
2. The sales channel UUID can be found in the browser URL bar when viewing the channel (e.g., `https://your-shop.com/admin#/sw/sales/channel/detail/a1b2c3d4...`).
3. Copy this UUID value.

{% hint style="info" %}
If you leave the Sales Channel ID blank, Violet will automatically use the first available sales channel in your store. For most single-channel stores, you can skip this step.
{% endhint %}

## Step 4: Provide Credentials to Violet

1. In the Violet Connect onboarding tool, select **Shopware** as your platform.
2. Enter the following credentials:

| Field                                         | What to Enter                                           | Example                       |
| --------------------------------------------- | ------------------------------------------------------- | ----------------------------- |
| **Store URL**                                 | The base URL of your Shopware store                     | `https://my-shop.example.com` |
| **Access Key ID**                             | The Admin API Integration Access key ID from Step 1     | `SWIA...`                     |
| **Secret Access Key**                         | The Admin API Integration Secret access key from Step 1 | *(masked field)*              |
| **Sales Channel API Access Key** *(optional)* | The Sales Channel API access key from Step 2            | `SWSC...`                     |
| **Sales Channel ID** *(optional)*             | The sales channel UUID from Step 3                      | `a1b2c3d4-e5f6-...`           |

3. Click **Connect**. Violet will immediately validate your credentials by:
   * Connecting to your Shopware Admin API and exchanging the Access Key ID and Secret Access Key for an authentication token.
   * Confirming the integration has sufficient permissions by reading your sales channels.
   * Verifying the Sales Channel API access key resolves to an active sales channel (if provided).

If any step fails, you will see a specific error message. Common issues:

| Error                                             | What to Check                                                                                                                                                                                                                |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Admin API integration credentials were rejected" | The Access Key ID or Secret Access Key was copied incorrectly, or the integration was deleted. Verify the values under **Settings > System > Integrations**.                                                                 |
| "Integration lacks the required privileges"       | The integration does not have the Administrator role enabled. Edit the integration and enable the **Administrator** toggle, or assign a custom ACL role with the permissions listed in the Granular Permissions table above. |
| "Sales Channel API access key is invalid"         | The Sales Channel API access key does not resolve to an active sales channel. Verify the key under **Sales Channels > \[Your Channel] > API access**. Ensure you copied the `SWSC` key, not the `SWIA` key from Step 1.      |
| Invalid store URL error                           | The Store URL is unreachable. Verify the URL is correct and includes the protocol (e.g., `https://`). Do not include `/api` or `/store-api` at the end.                                                                      |

Upon success you will be redirected back to the channel who first sent you to Violet.

***

## Credential Summary

| Credential                   | Required | Where to Find                                             | Example                          |
| ---------------------------- | -------- | --------------------------------------------------------- | -------------------------------- |
| Store URL                    | Yes      | Your Shopware store's base URL                            | `https://my-shop.example.com`    |
| Access Key ID                | Yes      | Settings > System > Integrations > \[Your Integration]    | `SWIA...`                        |
| Secret Access Key            | Yes      | Settings > System > Integrations (shown once at creation) | *(not displayed after creation)* |
| Sales Channel API Access Key | No       | Sales Channels > \[Your Channel] > API access             | `SWSC...`                        |
| Sales Channel ID             | No       | Sales channel UUID from the browser URL bar               | `a1b2c3d4-e5f6-...`              |

***

## How Violet Uses Your Credentials

Violet uses two sets of credentials to interact with your Shopware store:

* **Admin API credentials** (Access Key ID + Secret Access Key) are exchanged for a short-lived authentication token via OAuth2. This token is used to:
  * **Read your product catalog** (products, variants, pricing, media, categories) to make your items available for purchase through connected channels.
  * **Read orders** to keep order status synchronized between Shopware and Violet.
  * **Update order payment states** when payments are collected through connected channels.
  * **Register webhooks** so that Violet is notified in real time when products, orders, or customers change.
  * **Read shop configuration** (shop name, email, sales channel settings) to build your merchant profile.
* **Sales Channel API access key** (optional) is used to:
  * **Submit orders** (Direct Order Submission) by creating a guest checkout through the Shopware Store API when a customer purchases through a connected channel.

Your credentials are stored securely and encrypted at rest. They are never exposed to channels or end customers. The Admin API token is automatically refreshed and never stored long-term — only the Access Key ID and Secret Access Key are retained.

***

## Special Considerations

### Credential Lifecycle

The Admin API Integration credentials (Access Key ID and Secret Access Key) do not expire. They remain valid until you delete the integration in your Shopware Administration. The short-lived OAuth tokens minted from these credentials expire automatically and are refreshed by Violet as needed.

If you need to rotate your credentials:

1. Create a new integration in **Settings > System > Integrations**.
2. Update the credentials in Violet (contact support or re-run the onboarding flow).
3. Delete the old integration in Shopware.

### Revoking Access

To revoke Violet's access to your Shopware store at any time:

1. Sign in to your **Shopware Administration**.
2. Navigate to **Settings > System > Integrations**.
3. Locate the integration you created for Violet.
4. Click **Delete**.

Once deleted, all subsequent Violet API calls to your store will fail. Create a new integration and provide the new credentials to Violet to restore the connection.

### Multiple Sales Channels

If your Shopware instance has multiple sales channels, you can connect a specific one by providing its Sales Channel ID during onboarding. The shop profile (name, currency, language, country) will be sourced from that channel.

To connect multiple sales channels separately, complete the onboarding process once per channel, providing a different Sales Channel ID and Sales Channel API access key each time.

### Webhooks

After a successful connection, Violet will automatically register webhooks with your Shopware instance to receive real-time notifications for product, order, and customer events. You do not need to configure webhooks manually.

You can view the registered webhooks in your Shopware Administration under **Settings > System > Integrations** or via the Admin API.

### Direct Order Submission

Direct Order Submission (DOS) allows connected channels to place orders directly into your Shopware store. It requires the Sales Channel API access key (Step 2). Without it, Violet operates in read-only mode — products and orders are synced, but new orders cannot be submitted into Shopware.

{% hint style="info" %}
**Double opt-in guest registration:** If your Shopware store has double opt-in enabled for guest registrations, Direct Order Submission will not work. This is a Shopware configuration that requires email confirmation before a guest account is activated. Contact your Shopware administrator to disable double opt-in for guest accounts if you want to use DOS.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://merchant-help.violet.io/platform-guides/shopware.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.