Shopware Integration Setup

This guide walks through connecting a Shopware 6.6.5.0 and higher instance to Order Fox for importing products/customers and exporting orders.

Note: The theoretical minimum version is Shopware 6.3.5.0 (when the Integration & ACL system was stabilised), but this has not been tested. Only Shopware 6.6.5.0 and above are verified.

1. Shopware Integration Credentials

Request or create an integration in Shopware Admin under Settings > System > Integrations to obtain a Client ID (Access Key ID) and Client Secret (Secret Access Key).

An Administrator integration is preferred. If this is not possible, enable the following permissions in the integration's ACL grid:

Section	Row	View	Edit	Create	Delete
Catalogues	Products	x
Catalogues	Properties	x
Customers	Customers	x	x
Orders	Orders	x	x	x
Other	Sales Channels	x

No additional permissions are needed — the Orders "Create" role already includes api_proxy_switch-customer internally.

---

2. Create an OAuth Integration

Create an integration of type OAuth with the following settings:

Field	Value
Label	Shopware
Webservice URL	Your Shopware domain, e.g. https://shopware.example.com (no /api suffix)
Token URL	Full OAuth token endpoint, e.g. https://shopware.example.com/api/oauth/token
Client ID	Your Shopware Integration Access Key ID
Client Secret	Your Shopware Integration Secret Access Key
Scope	(leave empty)

The webservice URL must be the base domain only (up to the TLD). The token URL must include the full /api/oauth/token path.

---

3. Import Profiles

Import profiles pull data from Shopware into Order Fox. Each profile targets a specific Shopware API search endpoint.

Products

Create an import profile with the following configuration:

Field	Value
Name	Products
Integration	The Shopware OAuth integration created above
Reference data	The reference data set where products should be imported

Config parameters:

Parameter	Value
Path	/api/search/product
Transformer	shopware_products
Request Method	Post
Data Wrapper	data
Page Parameter	page
Page Start Index	1
Page Step Size	1
Page Size Parameter	limit
Page Size Length	10

Additional Headers:

{
    "Accept": "application/json",
    "sw-inheritance": "true"
}

Additional Parameters (request body):

{
    "includes": {
        "product": [
            "id", "productNumber", "name", "parentId",
            "price", "stock", "ean", "options", "translated"
        ]
    },
    "associations": {
        "options": {
            "associations": {
                "group": {}
            }
        }
    },
    "filter": [
        {
            "type": "equals",
            "field": "active",
            "value": true
        },
        {
            "type": "multi",
            "operator": "or",
            "queries": [
                {
                    "type": "not",
                    "operator": "and",
                    "queries": [
                        { "type": "equals", "field": "parentId", "value": null }
                    ]
                },
                {
                    "type": "equals",
                    "field": "childCount",
                    "value": 0
                }
            ]
        }
    ]
}

The filter ensures only active products are imported, and excludes parent products that have variants (only the variants themselves are returned).

Customers

Create an import profile with the following configuration:

Field	Value
Name	Customers
Integration	The Shopware OAuth integration created above
Reference data	The reference data set where customers should be imported

Config parameters:

Parameter	Value
Path	/api/search/customer
Transformer	shopware_customers
Request Method	Post
Data Wrapper	data
Page Parameter	page
Page Start Index	1
Page Step Size	1
Page Size Parameter	limit
Page Size Length	10

Additional Headers:

{
    "Accept": "application/json",
    "sw-inheritance": "true"
}

Additional Parameters (request body):

{
    "includes": {
        "customer": [
            "id", "customerNumber", "firstName", "lastName",
            "email", "company", "defaultBillingAddress",
            "defaultShippingAddress", "vatIds"
        ]
    },
    "associations": {
        "defaultBillingAddress": {
            "associations": {
                "country": {}
            }
        },
        "defaultShippingAddress": {
            "associations": {
                "country": {}
            }
        }
    }
}

Mapping

After creating each import profile, configure the field mapping to match the imported Shopware fields to your tenant's asset type attributes. The mapping is tenant-specific and must be configured per installation.

---

4. Export Profile (Orders)

To export orders back to Shopware, create an export profile with the Shopware provider.

Field	Value
Name	A descriptive name for the export
Integration	The Shopware OAuth integration created above
Provider	shopware
Path	/

Template:

The template uses Twig syntax and maps Order Fox order data to the Shopware order creation API format. Replace the salesChannelId with your Shopware Sales Channel ID. The fields on the parties and lines objects depend on your field mapping configuration, so adjust the template accordingly if you have mapped different fields.

{
    "salesChannelId": "<your-sales-channel-id>",
    "customerId": "{{ buyer_customer_party.external_id }}",
    "billingAddressId": "{{ accounting_customer_party.account_id }}",
    "shippingAddressId": "{{ buyer_customer_party.account_id }}",
    "items": [
        {% for line in lines %}
        {
            "productId": "{{ line.item.external_id }}",
            "quantity": {{ line.quantity }}
        }{% if not loop.last %},{% endif %}
        {% endfor %}
    ]
}

Template variable mapping:

Variable	Maps to
buyer_customer_party.external_id	customerId from the customers import
accounting_customer_party.account_id	Billing addressId from the customers import
buyer_customer_party.account_id	Shipping addressId from the customers import
line.item.external_id	productId from the products import

Setting the provider to shopware routes the export through the dedicated Shopware export handler, which handles authentication and API communication automatically.