README

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:

Command	Description
`shiphero:ping`	Verify API connectivity and list configured warehouses
`shiphero:sync:orders-from-date`	Re-sync Shopware orders from a given date
`shiphero:sync:sku`	Sync a single SKU to ShipHero
`shiphero:sync:inventory:full`	Run a full inventory pull from ShipHero
`shiphero:sync:products:all`	Enqueue a full product export to ShipHero
`shiphero:webhooks:ensure`	Register or re-register all ShipHero webhooks
`shiphero:webhooks:list`	List currently registered ShipHero webhooks
`shiphero:webhooks:ensure-inventory`	Re-register inventory webhooks specifically
`shiphero:preorder:reconcile`	Manually trigger preorder reconciliation
`shiphero:preorder:force-shipped-done`	Force preorder orders to done after shipment
`shiphero:fulfill:shopware-shipped`	Fulfill Shopware-shipped orders in ShipHero
`shiphero:resync:address-holds`	Re-sync orders held due to address issues
`shiphero:debug:inventory`	Debug ShipHero inventory for a specific SKU
`shiphero:debug:inventory:all`	Debug full warehouse inventory
`shiphero:debug:schema:field`	Inspect a ShipHero GraphQL schema field
`shiphero:debug:schema:query`	Run a raw GraphQL debug query
`shiphero:debug:order-line-item-schema`	Inspect the ShipHero order line item schema

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

Clone the plugin into your Shopware plugins directory:

git clone https://github.com/solution25com/shiphero-integration-shopware-6-solution25.git custom/plugins/ShipHeroIntegration

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.
Activate the Plugin
- After installation, click Activate to enable the plugin.
- Run the following commands from your Shopware root:

bin/console plugin:refresh
bin/console plugin:install --activate ShipHeroIntegration
bin/console cache:clear

Build Administration Assets

bin/console bundle:dump
bin/build-administration.sh
bin/console cache:clear

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

bin/console shiphero:ping

Plugin Configuration

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

Accessing the Configuration

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

API Credentials

Field	Description
ShipHero GraphQL API URL	The ShipHero public API endpoint (e.g. `https://public-api.shiphero.com/graphql`)
Refresh Token	Used to automatically renew access tokens
Access Token (Bearer)	Preferred authentication method. Leave API Key/Secret empty if using this
API Key	Basic auth key — used only if Access Token is empty
API Secret	Basic auth secret — used only if Access Token is empty
Warehouse ID	Your ShipHero warehouse ID used to filter inventory updates to the correct warehouse
Customer Account ID	Your ShipHero customer account ID

Webhook Settings

Field	Description
Public Webhook Base URL	The public HTTPS base URL of your Shopware store (e.g. `https://store.example.com`). Used to auto-generate webhook endpoints
Inventory Webhook URL Override	Optional: override the full inventory webhook URL
Product Webhook URL Override	Optional: override the full product webhook URL
Order Webhook URL Override	Optional: override the full order webhook URL
Webhook Secret	Used to verify HMAC-SHA256 signatures on all incoming ShipHero webhook payloads

Sync Toggles

Field	Default	Description
Enable Product Sync	Off	Push product changes from Shopware to ShipHero automatically
Run Full Product Sync Now	Off	Toggle on to immediately enqueue a full product export to ShipHero
Product Sync Batch Size	100	Number of products per batch during full sync (1–500)
Send Empty Product Tags	Off	When on, products with no tags will clear ShipHero tags on update
Send Empty Product Images	Off	When on, products with no images will clear ShipHero images on update
Create-Only Product Sync	Off	Creates missing ShipHero products but skips updates for existing ones — use for initial backfill
Create-Only Strategy: Lookup Existing First	On	When in create-only mode: look up SKU before creating (best when most products already exist in ShipHero)
Enable Order Sync	On	Bidirectional order sync between Shopware and ShipHero
Enable Inventory Sync	On	Apply ShipHero inventory webhook events to Shopware stock
Enable Continuous Inventory Backfill	Off	Periodically pull and correct full warehouse inventory from ShipHero
Inventory Backfill Page Size	200	Rows per ShipHero request during backfill (1–200)

Order Mapping

Field	Default	Description
Order Create Trigger (transaction state)	`paid`	The Shopware transaction state that triggers order creation in ShipHero
Delivery Shipped State	`shipped`	Technical name of the Shopware delivery state used to mark orders as shipped
Order Cancelled State	`cancelled`	Technical name of the Shopware order state for cancellations
Apply tracking codes to first delivery	On	Attach ShipHero shipment tracking codes to the first order delivery in Shopware

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

Section	Location	Description
ShipHero Logs	Admin sidebar	Browse daily plugin log files by date directly from the Admin

Uninstallation

bin/console plugin:deactivate ShipHeroIntegration
bin/console plugin:uninstall ShipHeroIntegration
bin/console cache:clear

License

MIT — see LICENSE for details.

Support

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

solution25 / ship-hero-integration

Maintainers

Package info

Statistics

Security