ShipFusion

At a glance

What is ShipFusion for FluentCart?

It is a WordPress plugin that makes ShipFusion — a third-party fulfillment warehouse — the shipping and inventory backend of a FluentCart store. Paid orders are handed to the warehouse automatically. Shipment tracking and stock levels come back. The FluentCart order status follows the package rather than guessing at it.

Nothing needs a human in the loop. The work runs on WP-Cron, with webhooks for the events that should not wait for the next tick, and the pieces that can fail are built to fail loudly and recover on their own.

The three flows

• Orders out. The moment FluentCart marks an order paid, a ShipFusion shipment is built and sent.
• Tracking back. Carrier, service, tracking number and delivery state land on the order, and the customer gets FluentCart’s own shipped and delivered emails.
• Stock back. The warehouse count is written to your FluentCart variations, so the store cannot sell what the warehouse cannot pack.

How an order leaves your store

Payment is the trigger. There is no queue to watch and no button to press.

Only what should ship, ships

• Digital, service and subscription line items are stripped out of the payload. A digital-only order never reaches the warehouse at all.
• Only paid orders sitting in processing or completed qualify.
• An activation floor — both a timestamp and an order-ID watermark — means installing on an established store never sweeps years of historical orders into physical fulfillment. Backfilling is deliberate, through a filter.

Building the payload

• The address is validated before it is sent, against ShipFusion’s required fields: name, address, city, postal code, country, state for US, CA, AU, MX, BR and IN, plus phone and email. FluentCart does not keep phone and email on the shipping address, so both fall back to the billing address and then the customer record.
• SKUs resolve three ways — from the line item, from the variation, or from a direct lookup of the variation ID across both the sku and variation_identifier columns.
• Bundles go out as their own SKU so ShipFusion’s Group product rules expand them at the warehouse. A filter flips that to explode the bundle into component lines instead. Duplicate SKUs across lines are merged.
• The shipping method the shopper paid for is honoured. Checkout methods map to a ShipFusion carrier and service through a filter, so an expedited order ships expedited. A final filter lets you adjust the whole payload before it goes.

When a push fails

Shipment creation is never auto-retried blindly, because a retry is how a store ends up paying to ship the same box twice.

• Every failure is recorded with the error text and an attempt count, and shown on the admin order screen.
• Retries back off thirty minutes. After five attempts the order is parked rather than left to churn.
• Orders that can never succeed — no shipping address, a missing SKU, digital-only — are parked immediately with the reason.
• A parked order is released from WP-CLI with --force once the underlying problem is fixed.
• Per-order locks stop two processes pushing the same order at the same time.

How tracking comes back

Two mechanisms, on purpose. Webhooks carry the events that should be instant; polling is the safety net for everything a webhook can drop.

Polling, in two phases

• A bulk shipment listing covers the last thirty days in a single call.
• Anything missing, or needing package-level detail such as per-parcel tracking or a delivery state, gets an individual fetch.
• The schedule is yours, from every fifteen minutes to once a day.
• A forty-five-day post-ship window keeps an order polled until delivery is actually observed, newest first, so a large backlog cannot starve today’s shipments.

Webhooks, for the moments that matter

A REST endpoint handles shipment_shipped, orderShipment, shipment_backOrder, shipment_onHold and lowInventory, plus acknowledgements for warehouse receipts and returns. It reads the documented tracking payload, and falls back to an API lookup when the webhook arrives thin.

The status lifecycle

The plugin registers a custom shipped status with FluentCart, so an order in transit is not misfiled as complete.

• Multi-package orders complete only when every package is delivered.
• Delivery Incomplete and Returned to Sender never auto-complete. Those need a person.
• Status only moves forward. A delivered or completed order can never be knocked back to shipped by a re-poll, a forced re-sync or a late webhook, so no customer gets a second shipped email.
• Webhook and cron are serialized per order, so two events arriving together cannot interleave.
• Lagging warehouse statuses are tolerated. ShipFusion sometimes marks items shipped, or issues tracking, before it flips the shipment status. All items shipped, or real tracking existing, is treated as shipped.

What lands on the order

Carrier, service, tracking number, ship date, live tracking status and a tracking URL — taken from ShipFusion when it supplies one, otherwise built per carrier for UPS, FedEx, USPS, DHL, Canada Post and Purolator. It renders as a card in the FluentCart order detail sidebar, is injected into the order REST response, and is written into the order’s Activity tab.

Shipments created in ShipFusion outside the plugin are reconciled back to FluentCart orders by order number, so a manual warehouse entry does not become an orphan.

Stock, with the warehouse as the source of truth

On a schedule or on demand, warehouse quantities are pulled and written to FluentCart variations: total stock, available stock, and the stock status recalculated from them.

Matching a warehouse SKU to a FluentCart variation

• The catalogue loads over REST, with a direct-database fallback when REST is unavailable.
• Both sku and variation_identifier are indexed, and column existence is checked so an older FluentCart install does not fatal.
• SKUs whose quantity has not changed are skipped without a write.

Bundles are derived, not guessed

