ShipStation Integration

The Middleware Platform integrates with ShipStation (a multi-carrier shipping management platform) to ingest real-time order and shipment data. This data powers the Shipping Dashboard and provides a local record of all fulfilment activity.

Architecture

ShipStation
     │  ORDER_NOTIFY / SHIP_NOTIFY webhook
     ▼
POST /api/webhooks/shipstation/order-notify
POST /api/webhooks/shipstation/ship-notify
     │
     ▼
ShipStationWebhookController
     │
     ▼
ShipStationService::fetchFromUrl()  ← calls ShipStation REST API
     │
     ▼
Eloquent upsert into shipstation_orders + shipstation_order_items + shipstation_shipments

Webhook Events

ShipStation sends two event types to the middleware:

ORDER_NOTIFY

Triggered when an order is created or updated in ShipStation.

Endpoint: POST /api/webhooks/shipstation/order-notify

The controller:

Validates that resource_url and resource_type are present in the payload.
Calls ShipStationService::fetchFromUrl($resourceUrl) to retrieve the full order detail from ShipStation's REST API.
Iterates over each order in the response and upserts a ShipStationOrder record.
Upserts all ShipStationOrderItem records for the order.

SHIP_NOTIFY

Triggered when a shipment is created for an order.

Endpoint: POST /api/webhooks/shipstation/ship-notify

The controller upserts a ShipStationShipment record including tracking information.

Data Models

`ShipStationOrder`

Column	Description
`order_id`	ShipStation's internal order ID (unique key)
`order_number`	Human-readable order number (matches WooCommerce order number)
`order_date`	When the order was placed
`order_status`	ShipStation order status
`ship_date`	Actual ship date
`shipby_date`	Committed ship-by date
`amount_paid`	Total amount paid
`shipping_amount`	Shipping charge
`carrier_code`	Carrier (e.g., `fedex`, `ups`)
`service_code`	Service level (e.g., `fedex_ground`)
`weight`	Order weight in ounces
`raw_data`	Full JSON payload from ShipStation (archived for debugging)

`ShipStationOrderItem`

Column	Description
`order_id`	FK to `shipstation_orders.order_id`
`sku`	Product SKU
`name`	Product name
`quantity`	Quantity ordered
`unit_price`	Unit price at time of order

`ShipStationShipment`

Column	Description
`shipment_id`	ShipStation's internal shipment ID
`order_id`	FK to `shipstation_orders.order_id`
`tracking_number`	Carrier tracking number
`carrier_code`	Carrier used
`ship_date`	Actual ship date
`raw_data`	Full JSON payload

Configuration

Set ShipStation API credentials in .env:

SHIPSTATION_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SHIPSTATION_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

In ShipStation, configure webhooks to point to the middleware:

Event	URL
Order Notify	`https://dash.scottsdalemint.com/api/webhooks/shipstation/order-notify`
Ship Notify	`https://dash.scottsdalemint.com/api/webhooks/shipstation/ship-notify`

Key Files

File	Description
`app/Http/Controllers/ShipStationWebhookController.php`	Webhook handler
`app/Services/ShipStationService.php`	REST API client
`app/Models/ShipStationOrder.php`	Order model
`app/Models/ShipStationOrderItem.php`	Order item model
`app/Models/ShipStationShipment.php`	Shipment model

Architecture​

Webhook Events​

ORDER_NOTIFY​

SHIP_NOTIFY​

Data Models​

ShipStationOrder​

ShipStationOrderItem​

ShipStationShipment​

Configuration​

Key Files​