## Connecting StarShipIt

Alpha Insights can sync shipping costs from StarShipIt with your WooCommerce orders. Once configured, a daily scheduled sync runs automatically, fetching shipping costs from the StarShipIt API and saving them to the order and as expenses for accurate profit reporting.

### What the integration does

- Syncs shipping costs from StarShipIt to WooCommerce orders using the order number
- Runs a daily sync that processes up to 50 orders per run (orders that do not yet have a synced cost)
- Saves the shipping cost to order meta (`_wpd_ai_total_shipping_cost` and `_wpd_ai_starshipit_api_cost`)
- Creates an expense in Alpha Insights for each synced order (reference: StarShipIt - {order_id}), categorized as Shipping
- Recalculates order profit after each successful sync
- Uses the StarShipIt API endpoint `https://api.starshipit.com/api/orders` and reads `total_shipping_price` from the order response

### Requirements

- Alpha Insights Pro with StarShipIt integration available
- WooCommerce with orders in a paid status
- StarShipIt API Key and Subscription Key from your StarShipIt account
- Action Scheduler (included with WooCommerce) for the daily sync

### Settings

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

#### API Key

The API key for your StarShipIt account. Required for the integration to run.

#### Subscription Key

The subscription key (Ocp-Apim-Subscription-Key) for your StarShipIt account. Required together with the API key.

#### Enable Logging

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

#### Next Scheduled Sync

Displays the next time the daily shipping cost sync will run. The schedule is set when you save settings and runs once per day.

### How to set up

1. Obtain your API Key and Subscription Key from your StarShipIt account.
2. In WordPress, go to Alpha Insights → Settings → Integrations.
3. Enter the API Key and Subscription Key in the StarShipIt section.
4. Optionally enable Enable StarShipIt logging for debugging.
5. Click Save changes. The integration activates when both keys are present; the recurring daily sync is scheduled on the next run of Alpha Insights’ event scheduler.

### How the sync works

- The sync only processes orders that are in a paid status and do not already have `_wpd_ai_starshipit_api_cost` set.
- Up to 50 orders are processed per run, ordered by date (newest first).
- For each order, Alpha Insights calls the StarShipIt API with the WooCommerce order number (not the internal order ID).
- If the API returns a `total_shipping_price`, it is saved to the order and an expense is created. Order totals are recalculated.
- If the API call fails or no shipping cost is found, the order’s attempt count is incremented. After 3 failed attempts, the order is skipped in future runs.
- There is a short delay (0.5 seconds) between API requests to reduce the risk of rate limiting.

### Order meta and expenses

When a shipping cost is synced successfully:

- Order meta: `_wpd_ai_starshipit_api_cost`, `_wpd_ai_total_shipping_cost`, and `_wpd_ai_starshipit_api_sync_attempt_count` (used for retries).
- Expense: A single expense per order with reference StarShipIt - {order_id}, category Shipping, and date from the order (date paid or date created).

### Troubleshooting

#### Sync not running

- Ensure both API Key and Subscription Key are saved and non-empty.
- Check that Action Scheduler is working (WooCommerce → Status → Scheduled Actions).
- Enable logging and review the StarShipIt log and StarShipIt error log at the bottom of the Integrations settings.

#### Orders not getting a shipping cost

- Confirm the order has a paid status.
- In StarShipIt, ensure the order exists and has a `total_shipping_price` (or equivalent) that the API returns.
- WooCommerce order number must match what StarShipIt expects; custom order number plugins are supported as long as the order is findable by that number.
- After 3 failed attempts, the order is skipped; you would need to clear the attempt meta or the starshipit cost meta to retry (or rely on support/developer tools).

### Developer note

Logging can be overridden with the filter `wpd_ai_starshipit_enable_logging`. See the filter documentation for details.