# Shopify Dev App Setup Guide
## For Cydekick-BMP Integration

This guide covers setting up a Shopify custom/dev app in the Partner Dashboard
to connect to the Cydekick-BMP platform (Order Sync, SKU Sync, Inventory Sync).

---

## Step 1 — Create the App in Shopify Partner Dashboard

1. Go to https://partners.shopify.com → **Apps** → **Create app**
2. Choose **Create app manually**
3. Enter an app name, e.g. `Cydekick-BMP`
4. Click **Create**

---

## Step 2 — Configure App Settings

Inside the app:

1. Click **Create version** (or open an existing version)
2. Under **URLs → App URL** enter your store URL or server URL
3. Under **Redirect URLs** add:
   ```
   https://yourdomain.com/channels/shopify/callback
   ```
   *(or your local URL, e.g. http://localhost/channels/shopify/callback)*
4. Under **Access → Scopes** enter exactly:
   ```
   read_products,write_products,read_inventory,write_inventory,read_locations,read_orders
   ```
5. Click **Save** then click **Release version**

---

## Step 3 — Get Your Credentials

Go to the **Client credentials** section and copy:

- **Client ID** → this is your **API Key** in Cydekick
- **Client Secret** → this is your **API Secret** in Cydekick

---

## Step 4 — Request Protected Customer Data Access

This is required for the Order Sync to work (orders contain customer data).

1. In the Partner Dashboard sidebar click **API access requests**
2. Find **Protected customer data access** → click **Request access**

### Step 4a — Select data use and reasons

Click **Select** next to **Protected customer data** and tick:

- [x] **Store management** — *"Import Shopify orders into our internal ERP system to manage fulfilment, inventory, and customer records."*
- [x] **App functionality** — *"Core feature of the ERP is to sync orders, customers, and order lines from Shopify into our business management platform for processing."*

Click **Save**.

### Step 4b — Protected customer fields (optional section)

Click **Select** on each field below and choose the same reasons (Store management + App functionality):

| Field | Reason |
|---|---|
| **Name** (first + last name) | Store management, App functionality |
| **Address** (billing + shipping) | Store management, App functionality |
| **Email** | Store management, App functionality |
| **Phone** | Store management, App functionality |

> **Important:** Since this is a dev/custom app, you do NOT need to submit for
> review. Shopify grants access immediately once you save Step 1.
> Only public App Store apps need a review.

---

## Step 5 — Data Protection Details

Fill in the data protection questionnaire as follows:

### Purpose

| Question | Answer |
|---|---|
| Do you process the minimum personal data required to provide value to merchants? | **Yes** |
| Do you tell merchants the personal data that you process and your purposes for processing it? | **Yes** |
| Do you limit your use of personal data to that purpose? | **Yes** |

### Consent

| Question | Answer |
|---|---|
| Do you have privacy and data protection agreements with your merchants? | **Yes** *(you are the merchant — it's your own store and app)* |
| Do you respect and apply customers' consent decisions? | **Not applicable** *(internal ERP, not a public-facing consumer app)* |
| Do you respect and apply customers' decisions to opt-out of having their data sold? | **Not applicable** *(you are not selling data)* |
| If you use personal data for automated decision-making and those decisions may have legal or significant effects, can customers opt-out? | **Not applicable** *(no profiling or automated decisions are made)* |

### Storage

| Question | Answer |
|---|---|
| Do you have retention periods that make sure personal data isn't kept longer than needed? | **Yes** |
| Do you encrypt data at rest and in transit? | **Yes** |
| Do you encrypt your data backups? | **Yes** |
| Do you separate test and production data? | **Yes** |
| Do you have a data loss prevention strategy? | **Yes** |

### Access

| Question | Answer |
|---|---|
| Do you limit staff access to customers' personal data? | **Yes** |
| Do you have strong password requirements for staff passwords? | **Yes** |
| Do you log access to personal data? | **Yes** |
| Do you have a security incident response policy? | **Yes** |

### Audits and certifications

Leave blank.

Click **Save**.

---

## Step 6 — Add the Channel in Cydekick

1. Go to **Channels → Channels → Create**
2. Fill in:
   - **Name** — e.g. `Shopify Banwells`
   - **Platform** — `Shopify`
   - **Shop Domain** — e.g. `your-store.myshopify.com`
   - **API Key (Client ID)** — from Step 3
   - **API Secret (Client Secret)** — from Step 3
3. Click **Save**
4. Click the **Connect to Shopify** button
5. You will be redirected to Shopify to authorise — click **Install**
6. You will be returned to Cydekick with status set to **Connected**

---

## Step 7 — Verify Scopes

After connecting, the Channel view page will show the **Scopes** field.
It should read:
```
read_products,write_products,read_inventory,write_inventory,read_locations,read_orders
```
If `read_orders` is missing, re-authorise via the Connect button.

---

## Step 8 — Configure SKU Mappings (for Order Sync linking)

Before running Order Sync, set up SKU mappings so order lines are linked to
Cydekick inventory products:

1. Go to the Channel → **SKU Mappings** tab
2. Map each Shopify SKU to the corresponding Cydekick product
3. Orders imported without a matching SKU mapping will be marked `[UNLINKED]`
   but will still import — they just won't be tied to inventory

---

## Step 9 — Run Order Sync

1. Go to the Channel → **Order Sync** tab
2. Click **Import Orders**
3. The page auto-refreshes every few seconds — errors appear automatically
4. Check the error panel if any orders fail to import
5. Subsequent syncs are incremental (only new orders fetched)
   — use **Reset Cursor** to re-check all orders from the beginning

---

## Troubleshooting

| Error | Fix |
|---|---|
| `403: This app is not approved to access REST endpoints with protected customer data` | Complete Steps 4 and 5 above — request protected customer data access in Partner Dashboard |
| `403: read_orders scope required` | Re-authorise the app via the Connect button to get a new token with updated scopes |
| `Sync failed — fatal error` | Check the error panel on the Order Sync page for the full message and stack trace |
| Orders not appearing after sync | Check the queue worker is running: `php artisan queue:work` (see `running_workers.rmd`) |
| `[UNLINKED]` lines on orders | Set up SKU mappings in the SKU Mappings tab for those product SKUs |