# Shopify Connector Setup Guide

Use this guide to connect a Shopify store to NexWave and confirm that orders, payments, products, and inventory are synchronising correctly.

This is a full setup and verification workflow. Use it when you are connecting a new Shopify store, reviewing an existing connection, or checking why orders or stock quantities are not flowing as expected.


:::info
NexWave does not have a public app in the Shopify App Store. Connect Shopify by creating a custom app in the Shopify Dev Dashboard, then authorising that app from the **Shopify Store** record in NexWave.

:::

## Before You Start

Confirm these details before you begin:

* You can sign in to NexWave with a role that can create and edit **Shopify Store** records.
* You have administrator access to the Shopify store.
* You know which NexWave **Company** should receive the Shopify orders.
* You know which NexWave **Warehouse** maps to each Shopify location.
* You know which NexWave items should map to each Shopify product or variant, especially when one product has multiple variants.
* You know whether NexWave should automatically create **Sales Orders**, **Sales Invoices**, **Payment Entries**, and **Delivery Notes** from Shopify activity.
* You have confirmed the tax accounts, write-off account, and payment modes to use for imported orders.
* You know whether scheduled inventory sync should check every mapped item or only items with changed stock quantities or Shopify mappings.
* You know whether Shopify draft orders should reserve stock immediately before they are paid or submitted.
* You know who reviews **NexWave Shopify Log** entries when inventory or product sync is skipped.

If you are replacing an older access-token connection, plan a short maintenance window so users are not changing the same store settings while the connection is being reauthorised.

## Part 1: Create the Shopify App

### Step 1: Open the Shopify Dev Dashboard


1. Sign in to your Shopify admin portal at <https://admin.shopify.com/>.
2. Go to **Settings**.
3. Open **Develop apps**.

 ![Shopify Develop apps page](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC84ZTU4OWNjMS0wOWViLTRkZmYtOTg5NS01YjdlMGE3ZmM2MTUvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.gyihVvdwbsLrkfOebWQ9mMO4RjpAArdHJGaM5Ei3ICg)


4. Click **Develop apps in Dev Dashboard**.

 ![Develop apps in Dev Dashboard button](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9jMDEwOWY1NC1iNmNlLTRjZWItOGE5OC05YTM4N2I4YjQ3NmQvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.Mvu5BGGqdP-egqESzIUzkQyekZoYCY1efSPDWn5zhS8)


5. In the Shopify Dev Dashboard, open **Apps** from the left sidebar.

 ![Shopify Dev Dashboard Apps page](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9hMDY0ODA3Yi03YzllLTQ2NDYtYmU3NS1lODM3MmUzNDNlYjkvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.sielY91tQg01XlN9zD1NPh_FScu7LjTn9xLVGyVSDrM)

### Step 2: Create a New App


1. Click **Create app**.
2. Enter a clear app name, for example *NexWave Integration - Main Store*.
3. Click **Create**.

 ![Create Shopify app dialog](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9mYWQ2NTg1ZC1kOGYyLTQ2OTQtOGI5NS0zNjAyZTQ1YTkwYjYvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.WMYtB3sDauBw1__UBAgOR3IlKPK_OwjQp_DdstHsNHI)

### Step 3: Configure App Settings

After the app is created:


1. Click **Configuration** in the left sidebar.
2. Scroll to **Settings**.

 ![Shopify app configuration page](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9lMDcxZTcwNi00ZTRiLTQwZTMtODczYi0xMjlkYWQ4MjkzNGYvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.ElsT8RoG-JLdyE7qDGB38TXIOSa2OqJn-ESsnRU0xLg)

### Step 4: Add the Callback URL and Permissions


1. In NexWave, create or open the matching **Shopify Store** record.
2. Set **Authentication Method** to **OAuth**.
3. Copy the **Callback URL** shown on the NexWave record.
4. In Shopify, add that exact value to the app's **Redirection URLs**.

 ![Shopify redirection URLs section](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9jYWNkNzllZS0zODZiLTRhNzYtODhjMy02OTAwOWU1NDNiOGEvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.yPKWnznHmHq9aFlu0fLn0BJzSr_oZYJyfDefhq8P7Zg)

