Complete Documentation

Detailed installation and configuration guide for the Shopify Integration module

Table of Contents

1. Introduction

This guide explains step by step how to configure the Shopify integration for Dolibarr. We detail exactly where to find each value needed for configuration.

What you will learn: Where all configuration values come from and how to obtain them precisely.

What's New in v2.0.24

This version brings major improvements for smoother and more automated integration.

New Features

Automatic Historical Order Import

The CRON system can now automatically import your historical orders during the first synchronization, automatically creating associated customers.

Intelligent CRON Auto-Activation

CRON tasks automatically activate as soon as product and order configurations are complete, and deactivate if configuration becomes incomplete to prevent API errors.

Critical Fixes

Issues Resolved:
  • Manual Synchronization: Fixed case where interface displayed products but couldn't synchronize them
  • Service Management: Services are now correctly identified and synchronized as such (requiresShipping: false)
  • Unified Parameters: Consistent parameter handling between search and synchronization interfaces
  • SKUs with Leading Zeros: Proper preservation of leading zeros in product references

Security Improvements

Secure Installation: CRON tasks are now disabled by default during installation to prevent premature API calls. They activate automatically once configuration is complete.

2. System Prerequisites

Dolibarr & Server

Component Required Version Verification
PHP 7.2.5 to 8.3.16 Dolibarr Menu → Home → System Information
Dolibarr 19.0 to 21.x Dolibarr Menu → Home → Version
cURL Extension Enabled Dolibarr Menu → Home → System Information → PHP Extensions
JSON Extension Enabled Dolibarr Menu → Home → System Information → PHP Extensions

Shopify

3. Module Installation

Step 1: Purchase and Download

  1. Purchase the module on Dolistore
  2. Download the ZIP file from your Dolistore account
  3. Do not unzip the file

Step 2: Installation in Dolibarr

  1. Log in to Dolibarr as administrator
  2. Go to Home → Setup → Modules/Applications
  3. Click on "Deploy/Install external module/application"
  4. Select your downloaded ZIP file
  5. Click "Send file"
  6. Enable the module in the list of available modules
Important: Enable these required Dolibarr modules before continuing:
  • Products/Services
  • Third parties (Customers/Suppliers)
  • Customer orders
  • Customer invoices
  • Stocks
  • Shipments

4. Creating Shopify Application

Crucial step: You must create a private application in Shopify to obtain access keys.

Step 1: Access Applications

  1. Log in to your Shopify admin
  2. In the left menu, click on "Apps"
  3. Click on "Develop apps" (or "App and sales channel settings")
  4. If this is your first app, click "Allow custom app development"

Step 2: Create Application

  1. Click "Create an app"
  2. App name: Dolibarr Integration
  3. Developer email: your email
  4. Click "Create app"

Step 3: Configure Permissions

Click "Configure Admin API scopes" and enable these permissions:

Scope Permission Justification
read_products Read Read Shopify products
write_products Write Create/modify products
read_orders Read Read orders
write_orders Write Modify orders
read_customers Read Read customer data
write_customers Write Create customers
read_inventory Read Read stock
write_inventory Write Update stock
read_locations Read Read locations

Click "Save" after selecting all scopes.

Step 4: Install Application

  1. Click "Install app"
  2. Confirm installation
  3. The app is now installed and you can retrieve the tokens

5. Shopify Configuration - Where to Find Each Value

Now that your application is created, here is exactly where to retrieve each value:

