# Shopify Integration

# Shopify Integration

The Shopify integration connects your Shopify online store(s) with NexWave, enabling multi-store management with automatic synchronisation of products, orders, inventory, and customer data.

## Key Differentiator: Multi-Store Architecture

Unlike single-store integrations, the NexWave Shopify connector is designed from the ground up for **multi-store operations**:

* Connect **multiple Shopify stores** to a single NexWave instance
* Each store maps to a specific **Company** for proper accounting separation
* Manage AU, NZ, US stores (or any regional stores) from one central system
* Independent configuration per store

 ![](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9iODcwZjE2OS05OWVkLTRjZTUtYjQyNi00MzRjYjk4OTg1NmIvbXVsdGktc3RvcmUtYXJjaGl0ZWN0dXJlLnN2ZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkyNjExOTAwLCJleHAiOjE3OTI2OTgzMDB9.2oZEKF-UleAWduK1M_cC_UYEDmulBY3pamPh6wWM4ic " =800x449")

## Data Flow Overview

 ![](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC8xYzYyNWMzYi0zZDlmLTRmZGEtYTYwMS04ZjlkNWMwODIxODkvZGF0YS1mbG93LnN2ZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkyNjExOTAwLCJleHAiOjE3OTI2OTgzMDB9.P2tP5qhNUdvIiVS4sO8QGHVkbCjvdWHNM45pIIeE6-0 " =800x515")

## Features Overview

### Item Synchronisation

**Direction:** NexWave → Shopify (Push Only)

* Push product data from NexWave Items to Shopify
* Flexible field mapping to Shopify standard fields or metafields
* Per-store field mapping configuration
* Automatic SKU assignment (item_code → SKU)
* Inventory tracking enabled for stock items

**Item Eligibility Control:**

* Manual override per item per store
* Automatic eligibility filters (e.g., "if AU RRP has value, sync to AU store")
* Filter types: Field Has Value, Field Equals, Field Not Empty

**For Existing Shopify Products:**

* SKU-based pre-mapping tool for migrations
* Fetch products from Shopify and match by SKU to NexWave items
* Migration report showing matched, unmatched, and conflicts

### Collection Mapping

* Map NexWave field values to Shopify Custom Collections
* Example: item_group "Outdoor" → Shopify Collection "Outdoor Living"
* Example: brand "Artisan" → Shopify Collection "Artisan Collection"
* Automatic collection assignment during item sync

### Order Synchronisation