Add Shopify Admin API permissions for:

* Customers: read and write
* Fulfilments: read and write
* Inventory: read and write
* Locations: read
* Orders: read and write
* Products: read and write

If your store uses additional Shopify features, confirm the required permissions with your NexWave administrator before authorising the app.

### Step 5: Copy the Client Credentials


1. Open **Client credentials** in Shopify.
2. Copy the **Client ID**.
3. Reveal and copy the **Client secret**.

 ![Shopify client credentials page](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC84N2QyYWM1OC1mYjEyLTQxZDgtYTdlNS0xZDY4YWM5OThhNDUvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.LLVR_1N43t-51Y487OMMwLqX3e8p7x2PKP0AWhxS0MI)

Keep the **Client secret** secure. Do not place it in documents, tickets, shared chat messages, or version control.

## Part 2: Configure the Shopify Store in NexWave

### Step 1: Create or Open the Shopify Store


1. In NexWave, search for **Shopify Store**.
2. Open the **Shopify Store** list.
3. Click **+ Add Shopify Store**, or open the existing store record you are reviewing.

 ![Shopify Store list in NexWave](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC82YzJjMGQ0ZS0wYzc1LTRjOTgtYTRhZi1jOGM3NWUyOTY2ZmMvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.aqYX4UTFhau6KQWHQU0TdgRnlFLBc_7NrxFvKimzDRk)

### Step 2: Enter the Basic Store Details

Fill in these fields:

| Field | What to enter |
|-------|---------------|
| **Shop Domain** | The store's Shopify domain, such as `example-store.myshopify.com`. |
| **Company** | The NexWave company that owns the sales, stock, tax, and payment entries for this store. |
| **Enabled** | Tick this when the store should actively sync. |
| **Default Customer** | Optional fallback customer if a customer cannot be matched or created. |
| **Customer Group** | Optional customer group for new customers created from Shopify. |
| **Cost Centre** | Optional cost centre for transactions from this store. |
| **Price List** | Optional price list reference for imported or synced items. |
| **Item Group** | Optional item group for new items created through the integration. |

 ![Shopify Store basic settings](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC8wZThlNTdkNy1lYzgwLTQyNDgtYWFlNy1hODhmYjFkMTg2NmIvU2NyZWVuc2hvdCAyMDI2LTAxLTE1IGF0IDEzLjE3LjA4LnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkyNjExOTAwLCJleHAiOjE3OTI2OTgzMDB9.hNwCEAXhRvTEwatko3gCPKG_bZB-yBkiVGjQB0VC_do)

### Step 3: Configure OAuth


1. Set **Authentication Method** to **OAuth**.
2. Paste the **Client ID** from Shopify.
3. Paste the **Client Secret** from Shopify.
4. Save the **Shopify Store** record.

The **Callback URL** field is generated by NexWave. It should match the value you entered in Shopify.


:::warning
Use the legacy **Access Token** option only for older stores that were already connected that way. For new Shopify custom apps, use **OAuth**.

:::

## Part 3: Connect and Test the Store

### Step 1: Connect to Shopify


1. Open the saved **Shopify Store** record.
2. Click **Actions**.
3. Click **Connect to Shopify**.

 ![Connect to Shopify action](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC8yMzVkY2VjYi0xMjFjLTQ1Y2QtODE4Zi0xYTQwYzg5NmNjNTcvU2NyZWVuc2hvdCAyMDI2LTAxLTE1IGF0IDEzLjE5LjE1LnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkyNjExOTAwLCJleHAiOjE3OTI2OTgzMDB9.Vgrl-txIejQEbcrxcetg-0ln0lvWV2ZpqKNx3-rMAj8)

### Step 2: Authorise the App in Shopify


