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.

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

4. Click Develop apps in Dev Dashboard.

Develop apps in Dev Dashboard button

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

Shopify Dev Dashboard Apps page

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

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

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

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

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

Step 2: Enter the Basic Store Details

Fill in these fields:

Shopify Store basic settings

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.

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

Step 2: Authorise the App in Shopify

1. Review the permissions requested by the app.

2. Click Install app.

Shopify app authorisation screen

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

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

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

Part 4: Configure Orders, Payments, and Tax

Order Settings

In Order Settings:

In Order Automation:

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:

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

Product and Item Sync Settings

In Item Sync Settings:

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.

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:

Inventory Settings with draft order stock reservation

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.

Shopify webhook event settings

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

Related Documentation

• Shopify Integration: feature overview and data flows.

• Selling: Sales Order management.

• Stock: inventory management.