Connecting ShipStation

Alpha Insights can sync shipping costs from ShipStation with your WooCommerce orders. Once configured and enabled, a daily sync runs automatically for the last 7 days of shipments, and you can run a one-time bulk sync to backfill historical data. Synced costs are saved to orders and as expenses for accurate profit reporting.

What the integration does

• Syncs shipping costs from ShipStation to WooCommerce orders by matching ShipStation orderNumber to your WooCommerce order number
• Runs a daily sync that fetches shipments from the past 7 days (paginated, 500 per page) and processes each shipment
• Optionally runs a bulk sync (all shipments, paginated) when you click Run bulk sync; if the API rate limit is hit, the current page is rescheduled and retried later
• Saves shipment cost + insurance cost to order meta (_wpd_ai_total_shipping_cost, _wpd_ai_shipstation_shipping_cost, and optionally _wpd_ai_shipstation_shipment_id)
• Creates an expense for each synced order (reference: ShipStation – {order_id}), categorized as Shipping; expense date comes from ShipStation createDate (UTC converted to your site timezone) or the order date
• Recalculates order profit after each successful sync

Requirements

• Alpha Insights Pro with ShipStation integration available
• WooCommerce with orders (order numbers can be default or custom, e.g. Sequential Order Numbers)
• ShipStation API Key and API Secret from your ShipStation account
• Action Scheduler (included with WooCommerce) for daily and bulk sync

Settings

Go to Alpha Insights → Settings and open the Integrations tab. Find the ShipStation section.

Enable Integration

Turn on ShipStation sync. The integration only runs when this is checked and both API key and API secret are set.

API Key

The API key for your ShipStation account. Required when the integration is enabled. ShipStation uses Basic Authentication (API key as username, API secret as password).

API Secret

The API secret for your ShipStation account. Required when the integration is enabled.

Enable Logging

When enabled, API requests and sync activity are written to the ShipStation log file. Errors are always logged to the ShipStation error log regardless of this setting.

ShipStation Sync Data section

• Next Scheduled Sync – When the next daily sync will run. The daily schedule fetches shipments for the past 7 days.
• Sync stats – Number of orders with synced shipping cost and number of expenses created from ShipStation syncs.
• Bulk Sync – Button to run a full sync of all shipments. Only shown when the integration is enabled. Runs in the background; if rate limited, pages are rescheduled automatically.
• Delete sync data – Removes all ShipStation data: shipping cost meta from orders and all expenses with reference starting with ShipStation – . Use with care.

How to set up

1. Obtain your API Key and API Secret from ShipStation (Account → API Settings or similar).
2. In WordPress, go to Alpha Insights → Settings → Integrations.
3. Check Enable ShipStation integration.
4. Enter the API Key and API Secret.
5. Optionally enable Enable ShipStation logging for debugging.
6. Click Save changes. The daily sync is scheduled on the next run of Alpha Insights’ event scheduler. Use Run bulk sync if you want to backfill past shipments.

How the sync works

Daily sync

• Runs once per day.
• Fetches shipments from ShipStation with createDate in the last 7 days, sorted by create date descending, 500 per page.
• For each shipment, matches orderNumber to a WooCommerce order (by order number or _order_number meta).
• Adds shipmentCost and insuranceCost and saves the total to the order and creates (or skips if already exists) the ShipStation expense.

Bulk sync

• Triggered by the Run bulk sync button. Schedules page 1; each page run schedules the next page until no full page is returned.
• Fetches all shipments (no date filter), 500 per page. If the API returns 429 (rate limit), the same page is rescheduled in 90 seconds.
• Same matching and processing as daily sync: order number → order, then save cost and expense.

Order matching

ShipStation uses order number, not internal order ID. Alpha Insights finds the WooCommerce order by:

• If the order number is numeric, trying wc_get_order( order_number ) and confirming the order’s get_order_number() matches.
• Otherwise searching for an order with _order_number meta equal to the ShipStation order number (supports custom order number plugins).

Order meta and expenses

When a shipment is processed successfully:

• Order meta: _wpd_ai_total_shipping_cost, _wpd_ai_shipstation_shipping_cost, and _wpd_ai_shipstation_shipment_id (if present in the shipment).
• Expense: One expense per order with reference ShipStation – {order_id}, category Shipping, and date from ShipStation createDate (UTC → site timezone) or the order’s date paid/created.

Troubleshooting

Integration not running

• Ensure Enable Integration is checked and both API Key and API Secret are saved and non-empty.
• Check WooCommerce → Status → Scheduled Actions for wpd_ai_shipstation_sync_costs_with_orders (daily) and wpd_ai_shipstation_bulk_sync_page (bulk).
• Enable logging and check the ShipStation log and ShipStation error log at the bottom of the Integrations settings.

Orders not getting a shipping cost

• Confirm the order number in WooCommerce matches the orderNumber in ShipStation (check ShipStation order details).
• If you use a custom order number plugin, ensure the order number is stored in a way the integration can find (e.g. _order_number meta or that the numeric ID matches the displayed number).
• Ensure the shipment has shipmentCost and/or insuranceCost; the total must be greater than zero to be saved.

Rate limiting (429)

During bulk sync, if ShipStation returns 429, the current page is automatically rescheduled to run again in 90 seconds. No action needed; let the queue finish.

Removing ShipStation data

Use Delete sync data to remove all ShipStation shipping cost meta from orders and all expenses with reference ShipStation – . This does not remove the integration settings; you can run sync again after re-saving or re-enabling.