1. Review the permissions requested by the app.
2. Click **Install app**.

 ![Shopify app authorisation screen](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC8yODFiNDBiNS00NmMyLTRlOWUtYTBmYy02NzY1NTY1NjIxNDUvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.uNOJ2H1z7eGHIgznVQTYJk3LAYRZaQBNJayFE4_w_HM)

After authorising, Shopify redirects you back to NexWave.

### Step 3: Confirm the Connection

On the **Shopify Store** record, confirm:

* The connection banner is green.
* **OAuth Status** shows *Connected*.
* **Connected User** is populated.

 ![Connected Shopify Store banner](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9lNjY4MGQxNi0zNjVmLTQ2YTgtOGQ1NS1kOTgwNzlmYjE5YmEvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.mGzvuNRertEDzmA8CJHPWMCjbBP6Sbd2IHfAGKctqdI)

### Step 4: Test the Connection


1. Click **Actions**.
2. Click **Test Connection**.
3. Confirm the dialog shows the Shopify shop details, including store name, domain, email, currency, and plan.

 ![Shopify connection test result](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC84NTM2MTQ3Yi0zOWRjLTRhNmQtODJjMC0xODAwNjExOTdlMjMvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.YVWF7xtoxqYUG98V2iWLOkN4iPkHamA_rKTFbdzVyEw)

Do not continue with order or inventory sync until **Test Connection** succeeds.

## Part 4: Configure Orders, Payments, and Tax

### Order Settings

In **Order Settings**:

| Setting | When to use it |
|---------|----------------|
| **Sync Orders** | Tick this when Shopify orders should create records in NexWave. |
| **Sync All Order Statuses** | Use this carefully. On a first sync it can import a large number of historical, completed, or closed orders. |
| **Sales Order Series** | Optional naming series for Sales Orders created from Shopify. |
| **Delivery Note Series** | Optional naming series for Delivery Notes created from Shopify fulfilment events. |
| **Sales Invoice Series** | Optional naming series for Sales Invoices created from Shopify. |
| **Last Order Sync** | Read-only timestamp showing the last successful order sync point. |

In **Order Automation**:

| Setting | Result |
|---------|--------|
| **Auto-submit Sales Order** | Submits Sales Orders for paid Shopify orders. |
| **Auto-create Invoice** | Creates a Sales Invoice after the Sales Order is submitted. |
| **Auto-create Payment Entry** | Creates Payment Entries against the Sales Invoice when Shopify payment information can be matched. |
| **Add Shipping as Item** | Adds shipping as an item line instead of as a tax row. |
| **Shipping Item** | Item to use when **Add Shipping as Item** is ticked. |
| **Auto-create Delivery Notes for Remaining Qty** | Allows fulfilment events to create Delivery Notes for remaining undelivered quantities. |

### Payment Method Mapping

If **Auto-create Payment Entry** is ticked, complete **Payment Method Mapping** before enabling live order sync.

Each Shopify payment gateway that may appear on a paid order should map to a NexWave **Mode of Payment** and account. This is important for stores that accept multiple payment methods, such as card, wallet, store credit, or other split-payment combinations.

If a paid order imports but no Payment Entry is created, check **Payment Method Mapping** and then review **NexWave Shopify Log** for the store.

### Customer Matching on Order Import

When an order imports, NexWave first checks whether the Shopify customer is already linked to an active **Customer**. If there is no existing Shopify link, NexWave checks **Contact** records with the same email address and uses the linked active **Customer** when there is one clear match.

If the email is linked only to disabled **Customer** records, the order sync stops with a message naming those disabled records. This prevents new orders from being attached to an inactive customer by mistake.

To resolve a customer matching error:


1. Open the related **NexWave Shopify Log** entry.
2. Read the message to confirm whether the email is linked only to disabled **Customer** records.
3. Open the named **Customer** record and decide whether it should be re-enabled, left disabled, or replaced by another active **Customer**.
4. Check the linked **Contact** email and make sure it points to the active **Customer** that should receive future orders.
5. If the order should always use one fallback customer, set **Default Customer** on the **Shopify Store**.
6. Run **Sync > Sync Orders** again after the customer and contact records are corrected.