Dolibarr Field Where to Find the Value in Shopify Exact Format Example
Shopify Store Hostname * Your store URL (address bar) mystore.myshopify.com
(WITHOUT https://)		 test-store.myshopify.com
Shopify Access Token * Apps → Develop apps → [Your app] → API access tokens → "Admin API access token" shpat_xxxxxxxxxxxxxxxxxxxxxxxx shpat_1a2b3c4d5e6f7g8h9i0j
Shopify API Key * Apps → Develop apps → [Your app] → API credentials → "API key" Alphanumeric string abc123def456ghi789
Shopify API Secret Key * Apps → Develop apps → [Your app] → API credentials → "API secret key" Secret alphanumeric string shpss_xyz789abc123def456
Shopify Location ID * Settings → Locations → Copy the ID of your main location Integer number 123456789
Shopify Vendor Your brand/company name (optional) Free text My Store
Pay attention to formats:
  • Hostname: WITHOUT "https://" at the beginning
  • Access token: Usually starts with "shpat_"
  • Secret key: Usually starts with "shpss_"
  • Location ID: Numbers only, no text

How to Retrieve Location ID

  1. In Shopify Admin, go to Settings → Locations
  2. Click on your main location (usually the one with your address)
  3. The ID is found in the URL: .../locations/123456789
  4. Copy only the numbers: 123456789

6. Dolibarr Configuration - Automatic and Manual Parameters

Field How to Obtain the Value Notes
Dolibarr API Key * Automatically generated by the module If you don't have one: Menu → Users & Groups → [Your user] → API Tab → Generate
Dolibarr Host URL * Automatically detected Ex: https://yourdomain.com/dolibarr
Dolibarr Product Category * Menu → Products/Services → Categories → Select your category Only products in this category will be synchronized

Synchronization Parameters

Parameter Recommended Value Explanation
Maximum orders per sync 10 Limits the number of orders processed each time
Products per cron cycle 10 Number of products updated per automatic cycle

7. Product Synchronization Configuration

Available Synchronization Options

Option Description Recommendation
Synchronize prices Sends Dolibarr prices to Shopify Enabled - Essential for e-commerce
Price level (if multiprice) Which Dolibarr price level to use Level 1 generally
Synchronize descriptions Sends product descriptions Enabled - Important for SEO
Synchronize images Sends product images Enabled - Essential
Synchronize stock Updates stock quantities Enabled - Prevents overselling
Use virtual stock Real stock - orders + supplier orders Enabled - More accurate
Tip: Enable all options for complete synchronization. You can disable them individually later if needed.

8. Order Synchronization Configuration

Required Parameters

Field Where to Configure in Dolibarr Example
Order prefix Free text (ex: SHOP-) SHOP-
Order origin Menu → Setup → Dictionaries → Origin of commercial proposals/orders Internet
Payment terms Menu → Setup → Dictionaries → Payment terms Payment on receipt
Default shipping method Menu → Setup → Dictionaries → Shipping methods Colissimo
Shipping product Menu → Products/Services → Create a "Shipping" service Service with ref PORT001
Default warehouse Menu → Stocks → Warehouses Your main warehouse
Bank account Menu → Bank → Financial accounts Your main account

Create the "Shipping" Product

  1. Menu → Products/Services → New product/service
  2. Type: Service
  3. Reference: SHIPPING
  4. Label: Shipping
  5. Price: 0 (will be calculated automatically)
  6. Click Create

8.1. Historical Order Import v2.0.24

Import all your previous Shopify orders automatically during the first module configuration.

New Feature: Historical import now uses intelligent pagination to process thousands of orders without limitation and automatically resumes if interrupted.

Configuration Fields

Field Description
Enable historical import Enables automatic import of previous Shopify orders during the next CRON execution. Automatically unchecks after successful import to prevent duplicates.
Import start date Date from which to import historical orders (leave empty to import from beginning)
Import end date Date until which to import historical orders (leave empty to import until today)
Historical import completed Indicates if historical import has been performed. Once completed, only new orders will be imported

How it Works

  1. Enable historical import and optionally define a date range
  2. System automatically processes orders in batches of 10-50 according to your configuration
  3. If interrupted by time limit, import automatically resumes at next CRON
  4. Once completed, import automatically disables to prevent duplicates
Automatic Pagination: The system automatically traverses all available order pages, even on large catalogs.
For large initial imports: Monitor Dolibarr logs to track progress.

9. Automatic Tasks Configuration (Cron)

Important: Cron tasks are disabled by default for security. You must enable them manually.

Tasks to Configure

Task Recommended Frequency Description
Product synchronization Every hour Updates products and stock
Order import Every 15 minutes Retrieves new Shopify orders

Activating Cron Tasks

  1. Menu → Tools → Scheduled jobs
  2. Search for "ShopifyIntegration" tasks
  3. For each task:
    • Click Edit
    • Enable "Status: Enabled"
    • Configure frequency
    • Click Edit
Test: You can test a task by clicking the "Run now" button next to each task.

10. Module Update

How to update the Shopify Integration module to a new version from the DoliStore.

Important: The deactivation/reactivation procedure is mandatory for SQL update scripts to execute correctly.

Update Procedure

1. Download the New Version

  1. Go to the DoliStore
  2. Log in with your account
  3. Download the latest version of the module (ZIP file)
  4. Save the ZIP file on your computer

2. Disable Current Module

  1. In Dolibarr: Menu → Setup → Modules/Applications
  2. Search for "Shopify Integration"
  3. Click "Disable" (red button)
  4. Confirm deactivation

3. Install the New Version

  1. Stay in Menu → Setup → Modules/Applications
  2. Click on "Deploy/Install external module"
  3. Click "Browse" and select the downloaded ZIP file
  4. Click "Send file"
  5. Follow the installation instructions

4. Reactivate Module

  1. Once installation is complete, search for "Shopify Integration"
  2. Click "Enable" (green button)
  3. Verify that the displayed version number matches the new version
  4. SQL update scripts execute automatically during reactivation
Verification:
  • The version number displayed in the module list should match the new version
  • Check Dolibarr logs to ensure SQL scripts executed without errors
  • Test main functionalities (manual sync, configuration)

Alternative Method: Via DoliStore Tab

Quick alternative: You can also try the "Modules available from DoliStore" tab which sometimes allows direct automatic updates, but the method above is more reliable.
In case of problems: Restore the backup of the old folder and contact support. Never leave the module in a partially updated state.

11. Common Troubleshooting

Shopify Connection Errors

Error: "Connection failed" or "Access denied"
Cause: Incorrect API information
Solution:
  • Check hostname (without https://)
  • Regenerate Shopify access token
  • Verify app is properly installed
  • Check all necessary scopes

Products Not Synchronized

Error: "No products synchronized"
Cause: Category or status problem
Solution:
  • Check that your products are in the correct category
  • Product status = "For sale"
  • Product not archived

Orders Not Imported

Error: "No orders found"
Cause: Incomplete configuration
Solution:
  • Complete all required fields in the "Orders" tab
  • Verify bank account exists
  • Create the "Shipping" product

Where to Find Logs

Menu → Tools → Dolibarr Log Search for: "ShopifyIntegration"

Technical Support

If you cannot resolve your problem:

🎉 Congratulations!

Your Shopify-Dolibarr integration is now configured. You can test synchronization via the manual synchronization interface.

Back to Home Rate the Module