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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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-...

1. 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.

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.