# Shopify to Wave Sync - Setup Guide

## What This Does
- Listens for new orders from Shopify
- Listens for new customers from Shopify
- Automatically creates customers in Wave (if they don't exist)
- Automatically creates invoices in Wave from Shopify orders
- No monthly fees, runs on your own server
- Logs all activity for debugging

## Prerequisites
- A web server with PHP 7.4+ (cURL enabled)
- Shopify store
- Wave account
- Domain/URL where this script can be accessed

## Step 1: Get Shopify API Credentials

1. Log into your Shopify Admin
2. Go to **Settings → Apps and integrations**
3. Click **Develop apps** (top right)
4. Click **Create an app**
5. Name it "Wave Sync" and create it
6. Go to **Configuration** tab
7. Under **Admin API scopes**, enable:
   - `read_customers`
   - `read_orders`
8. Click **Save** and then **Reinstall app**
9. Go to **API Credentials** tab
10. Copy your **Admin API access token** (you'll need this)
11. Go to **Webhooks** tab in the dev app, add webhooks:
    - Event: **Customer created**
    - URL: `https://yourdomain.com/webhook.php`
    - Event: **Order created**
    - URL: `https://yourdomain.com/webhook.php`
12. Save webhooks
13. Under **Display information**, copy the **Client secret** (this is your webhook secret)

## Step 2: Get Wave API Token

1. Go to https://gql.waveapps.com/
2. Log in with your Wave account
3. Look for **API Token** section
4. Click to generate a new token
5. Copy the token
6. In your Wave app, go to **Settings → Business Settings**
7. Copy your **Business ID** (visible in the URL or settings)

## Step 3: Deploy the Script

1. Download `shopify-wave-sync.php` to your web server
2. Edit the configuration at the top:
   ```php
   define('SHOPIFY_WEBHOOK_SECRET', 'paste_your_shopify_client_secret_here');
   define('WAVE_API_TOKEN', 'paste_your_wave_api_token_here');
   define('WAVE_BUSINESS_ID', 'paste_your_wave_business_id_here');
   ```
3. Make sure the script is accessible at your webhook URL (e.g., `https://yourdomain.com/webhook.php`)
4. Create a `sync.log` file in the same directory with write permissions:
   ```bash
   touch sync.log
   chmod 666 sync.log
   ```

## Step 4: Test It

1. In Shopify Admin, create a test customer
2. Check your `sync.log` file - you should see a success message:
   ```
   [2026-04-17 14:32:15] Received webhook: customers/create
   [2026-04-17 14:32:16] Created Wave customer: test@example.com (ID: ...)
   ```
3. Create a test order in Shopify
4. In your Wave account, you should see a new invoice with the order details

## Troubleshooting

**Check the log file** - The script logs every webhook and any errors to `sync.log`. Most issues appear there.

**Common problems:**

- **"Invalid webhook signature"** - Your `SHOPIFY_WEBHOOK_SECRET` is wrong. Get it from Shopify's **Client secret** field.
- **"Wave API error"** - Check that your `WAVE_API_TOKEN` is valid and not expired. Regenerate at https://gql.waveapps.com/
- **"Could not find business"** - Verify your `WAVE_BUSINESS_ID` is correct (from Wave settings URL)
- **Webhook not triggering** - Verify your webhook URL is publicly accessible (not localhost)

**Test manually:**

You can test the webhook manually using cURL:
```bash
curl -X POST https://yourdomain.com/webhook.php \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Topic: orders/create" \
  -H "X-Shopify-HMAC-SHA256: test" \
  -d '{"id":123,"email":"test@example.com"}'
```

## What Gets Synced

**Customers:**
- Email
- First name
- Last name

**Orders:**
- Order number → Invoice ID (SHOP-12345)
- Customer email → Links to Wave customer
- Line items with descriptions and prices
- Shipping charges
- Sets invoice as DRAFT (you can send manually or auto-send)

## Manual Sync / Backfill

This script only syncs NEW orders/customers going forward. To manually add historical orders:

1. Export CSV from Shopify (Orders or Customers)
2. Create customers/invoices in Wave manually, or
3. Modify this script to batch-import CSVs (requires coding)

## Security Notes

- The webhook verifies Shopify's signature - only accepts legitimate Shopify webhooks
- Wave API token is stored locally (keep this file secure)
- Logs may contain customer emails - protect your `sync.log` file with appropriate file permissions
- Consider disabling file listing on your server directory

## Customization Examples

**Only sync paid orders:**
```php
if ($order['financial_status'] !== 'paid') {
    log_message("Skipping unpaid order");
    return;
}
```

**Set invoice to APPROVED instead of DRAFT:**
```php
'status' => 'APPROVED'
```

**Add custom account mapping:**
Change the account names in the invoice creation:
```php
'account' => [
    'name' => 'Sales Revenue'  // Change this
]
```

## Support

- Check `sync.log` for error messages
- Review webhook delivery history in your Shopify dev app
- Wave's GraphQL API docs: https://developers.wave.app/
- Shopify webhook docs: https://shopify.dev/docs/api/admin-rest/webhook-topics