### Tax Settings

In **Tax Settings**, configure:

| Field | Purpose |
|-------|---------|
| **Default Sales Tax Account** | Default account for Shopify tax when no more specific mapping applies. |
| **Default Shipping Charges Account** | Account for shipping charges when shipping is not added as an item. |
| **Write Off Account** | Account for small rounding differences between Shopify and NexWave totals. |
| **Tax Accounts** | Mapping from Shopify tax titles to NexWave tax accounts and templates. |

Use a **Write Off Account** even when you expect totals to match. Shopify and NexWave may round tax-inclusive orders differently by a few cents.

## Part 5: Configure Products and Inventory

### Fetch Locations and Map Warehouses

To sync inventory, map each Shopify location to a NexWave warehouse.


1. Click **Actions**.
2. Click **Fetch Shopify Locations**.
3. In **Warehouse Mapping**, select the matching NexWave warehouse for each Shopify location.
4. Save the store.

 ![Fetched Shopify locations and warehouse mapping](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9kYWQ2ZWI5NS0wMDVjLTRiZTYtOGE3My1jNDdlOGZmODA5MzYvaW1hZ2UucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTI2MTE5MDAsImV4cCI6MTc5MjY5ODMwMH0.xsJiWxO88_MoICmhh0clDzpfcd_ZrvEiseQn3w0PxjI)

### Product and Item Sync Settings

In **Item Sync Settings**:

| Setting | Purpose |
|---------|---------|
| **Enable Item Sync** | Allows NexWave items to sync to Shopify. |
| **Update Shopify on Item Update** | Pushes item changes to Shopify when the item is updated in NexWave. |
| **Enable Image Sync** | Sends item images to Shopify products when item sync runs. |
| **Item Field Mapping** | Maps NexWave item fields to Shopify product fields or metafields. |

For existing Shopify products, click **Actions** and use **Fetch Products & Map by SKU** before running full item sync. This creates item-store mappings where Shopify SKUs match NexWave item codes.

Use **Sync > Sync All Items** after checking mappings. This queues sync for eligible items and is better than editing every product manually.

### Validate Item and Variant Mappings

Before relying on inventory sync, confirm each sellable Shopify variant is linked to the correct NexWave item for this store. Open the Item record and review the **Shopify Stores** rows.

| Field | What to check |
|-------|---------------|
| **Shopify Store** | The row belongs to the store connection you are reviewing. |
| **Enabled** | Only enabled rows are considered for product and inventory sync. |
| **Shopify Product ID** | The Shopify product linked to this NexWave item. |
| **Shopify Variant ID** | The Shopify variant linked to this NexWave item. This is important for products with several variants. |
| **Shopify Inventory Item ID** | The Shopify inventory target used for stock quantity updates. NexWave can refresh it from Shopify when it is missing or stale. |
| **Last Sync At** | The most recent successful product or item sync for this store row. |

Use **Fetch Products & Map by SKU** for existing Shopify products before a full item sync. This reduces manual mapping work and helps each Shopify variant land on the correct NexWave item.

If one NexWave item maps to more than one Shopify variant, keep one **Shopify Stores** row per variant and confirm each row points to the correct store, product, and variant.

Do not leave two different NexWave items enabled against the same Shopify inventory item for the same store. When NexWave detects conflicting ownership, it skips the affected stock update instead of sending a quantity to the wrong Shopify product. Review **NexWave Shopify Log**, disable or correct the wrong row, then run **Sync > Sync Inventory** again.

When troubleshooting a product, compare the Item's **Shopify Stores** row, the Shopify product or variant, and the latest **NexWave Shopify Log** entry before changing store-wide settings.

### Collection Mapping and Item Filters

Use **Collection Mapping** when Shopify collections should be driven by NexWave item values, such as brand, range, season, or product group.

Use **Item Eligibility Filters** to control which items can sync to this store. This is useful for multi-store setups where not every item belongs in every Shopify store.

