Download the PHP package solution25/ship-hero-integration without Composer

ShipHero Integration for Shopware 6

Introduction

The ShipHero Integration Plugin creates a real-time, bidirectional sync between your Shopware 6 store and ShipHero — a cloud-based warehouse management and fulfillment platform. Once connected, your products, orders, and inventory levels are kept in sync automatically across both systems via webhooks and a queue-based message bus, with no manual intervention required during normal operation.

The plugin handles the full fulfillment lifecycle: pushing paid orders to ShipHero, updating delivery and tracking information back into Shopware when ShipHero ships them, keeping stock levels accurate in real time via inventory webhooks, and syncing your product catalog to ShipHero when products are created or updated in Shopware. It also includes preorder state management, a continuous inventory backfill safety net, an Admin log viewer, and a full suite of CLI commands for operations, debugging, and recovery.

Key Features

Bidirectional Order Sync

• Paid Shopware orders are automatically pushed to ShipHero when the order transaction reaches the configured trigger state (default: paid).
• When ShipHero ships an order, the plugin receives the webhook, updates the delivery tracking codes, and transitions the Shopware delivery to the shipped state.
• Order cancellations and line item changes in ShipHero are also reflected back into Shopware via webhook processing.

Real-Time Inventory Sync (ShipHero → Shopware)

• ShipHero inventory webhook events are received and applied to Shopware product stock levels in real time.
• Inventory updates are filtered by the configured Warehouse ID so only stock from the correct warehouse is applied.
• Digital products are automatically excluded from inventory sync via a custom field flag (is_digital_item).

Continuous Inventory Backfill

• An optional scheduled backfill task continuously pulls the full warehouse inventory from ShipHero via paginated GraphQL queries and corrects any drift in Shopware stock levels.
• Acts as a safety net for missed or delayed webhook events.
• Configurable page size (1–200 rows per request) and can be enabled/disabled independently.

Product Sync (Shopware → ShipHero)

• Products created or updated in Shopware are automatically pushed to ShipHero when product sync is enabled.
• Supports standalone products, parent products with variants, and variant products — each classified and synced appropriately.
• A full product sync can be triggered on demand from the Admin config toggle, processing all products in configurable batches.
• Create-only mode available for initial backfill: creates missing products in ShipHero without updating existing ones — significantly faster for large catalogs.
• Product images, tags, dimensions, and names are all included in the sync payload.
• Configurable options to control whether empty image lists or empty tag lists clear the corresponding fields in ShipHero.

Webhook Registration & Verification

• Webhooks for inventory updates, inventory changes, product updates, shipment updates, and order line events are registered automatically with ShipHero via GraphQL.
• All incoming webhook payloads are verified using HMAC-SHA256 signature validation against the configured webhook secret.
• Webhook deduplication prevents the same event from being processed more than once.
• A webhook inbox stores incoming events for processing; a separate inventory inbox handles high-volume inventory events.

Preorder Support

• Orders containing preorder line items are automatically placed into a dedicated Preorder order state in Shopware.
• A scheduled task runs every 5 minutes to reconcile preorders — detecting when all preorder items have been fulfilled or shipped and transitioning the order state accordingly.
• Preorder state transitions are guarded against locked or completed delivery states to prevent invalid transitions.

Admin Log Viewer

• A dedicated ShipHero Logs section in the Shopware Admin displays daily log files from the plugin.
• Logs can be browsed by date directly from the Admin without server access.

GraphQL Client with Rate Limiting

• All ShipHero API calls use a dedicated GraphQL client with built-in rate limit awareness (up to 6,800 requests per 5-minute window), automatic retry with backoff on throttle responses (up to 5 attempts), and request latency tracking.
• Supports both Bearer token and Basic auth (API Key + Secret) authentication methods.
• Access tokens are refreshed automatically using the configured refresh token.

Queue-Based Async Processing

• All sync operations (order sync, product sync, inventory sync) are dispatched as Symfony Messenger messages and processed asynchronously via the message bus — keeping webhook responses fast and decoupled from the sync logic.

CLI Commands

The plugin ships a full suite of console commands for operations, recovery, and debugging:

Compatibility

• ✅ Shopware 6.6.x
• ✅ PHP 8.1+
• ✅ Requires Symfony Messenger with an async transport (e.g. RabbitMQ, Redis, Doctrine)

Get Started

Installation & Activation

GitHub

1. Clone the plugin into your Shopware plugins directory:

2. Install the Plugin in Shopware 6

   • Log in to your Shopware 6 Administration panel.
   • Navigate to Extensions > My Extensions.
   • Locate the plugin and click Install.

3. Activate the Plugin

   • After installation, click Activate to enable the plugin.
   • Run the following commands from your Shopware root:

4. Build Administration Assets

5. Verify Installation

   • After activation, you will see ShipHero Integration in the list of installed plugins.
6. Verify API Connectivity

Plugin Configuration

After installing the plugin, configure your ShipHero credentials and sync preferences through the Shopware Administration panel.

Accessing the Configuration

1. Go to Settings > System > Plugins > ShipHero Integration > Configure
2. Set the following fields:

API Credentials

Webhook Settings

Sync Toggles

Order Mapping

How It Works

1. Order Created in Shopware → Pushed to ShipHero

When a Shopware order transaction reaches the configured trigger state (default: paid), the plugin enqueues a SyncOrderByNumberMessage. The message handler builds the full ShipHero order payload — including line items, shipping address, and billing details — and creates the order in ShipHero via GraphQL. The ShipHero order ID is stored on the Shopware order as a custom field.

2. ShipHero Ships the Order → Shopware Updated

When ShipHero ships the order, it sends an order webhook to your store. The webhook processor parses the event, matches it to the Shopware order by order number, updates the delivery tracking codes, and transitions the Shopware delivery state to shipped.

3. Inventory Updated in ShipHero → Shopware Stock Corrected

When inventory changes in ShipHero, an inventory webhook is dispatched to Shopware. The plugin filters the payload by your configured warehouse ID and updates the corresponding Shopware product stock levels. Digital products (flagged via a custom field) are automatically skipped.

4. Product Updated in Shopware → Pushed to ShipHero

When a product, its price, translation, tags, or images are updated in Shopware and product sync is enabled, the plugin enqueues a SyncProductBySkuMessage. The message handler classifies the product (standalone, variant, or parent with variants) and pushes the appropriate payload to ShipHero, including dimensions, images, tags, and name.

5. Webhook Registration

On first use (or when re-run via CLI), the plugin registers all required webhooks with ShipHero via the GraphQL API. Webhook IDs and shared secrets are stored in Shopware system config for subsequent signature verification.

6. Preorder Reconciliation

Orders with preorder line items are automatically placed in a Preorder state. A scheduled task runs every 5 minutes to check whether preorder items have been allocated or shipped in ShipHero and transitions the order out of the preorder state when ready.

Admin Sections Added by This Plugin

Uninstallation

License

MIT — see LICENSE for details.

Support

For questions or issues, please open a GitHub Issue or contact Solution25.