# Shopware integration

> How the Maxmove Shopware plugin and the Shopware Cloud app connect a shop, quote delivery at checkout, sync orders, and report delivery status back.

Maxmove integrates with Shopware 6.7 in two distributions that share one Maxmove backend:

| | Maxmove Delivery (plugin) | Maxmove Delivery Cloud (app) |
| --- | --- | --- |
| For | Self-hosted and PaaS Shopware | Shopware Cloud |
| Type | PHP plugin, technical name `MaxmoveDelivery`, Composer package `maxmove/shopware-delivery` | Shopware App System app, `MaxmoveDeliveryCloud` |
| Requires | PHP 8.2, Shopware 6.7 (below 6.8) | Shopware 6.7 |
| Checkout price | Live price through the storefront pricing policy | Merchant price only: fixed or free delivery with a cost ceiling |
| Pickup choice | Earliest pickup and up to 4 delivery windows | One "Earliest" option |

For click-by-click setup of the plugin, see [Set up the Maxmove Shopware plugin](https://maxmove.com/en/help/business-api/shopware-maxmove-setup).

## How it connects

Neither distribution uses the public `/v1` API or `/v1` API keys. Both talk to a dedicated Shopware API at Maxmove, and their orders send no `/v1` webhook events. A shop can connect only one of the two.

### Plugin

**1. Connection code**

An admin of a Maxmove business workspace gets a single-use connection code that is valid for 15 minutes.

**2. Connect**

The merchant enters the code in the plugin. The plugin creates its own shop id, plugin token, and callback secret and registers them with Maxmove, together with a callback URL on the shop's origin. In production, the shop must use HTTPS.

**3. Activate**

The connection becomes active after the first **Save and activate** in the plugin's settings. From then on, the plugin authenticates with its plugin token as a bearer token.

Install it from the ZIP or with `bin/console plugin:install --activate MaxmoveDelivery`.

### Cloud app

The app registers through the standard Shopware app handshake. Its admin pages load from `connect.maxmove.com` inside the Shopware Administration. The connection stays pending until the merchant links it to a Maxmove business workspace. Requests from Shopware to Maxmove are signed with the shop secret (`shopware-shop-signature`).

## Checkout

**Plugin.** Maxmove quotes only after the shopper selects the Maxmove shipping method (technical name `maxmove_delivery`). It computes the delivery windows: the earliest pickup plus 2-hour slots within the store's opening hours and lead time, today for same-day and today and tomorrow for scheduled delivery, at most 4. Each window is a signed quote, and the shopper picks one on the confirm page. Headless storefronts can use the plugin's Store API routes.

The plugin sends no coordinates, weights, or dimensions; Maxmove geocodes the addresses. The plugin waits up to 3 seconds. Without a fresh quote, checkout is blocked with "Maxmove is currently unavailable. Choose another shipping method." Rule Builder rules on the shipping method are checked by Maxmove at quote time.

The shopper price comes from the pricing policy: live price with a percentage adjustment, fixed price, free delivery, or free delivery above a subtotal, with a maximum carrier cost. Fixed and free prices require a maximum carrier cost.

**Cloud app.** The app offers one "Earliest" option through the Shopware checkout gateway at the merchant's fixed or free price, with a cost ceiling (30.00 EUR by default). If Maxmove can't quote, the method is removed from checkout.

## Data flow

**1. Order event**

**Plugin:** on order placement and payment changes, the plugin writes an event to a durable local queue that Shopware's message consumer and a scheduled task drain every 60 seconds, with retries. **Cloud app:** Shopware sends `order.written` and paid-transaction webhooks.

**2. Import**

By default, Maxmove creates the delivery after payment. It re-quotes the route: the plugin's signed quote can be used for one order only, and the Cloud app requires the quoted price to match the order's shipping total.

**3. Delivery created**

One Shopware order becomes exactly one Maxmove delivery.

## Status sync

Maxmove reports each status change to the shop, in order per order, with up to 20 attempts and a backoff of up to 6 hours between them. The plugin receives signed callbacks; the Cloud app's shop is updated through the Shopware Admin API.

Callbacks to the plugin are signed in the `x-maxmove-signature` header: a hex HMAC-SHA256 of `{timestamp}.{body}` with the callback secret, valid for 300 seconds. These are not the `/v1` webhook events.

- The tracking URL is written to the order delivery's tracking codes.
- The order delivery moves to **shipped** when the courier accepts, picks up, or completes the delivery. The Cloud app skips the transition on acceptance.
- A cancelled delivery moves the order delivery to **cancelled**.
- The plugin also stores the delivery status in the order's custom field `maxmove_delivery_status`.

The merchant setting **Sync tracking** turns all of this on or off and is on by default. When it's off, Maxmove writes no tracking URL, delivery state, or status field into the Shopware order. Each order keeps the setting that applied when Maxmove quoted its delivery, so a change affects new orders, not deliveries already underway.

## Payment

The shopper pays the shop. Maxmove charges the business workspace's company card per delivery: it authorizes the amount when it imports the order, captures it after completion, and releases it if the delivery is cancelled before completion. If billing isn't ready, the order waits in Maxmove with a link to the billing setup in the dashboard.

## Cancellations

- Cancelling the order or its delivery in Shopware cancels the Maxmove delivery, unless the merchant turned off cancelling on source cancellation (on by default).
- With **Sync tracking** on, a delivery cancelled by Maxmove cancels the Shopware order delivery, not the order. Refunds are not synced.

## Limits and requirements

- A Maxmove business workspace with the Integrations and Payments modules, a company card ready for billing, a pickup location, and saved settings.
- Orders need a customer name, an email address, and a delivery phone number.
- A currency with two decimals.
- For the plugin, Shopware's message consumer and scheduled tasks must run.
- Extra services: stairs, fragile handling, pickup window, two-person delivery, and installation, either paid by the shopper and shown at checkout, or paid by the merchant and hidden.

---

Source: https://maxmove.com/en/developers/docs/integrations/shopware