Complete Documentation

Detailed installation and configuration guide for the Shopify Integration module

Table of Contents

0. Getting a License

Step 1: Install the Doli2Shop App

Go to doli2shop.ptitetete.org/shopify-app/ and install the application in your Shopify store.

Step 2: Choose Your Subscription

  • Annual (recommended): €250 excl. VAT/year - Save €50
  • Monthly: €25 excl. VAT/month - No commitment
Already a DoliStore Customer?
Choose "I already have a license" and enter your serial number (SI-XXXX-XXXX-XXXX) to continue using your existing license until it expires.

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 18.0 to 22.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. Installing the Doli2Shop Application in Shopify

New! Official Shopify Application - Doli2Shop now uses an official partner application, simpler and more secure than the old private applications.

Why a Shopify Application?

Using an official Shopify partner application offers several major advantages:

  • 🔐 OAuth 2.0 Security: Secure authentication compliant with Shopify standards, without sharing sensitive API keys
  • ✅ Shopify Compliance: Application verified and approved by Shopify, meeting all their security requirements
  • 🚀 Simplified Installation: Just a few clicks from the Shopify App Store, no complex technical configuration
  • 🔄 Automatic Updates: Permissions and features are automatically kept up to date
  • 📊 Full API Access: All necessary permissions are pre-configured (products, orders, customers, inventory)

Video Installation Tutorial

Watch this video to see the complete step-by-step installation process:

Watch Installation Tutorial

Installation Steps

Step 1: Access the Shopify App Store

  1. Log in to your Shopify admin
  2. In the left menu, click on "Apps"
  3. Click on "Shopify App Store" or search directly in the store
  4. Or access directly via this link: Doli2Shop on the Shopify App Store

Step 2: Find and Install Doli2Shop

  1. Search for "Doli2Shop - ERP Integration" in the App Store
  2. Or use the direct link provided by support
  3. Click "Add app"
  4. Accept the requested permissions (products, orders, customers, inventory)

Step 3: Configuration in the Application

  1. Once the app is installed, follow the setup wizard
  2. Enter your Dolibarr URL (e.g., https://yourdomain.com/dolibarr)
  3. The application automatically generates your API credentials
  4. Carefully note the displayed information:
    • Access Token (starts with shpat_...)
    • API Key
    • API Secret

Step 4: Enter Information in Dolibarr

  1. Go back to Dolibarr → ShopifyIntegration → Configuration
  2. Paste the obtained information in the corresponding fields
  3. Click "Save"
Important: The Access Token is only displayed once during installation. If you lose it, you will need to uninstall and reinstall the application to get a new one.

Automatically Configured Permissions

The Doli2Shop application automatically configures all necessary permissions:

Scope Permission Usage
read_products / write_products Read/Write Product synchronization Dolibarr ↔ Shopify
read_orders / write_orders Read/Write Import Shopify orders to Dolibarr
read_customers / write_customers Read/Write Automatic customer creation
read_inventory / write_inventory Read/Write Real-time stock synchronization
read_locations Read Stock location management
read_fulfillments / write_fulfillments Read/Write Shipment synchronization

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

🚨 Missing Shopify Permissions - CRITICAL

Symptom: Orders haven't synchronized for several days, CRON returns an error (-1)
Cause: Missing WRITE permissions in your Shopify application
Quick Diagnostic:
  1. Go to ShopifyIntegration Menu → Configuration → System Diagnostic
  2. Check the "Shopify API Permissions" section
  3. If you see lines with status: "error" → Missing permissions!

📝 Required Permissions (9 minimum)

Permission Type Required Function
read_products READ ✅ YES Read products
write_products WRITE ✅ YES Create/modify products
read_inventory READ ✅ YES Read stock levels
write_inventory WRITE ✅ YES Update stock
read_orders READ ✅ YES Read orders
write_orders WRITE ✅ YES Modify orders
read_customers READ ✅ YES Read customers
write_customers WRITE ✅ YES Create customers
read_locations READ ✅ YES Read locations
write_publications WRITE ⚠️ Recommended Publish products to sales channels
write_files WRITE ⚠️ Recommended Synchronize images

🔧 Step-by-Step Correction Procedure

  1. Access your Shopify application:
    • Shopify Admin → Settings → Apps and sales channels
    • Click on "Develop apps"
    • Select your Dolibarr application
  2. Edit permissions:
    • "Configuration" tab
    • "Admin API access scopes" section → Click "Edit"
  3. Check ALL missing permissions (see table above)
  4. Save and reinstall:
    • Click "Save"
    • ⚠️ IMPORTANT: Click "Reinstall app" to activate new scopes
  5. Retrieve the new token:
    • "API credentials" tab
    • "Admin API access token" section
    • Click "Reveal token once" and copy it
    • ⚠️ You won't be able to see it again!
  6. Update Dolibarr:
    • ShopifyIntegration Menu → Configuration → Setup
    • "Shopify Access Token" field → Paste the new token
    • Click "Save"
  7. Verify the fix:
    • ShopifyIntegration Menu → Configuration → System Diagnostic
    • All permissions should show status: "ok"
    • Test manual order synchronization
⚠️ Common Mistake: Having only READ permissions is NOT sufficient! The module absolutely needs WRITE permissions to function correctly (create products, update stock, add notes to orders, etc.).
Complete Documentation: For more details, see the complete technical guide in /docs/troubleshooting/SHOPIFY_PERMISSIONS_EN.md of your installation.

Dolibarr API Endpoint Issues

Error: "Endpoint not found (404)" or "Bad Request (400)"
Possible causes:
  • API/Web Services module disabled: Menu → Configuration → Modules → Search "API" → Enable
  • Dolibarr version too old: Some endpoints require Dolibarr 14+
  • Insufficient user permissions: API user must have full rights
  • Missing test file: For documents/download, this is normal if no company logo exists

Configuring API User Permissions

  1. Menu → Configuration → Users & Groups
  2. Click on your API user
  3. "Permissions" tab
  4. Grant these minimal permissions:
    • ✅ API: Full API access
    • ✅ Documents: Read documents
    • ✅ Products/Services: Read products
    • ✅ Third parties: Read/create customers
    • ✅ Orders: Read/create orders
  5. Click "Save"
Important note: The 404 error on "documents/download" is normal if no company logo exists. This does not affect Shopify synchronization.

Explore and Test Dolibarr API

Dolibarr provides a built-in API explorer to test and document all available endpoints:

  1. Explorer URL: https://yourdomain.com/dolibarr/api/index.php/explorer
  2. Swagger documentation: https://yourdomain.com/dolibarr/api/index.php/explorer/swagger.json?DOLAPIKEY=your_api_key
  3. Replace yourdomain.com/dolibarr with your actual Dolibarr URL
  4. Replace your_api_key with your user API key

This tool allows you to:

  • ✅ Test all API endpoints live
  • ✅ View complete documentation for each endpoint
  • ✅ Check required and optional parameters
  • ✅ Diagnose API issues directly
Critical API parameters according to Swagger documentation:
  • GET /documents: modulepart parameter required (e.g.: product, company, user)
  • GET /documents/download: modulepart parameter required + original_file optional
  • GET /status: Basic endpoint (not documented in Swagger but functional)

Note: 400 (Bad Request) errors usually indicate missing or invalid parameters.

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