FluentCart bundle products do not appear in ShipFusion’s inventory feed — the warehouse holds components. After the component pass, each bundle’s stock is computed as the smallest component available divided by quantity in the bundle, so a bundle can never sell what the warehouse cannot pack. A bundle whose SKU ShipFusion does report keeps the warehouse number. A bundle with an unknown child is skipped, never zeroed.

Safe by default

• A missing or non-numeric quantity skips the SKU rather than writing a zero and taking a product off sale.
• Variations with stock management switched off are left alone, and are never switched on.
• A FluentCart write failure counts as an error, so a run where nothing actually wrote cannot report success.
• A lowInventory webhook triggers a single-SKU refresh rather than a full sweep.

What happens when an order changes

Hold-orders mode

FluentCart auto-completes paid orders by default, which makes completed mean paid rather than delivered. Turn hold-orders mode on and ShipFusion-managed orders stay at processing until the warehouse actually ships. Manual admin completions are respected, and orders the plugin does not manage are left alone entirely.

Cancelled and refunded orders are never revived by a late warehouse event.

Built for the person running the store

Settings live inside FluentCart, not in a separate world. The plugin appears on FluentCart’s Plugin Addons card and as a nav item, and in FluentHub’s combined menu when FluentHub is present, with a standalone page as the fallback.

What you configure

• ShipFusion username and password, encrypted at rest.
• Warehouse: Illinois, Las Vegas, Pennsylvania or Toronto.
• API URL, https only.
• Per-job intervals, an auto-push toggle, a hold-orders toggle, and an address for failure alerts.

One-click actions

• Test connection, before anything else is trusted.
• Sync inventory, with a dry run that shows what would change without changing it.
• Push orders, Pull shipments and Force re-pull.
• Generate webhook secret, masked, with Show and Copy.
• Every action reports counts plus per-SKU and per-order detail, and takes the same lock as the cron job, so a click can never overlap a scheduled run.

On the order itself

• A tracking widget in the order detail sidebar, including failed and parked push state with the reason spelled out.
• An activity log entry for every change the plugin makes: shipped, delivered, status changes, warehouse cancellations.

Built to run unattended

• Every job is lock-guarded. Inventory sync, shipment pull and order push each take an atomic, object-cache-aware lock with a heartbeat refresh for long runs.
• Failures are told to you. After three consecutive failures of any job you get an email, with a one-hour cooldown and a counter that resets on success.
• A circuit breaker sits in the API client. After three consecutive hard failures the run fails fast instead of burning worker time, with exponential backoff and Retry-After support on rate limits.
• Logs are private. They go to a salted, access-protected directory under uploads, kept thirty days, with customer PII redacted unless debug logging is deliberately switched on.
• There is a CLI. wp fluentcart shipfusion covers test-connection, sync-inventory, push-orders, pull-shipments and status, and guards against pushing an unpaid or cancelled order.
• Uninstall is clean. The sync table, every option and transient, and the log directory are removed, per site on multisite.

The warehouse is treated as untrusted input

A webhook endpoint that moves order status and stock is worth attacking, so it is built as though someone will.

• Webhooks are verified by HMAC-SHA256 with seven-day replay protection. A legacy plaintext auth code is accepted only until the first signed webhook arrives, then disables itself.
• Every secret is encrypted with AES-256-GCM — the ShipFusion password, the webhook secret, the update token. Salt rotation is detected and surfaced as an admin notice rather than failing silently.
• Admin actions are nonce- and capability-checked, every database query is prepared, and all output is escaped.
• Tracking links render only for http and https URLs.
• No raw webhook payloads or customer data are stored in wp_options.

Updates and extension points

• Hands-off auto-updates from a private GitHub repository using a stored fine-grained token, pinnable to a tag or a branch.
• Filters for the push floor, the retry policy, the poll windows, the required address fields, shipping-method mapping, bundle behaviour, payload customization and log retention.
• Actions fired on shipped, status change, fulfilled, inventory updated and cancel-failed, so other plugins and automations can react.
• Complete generated API references for both ShipFusion and FluentCart ship with the repository, refreshed weekly by CI.

Planned pricing

Annual pricing, to be confirmed at launch. The plugin keeps working when a license lapses; updates and support pause until it is renewed.

Requirements

• WordPress 6.0+, PHP 7.4+, FluentCart required and active
• A ShipFusion account with API access, and at least one of the four warehouses
• WP-Cron running, or a real system cron pointed at it
• A publicly reachable REST endpoint if you want webhooks; polling alone also works

Known limits, stated plainly

• ShipFusion is the source of truth for stock. If you also edit quantities by hand in FluentCart, the next sync will overwrite them.
• Shipment creation is never auto-retried. That is deliberate — the cost of a duplicate physical shipment is higher than the cost of a parked order — but it does mean a parked order waits for a person.
• A bundle with an unknown component is skipped, not zeroed. Its stock will look stale until the component appears in the warehouse feed.
• Delivery Incomplete and Returned to Sender do not auto-complete an order and never will.
• Warehouse-side edits are reconciled by order number. A shipment created at ShipFusion with a different reference cannot be matched back.