### Inventory Settings

In **Inventory Settings**:

| Field | Purpose |
|-------|---------|
| **Enable Inventory Sync** | Allows NexWave to push inventory levels to Shopify. |
| **Inventory Sync Mode** | Choose whether scheduled inventory runs check every mapped item or only items with changed stock quantities or Shopify mappings. |
| **Reserve Stock for Draft Orders** | Tick this when imported Shopify draft orders should reserve stock in NexWave and reduce the inventory quantity pushed back to Shopify. |
| **Default Warehouse** | Optional warehouse used when a more specific location mapping is not available. |
| **Inventory Sync Frequency** | Minimum interval, in minutes, between automatic inventory sync runs. |
| **Last Inventory Sync** | Read-only timestamp showing the last inventory sync that made progress. |
| **Warehouse Mapping** | Maps Shopify locations to NexWave warehouses. |

 ![Inventory Settings with draft order stock reservation](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC8xYzlmZGI5OC04ZGU2LTQ3ZjUtOTMzZC1mZDAzOGNiYWRhOWIvMDEtaW52ZW50b3J5LXNldHRpbmdzLWRyYWZ0LW9yZGVycy5wbmciLCJ0eXBlIjoiYXR0YWNobWVudCIsImlhdCI6MTc5MjYxMTkwMCwiZXhwIjoxNzkyNjk4MzAwfQ.QfCqo430auAf3coCKdiKfAc-tmxrmXn0pnd8GcvkxA8)

Use **Full Inventory** when you are setting up a store, recovering from a mapping change, or want every scheduled run to check every mapped item. Existing stores default to **Full Inventory**.

Use **Changed Bins** after a clean full inventory sync when the store has many items and scheduled runs should process only items whose stock quantity or Shopify mapping changed since **Last Inventory Sync**. If there is no previous **Last Inventory Sync**, NexWave runs a full baseline first.

NexWave sends available-for-sale quantity to Shopify, not total physical stock. This means the quantity sent to Shopify is current stock less stock already reserved for Sales Orders, never below zero.

If **Reserve Stock for Draft Orders** is ticked, imported Shopify draft orders also reduce the available-for-sale quantity once their stock reservation is created. Use this when draft orders represent committed demand that should not be sold again before the order is paid or submitted. Leave it unticked when draft orders are quotes, abandoned checkouts, or otherwise not firm enough to reserve stock.

When a draft order is later submitted or cancelled through the connector, NexWave avoids double-reserving the same demand and releases the active draft reservation on cancellation.

Use **Sync > Sync Inventory** when you need to push current inventory immediately. Manual inventory sync runs a full push even when **Inventory Sync Mode** is set to **Changed Bins**, and it bypasses the normal frequency window before queuing the run in the background.

### API Compatibility for Inventory Sync

NexWave uses Shopify's current inventory update method for inventory sync. If a store is configured on an older Shopify Admin API version, NexWave uses a compatible inventory version for stock updates without changing the stored store setting.

You normally do not need to edit **API Version** just because inventory sync runs. If Shopify reports an inventory API error, check **NexWave Shopify Log**, confirm the app still has Inventory read and write permissions, then run **Test Connection** and retry **Sync > Sync Inventory**.

## Part 6: Register and Verify Webhooks

In **Webhook Events**, decide which Shopify events NexWave should process.

| Setting | Purpose |
|---------|---------|
| **Process Order Create Webhooks** | Receive new Shopify orders. |
| **Process Order Paid Webhooks** | Process payment confirmations and order automation. |
| **Process Order Cancelled Webhooks** | Sync cancellations from Shopify. |
| **Process Fulfilment Webhooks** | Create Delivery Notes when Shopify orders are completed in Shopify. |

 ![Shopify webhook event settings](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9iODEwNjdmZi1lODI3LTRlZDgtYmZiMC0wMzk0NTY4ZTM0M2EvU2NyZWVuc2hvdCAyMDI2LTAxLTIyIGF0IDIxLjQ2LjQwLnBuZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkyNjExOTAwLCJleHAiOjE3OTI2OTgzMDB9.eL8MvVB06jaulSkhxRBu-kYt98EJuNOGX3ZUXY3Hb8E)

