# ShipStation Integration - Quick Start Guide

## 🚀 Get Started in 5 Minutes

### Step 1: Install Dependencies (30 seconds)

```bash
npm install
```

### Step 2: Add Environment Variables (1 minute)

Add to your `.env.local` file:

```env
SHIPSTATION_API_KEY=45df243c25724253a8085b39e81c26c2
SHIPSTATION_API_SECRET=a99e4153d60a453685936dfd87b1d2bf
```

### Step 3: Test Connection (30 seconds)

```bash
npm run test:shipstation
```

**Expected Output**:
```
✅ SHIPSTATION_API_KEY: configured
✅ SHIPSTATION_API_SECRET: configured
✅ API authentication successful!
✅ Test order created successfully!
```

### Step 4: Configure Webhooks (2 minutes)

**In ShipStation**:
1. Go to Settings → API Settings → Webhooks
2. Click "Add Webhook"
3. URL: `https://your-domain.com/api/shipstation/webhook`
4. Select events: `SHIP_NOTIFY`, `ITEM_SHIPPED`
5. Save

### Step 5: Test Payment Flow (1 minute)

1. Start dev server: `npm run dev`
2. Process test payment with card `4242 4242 4242 4242`
3. Check ShipStation dashboard - order should appear!

## ✅ Verification

### Order Created Successfully?

**Check WooCommerce order metadata**:
- `_shipstation_order_id` ✅ Should be present
- `_shipstation_synced_at` ✅ Should have timestamp

**Check ShipStation dashboard**:
- Order appears in "Awaiting Shipment"
- Order number matches WooCommerce ID

### Shipment Notification Working?

**Test**:
1. Mark order as shipped in ShipStation
2. Add tracking number
3. Check WooCommerce order:
   - Status should be "shipped"
   - Tracking number in metadata

## 🔧 Troubleshooting

### "401 Unauthorized"
- Check API credentials are correct
- No extra spaces in `.env.local`
- Try regenerating keys in ShipStation

### Order Not Appearing in ShipStation
- Check application logs for errors
- Verify API credentials
- Check order metadata for `_shipstation_sync_error`

### Webhook Not Received
- Verify webhook URL is correct
- Check events are enabled
- Test webhook manually from ShipStation

## 📚 Documentation

- **Detailed Setup**: See `SHIPSTATION_SETUP.md`
- **Technical Details**: See `SHIPSTATION_INTEGRATION.md`
- **Implementation Summary**: See `SHIPSTATION_IMPLEMENTATION_SUMMARY.md`

## 🎯 What Happens Now?

### When Customer Pays:
1. ✅ Payment processed via Stripe
2. ✅ WooCommerce order → "processing"
3. ⭐ **Order created in ShipStation automatically**
4. ✅ Customer receives confirmation

### When You Ship:
1. ⭐ **Mark as shipped in ShipStation**
2. ⭐ **WooCommerce auto-updates to "shipped"**
3. ⭐ **Tracking info added to order**
4. ✅ Customer can track shipment

## 🔒 Security Notes

- ✅ All API calls from server (never exposed to browser)
- ✅ Credentials stored in environment variables
- ✅ Rate limiting enabled (100 webhooks/min)
- ✅ Graceful error handling (payment succeeds even if ShipStation fails)

## 🚨 Important

**After Testing**:
- Delete test order #999999 from ShipStation dashboard
- Update webhook URL to production domain before going live
- Monitor logs for first 24 hours after deployment

## ⚡ Quick Commands

```bash
# Install dependencies
npm install

# Test ShipStation connection
npm run test:shipstation

# Start development server
npm run dev

# Build for production
npm run build
```

## 📞 Need Help?

1. Run test script: `npm run test:shipstation`
2. Check logs for `[shipstation]` entries
3. Review `SHIPSTATION_INTEGRATION.md` for details
4. Contact ShipStation support for API issues

---

**That's it!** Your integration is ready. Process a test payment to see it in action! 🎉