**Direction:** Shopify → NexWave (Pull via Webhooks)

 ![](https://docs.nexwaveapp.com/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzL2YxMTg5ZTEzLTdlMTQtNDA1ZC04MDI1LWMxZmI0Y2Y2MTg0ZC9hZGE0OWQ1YS0wNGU2LTQxMzQtODUwMy1jZDg0YjU2NTE1ZDQvc2hvcGlmeS1vcmRlci1mbG93LnN2ZyIsInR5cGUiOiJhdHRhY2htZW50IiwiaWF0IjoxNzkyNjExOTAwLCJleHAiOjE3OTI2OTgzMDB9.Nv2Ke2fj4IFsTXCgacLNYUmG40qLWilyNCWFDGrKHcQ " =700x644")

* Webhook-based real-time order sync
* HMAC signature validation for security
* Store resolution via X-Shopify-Shop-Domain header
* Orders routed to correct Company based on store configuration
* Global customers (email-based lookup across stores)

**Order Automation Options:**

* Auto-submit Sales Order for paid orders
* Auto-create Sales Invoice (requires auto-submit)
* Auto-create Payment Entry (requires auto-create invoice)
* Configurable Cash/Bank account for payment entries

**Custom Fields on Sales Order:**

* Shopify Store reference
* Shopify Order ID
* Shopify Order Number
* Financial Status
* Fulfillment Status

### Tax Handling

The connector uses an **"On Net Total"** approach for tax calculation, which provides cleaner tax rows and handles large orders efficiently.

**How It Works:**


1. **Single GST Row** - Instead of creating a tax row per line item, a single "On Net Total" GST row is created at the order level
2. **Zero-Rated Detection** - Items marked as non-taxable in Shopify (taxable=false or empty tax_lines) are automatically detected
3. **Item Tax Templates** - Zero-rated items can have an Item Tax Template applied for proper GST/BAS reporting
4. **Multi-Region Support** - Handles different tax rates automatically (e.g., NZ 15% GST, AU 10% GST)

**Tax Calculation Flow:**

| Step | Description |
|------|-------------|
| 1\. Detect tax types | Collect unique tax titles and rates from the order |
| 2\. Apply item templates | Zero-rated items get Item Tax Template or item_tax_rate override |
| 3\. Create tax rows | Single "On Net Total" row per tax type |
| 4\. Handle shipping | Add as line item (taxed via On Net Total) or as separate tax row |
| 5\. Rounding adjustment | Apply write-off for any small discrepancies |

**Shipping Options:**

* **As Line Item** - Shipping added as an item, taxed via the On Net Total GST row
* **As Tax Row** - Shipping added as an "Actual" tax row with separate GST on shipping

**Rounding Adjustments:**

Due to differences in tax calculation between Shopify and NexWave (especially with tax-inclusive pricing), small discrepancies may occur. The connector automatically applies a rounding adjustment using:


1. Store-level **Write Off Account** (if configured)
2. Company's default Write Off Account (fallback)

**Tax Configuration Options:**

| Setting | Description |
|---------|-------------|
| Tax Account | NexWave account for the tax |
| Sales Taxes and Charges Template | Predefined template for consistent calculation |
| Zero-rated Item Tax Template | Template for zero-rated items (GST/BAS compliance) |
| Write Off Account | Account for rounding adjustments |

### Fulfillment Synchronisation

**Direction:** Shopify → NexWave (Pull via Webhooks)

* Webhook-based fulfillment sync (`orders/fulfilled`, `orders/partially_fulfilled`)
* Automatic Delivery Note creation when orders are fulfilled in Shopify
* Duplicate prevention - checks for existing Delivery Notes before creating
* Partial fulfillment support - option to create DNs for remaining quantities
* Tracking information captured from Shopify fulfillment data

### Customer & Address Handling

* Customer lookup by shopify_customer_id first, then by email
* Addresses deduplicated by content (title, address_line1, city, country)
* Both billing and shipping addresses set on Sales Order
* Global customer base across all connected stores

### Inventory Synchronisation

**Direction:** NexWave → Shopify (Push)

* Push stock levels from NexWave warehouses to Shopify locations
* Warehouse-to-Location mapping per store
* Multi-location support within Shopify
* Configurable sync frequency per store
* Real-time stock updates to prevent overselling

## Multi-Store Use Cases

### Regional Stores

| NexWave Company | Shopify Store | Currency |
|-----------------|---------------|----------|
| Company AU      | store-au.myshopify.com | AUD      |
| Company NZ      | store-nz.myshopify.com | NZD      |
| Company US      | store-us.myshopify.com | USD      |

### Brand Stores

| NexWave Company | Shopify Store | Brand |
|-----------------|---------------|-------|
| Brand A Ltd     | brand-a.myshopify.com | Brand A |
| Brand B Ltd     | brand-b.myshopify.com | Brand B |

## Custom Fields Added

The integration adds custom fields to track Shopify data:

| DocType | Fields Added |
|---------|--------------|
| Item    | shopify_stores (table linking items to stores) |
| Customer | shopify_customer_id |
| Sales Order | shopify_store, shopify_order_id, shopify_order_number, shopify_financial_status, shopify_fulfillment_status |
| Sales Order Item | shopify_item_discount |
| Delivery Note | shopify_store, shopify_order_id, shopify_order_number |
| Sales Invoice | shopify_store, shopify_order_id, shopify_order_number |

## Data Flow Summary

| Data | Shopify → NexWave | NexWave → Shopify |
|------|-------------------|-------------------|
| Products/Items | \-                | ✓ (push)          |
| Product Fields/Metafields | \-                | ✓                 |
| Collections | \-                | ✓ (mapping)       |
| Stock Levels | \-                | ✓                 |
| Orders | ✓ (webhooks)      | \-                |
| Fulfillments | ✓ (webhooks)      | \-                |
| Customers | ✓                 | \-                |
| Addresses | ✓                 | \-                |
| Tax  | ✓                 | \-                |

## Store Configuration Options

Each Shopify Store in NexWave can be configured with:

* **Authentication** - Shop domain and OAuth credentials (or legacy access token)
* **Company Mapping** - Which NexWave company receives orders
* **Warehouse Mappings** - NexWave warehouses to Shopify locations
* **Field Mappings** - Item fields to Shopify fields/metafields
* **Collection Mappings** - NexWave values to Shopify collections
* **Item Filters** - Auto-eligibility rules for items
* **Tax Mappings** - Shopify tax titles to NexWave accounts, templates, and write-off account
* **Order Settings** - Auto-submit, auto-invoice, payment accounts
* **Webhook Events** - Control which events are processed

## Permissions

| Role | Access Level |
|------|--------------|
| Sales Manager | Full access (create, edit, delete, import/export) |
| Sales User | Read-only + reports |
| Accounts Manager | Read-only + reports |
| Accounts User | Read-only + reports |
| System Manager | Full administrative access |

## Related Documentation

* [Shopify Connector Setup Guide](/doc/a96a8585-f913-422b-ae90-c27568ca0e3a) - Guide on setting up Shopify connector on NexWave
* [Selling](/doc/9611c59c-fa49-4d68-ae8d-435ff4e26eed)  - Sales Order management in NexWave
* [Stock](/doc/42e81da0-a3bc-4f24-a596-63df62a260ae)  - Inventory management
* [Accounting](/doc/85b00666-859d-4e2b-9bac-6c1dd3848464)  - Financial management

---

**Documents**

- [Shopify Connector Setup Guide](https://docs.nexwaveapp.com/s/docs/doc/shopify-connector-setup-guide-hpVraqmSVk)