After changing webhook settings:


1. Save the **Shopify Store** record.
2. Click **Actions**.
3. Click **Register Webhooks**.
4. Click **Actions** again.
5. Click **Fetch Webhooks** and confirm the expected events are registered.

If registration partially fails, check the message shown by NexWave and then review **NexWave Shopify Log**.

## Part 7: Run Post-Setup Verification

Use these checks before relying on the integration for live operations.

### Verify Order Sync


1. Confirm **Sync Orders** is ticked.
2. Confirm **Payment Method Mapping** covers every active Shopify payment gateway.
3. Click **Sync > Sync Orders**.
4. Review the result message for synced, skipped, and errored orders.
5. Open the latest imported **Sales Order** and confirm:
   * **Shopify Store** is populated.
   * The Shopify order number is present.
   * Customer and address details look correct.
   * The correct company, currency, tax, and warehouse details were used.
6. If Shopify draft orders are used, confirm whether the imported draft **Sales Order** should reserve stock based on **Reserve Stock for Draft Orders**.
7. If **Auto-create Invoice** and **Auto-create Payment Entry** are enabled, open the linked Sales Invoice and Payment Entry to confirm the invoice is paid or allocated as expected.

### Verify Product Sync


1. Open a clean test item that should appear in Shopify.
2. Confirm the item has a **Shopify Stores** row for the relevant store, or that it matches the store's **Item Eligibility Filters**.
3. Click **Sync to Shopify** from the Item, or use **Sync > Sync All Items** from the **Shopify Store**.
4. Review the matching **Item Shopify Store** row for **Shopify Product ID**, **Shopify Variant ID**, **Shopify Inventory Item ID**, and **Last Sync At**.
5. For products with several variants, confirm each variant has its own correct **Shopify Stores** row.
6. Check the product in Shopify and confirm title, SKU, status, image, mapped fields, and collections.

### Verify Inventory Sync


1. Confirm **Enable Inventory Sync** is ticked.
2. Confirm **Warehouse Mapping** is complete.
3. Confirm **Inventory Sync Mode** is appropriate for the store. Use **Full Inventory** for first setup and broad checks; use **Changed Bins** for normal incremental scheduled runs after a clean baseline.
4. Click **Sync > Sync Inventory** when you want an immediate full refresh.
5. Wait for the background job to finish.
6. Confirm **Last Inventory Sync** updated.
7. Check **NexWave Shopify Log** for the store.
8. Compare a small sample of Shopify quantities with the NexWave Stock Balance for the mapped warehouse.
9. If an item has several Shopify mappings, test one item with each mapped variant and location, then confirm only the intended Shopify variant quantity changed.

When comparing quantities, remember that NexWave syncs available-for-sale stock. If a quantity is lower than physical stock, check whether some stock is already reserved for Sales Orders. If **Reserve Stock for Draft Orders** is ticked, active draft Shopify order reservations are also subtracted.

### Verify Logs

Open **NexWave Shopify Log** from the Shopify workspace or the search bar. Review the latest entries for the store.

Useful checks:

* **Status** should show successful runs for recent sync jobs.
* **Method** helps identify whether the issue is order sync, item sync, inventory sync, webhook handling, or payment creation.
* **Reference Document Type** and **Reference Name** point to the related Sales Order, Sales Invoice, Item, or Shopify Store where available.
* Inventory mapping or ownership messages show item-store rows that need review before retrying sync.
* Shopify API version messages usually mean NexWave has switched the inventory call to a compatible version. Check permissions and retry before changing the stored **API Version**.
* Error entries usually mean the store setup is incomplete, a Shopify permission is missing, or a mapping needs attention.

## Troubleshooting

| Symptom | What to check |
|---------|---------------|
| **Test Connection** fails | Reconnect using **Actions > Connect to Shopify**, then confirm the **Client ID**, **Client Secret**, and Shopify permissions. |
| Shopify says the redirect URL does not match | Copy **Callback URL** from the NexWave **Shopify Store** record again and paste it into Shopify exactly. Check for old domains or extra slashes. |
| Webhooks are not received | Confirm the relevant **Webhook Events** are ticked, click **Register Webhooks**, then click **Fetch Webhooks**. Check **Shared Secret** if your setup uses a manual override. |
| Orders do not import | Confirm **Sync Orders** is ticked, the store is **Enabled**, webhooks are registered, and **Last Order Sync** is not already past the order date. Use **Sync > Sync Orders** to test manually. |
| Order sync stops with a disabled Customer message | Open the named **Customer** records, re-enable the correct active customer if appropriate, or update the linked **Contact** email before running **Sync > Sync Orders** again. |
| Paid orders import but Payment Entries are missing | Confirm **Auto-create Payment Entry** is ticked and every Shopify gateway is covered in **Payment Method Mapping**. Check **NexWave Shopify Log** for skipped or unmapped payment messages. |
| Order totals differ by a few cents | Confirm **Write Off Account** is set and tax mappings are complete. Small tax-inclusive rounding differences are expected on some orders. |
| Products do not appear in Shopify | Confirm **Enable Item Sync** is ticked, the item has a matching SKU or **Shopify Stores** row, and the item matches **Item Eligibility Filters**. Use **Fetch Products & Map by SKU** for existing Shopify products. |
| Inventory does not update | Confirm **Enable Inventory Sync** is ticked, **Warehouse Mapping** is complete, and the item has Shopify product and variant IDs. Use **Sync > Sync Inventory** and review **NexWave Shopify Log**. |
| Inventory sync skips an item with a mapping conflict | Open the item, review **Shopify Stores** rows for this store, and correct rows pointing at the wrong Shopify product, variant, or inventory item. Then run **Sync > Sync Inventory**. |
| A multi-variant product updates the wrong Shopify variant | Confirm each variant has its own **Shopify Stores** row with the correct **Shopify Product ID** and **Shopify Variant ID**. Run **Fetch Products & Map by SKU** if mappings came from existing Shopify products. |
| Shopify returns an inventory API version error | Check **NexWave Shopify Log**, confirm Inventory read and write permissions, and rerun **Test Connection**. NexWave uses a compatible inventory API for stock updates without requiring a store setting change. |
| Only recently changed items update during scheduled inventory sync | Check **Inventory Sync Mode**. **Changed Bins** is incremental; use **Sync > Sync Inventory** for a full refresh, or switch to **Full Inventory** if every scheduled run should review all mapped items. |
| Shopify quantity is lower than physical stock | Check reserved stock in NexWave. Inventory sync sends available-for-sale quantity, which is physical stock less stock reserved for Sales Orders. If **Reserve Stock for Draft Orders** is ticked, active draft Shopify order reservations are also subtracted. |
| Shopify can sell stock that is already committed to a draft Shopify order | Confirm **Reserve Stock for Draft Orders** is ticked, the draft order imported as a draft **Sales Order**, the item has a warehouse, and stock reservation is enabled for the site. Run **Sync > Sync Inventory** after checking the draft order. |
| **Last Inventory Sync** does not change after a failed run | Review **NexWave Shopify Log**. The timestamp updates only when the run makes progress, so a fully failed run leaves the last successful timestamp unchanged. |
| A webhook event should be disabled temporarily | Untick the relevant **Webhook Events** option, save, then click **Register Webhooks** so Shopify receives the updated registration. |

## Related Documentation

* [Shopify Integration](/doc/0f2cd59e-8943-4d55-b4ff-522c760c01bb): feature overview and data flows.
* [Selling](/doc/9611c59c-fa49-4d68-ae8d-435ff4e26eed): Sales Order management.
* [Stock](/doc/42e81da0-a3bc-4f24-a596-63df62a260ae): inventory management.