Installation guide
From the package to a Shopify store that is connected, licensed and synchronised: prerequisites, connection, licence, settings, scheduled jobs
Download the PDFThis guide takes you from nothing to a Shopify store connected to Dolibarr, with an active licence and the synchronisations set up. It applies to Doli2Shop 2.6.3 and later. Allow an hour, ten minutes of it on the Shopify side. The screenshots show a fictitious demonstration store: the names, domains and numbers you see on your own system will be yours.
The steps, in order:
- the prerequisites;
- installing the package and activating the module;
- connecting the Shopify store;
- the licence;
- the configuration wizard;
- the synchronisation direction;
- stock (real or virtual) and the Shopify location;
- the scheduled jobs;
- the final checks;
- what happens when the licence ends.
1. Prerequisites
| Item | Requirement |
|---|---|
| Dolibarr | version 18 to 24 |
| PHP | 7.4 at minimum. The ceiling depends on your Dolibarr: PHP 8.1 at most with Dolibarr 18, PHP 8.5 at most with Dolibarr 23 and 24 |
| Database | MySQL 5.7 or later, or MariaDB 10.3 or later |
| Dolibarr address | over HTTPS (mandatory: Shopify refuses to send the connection back to an HTTP address) |
| Dolibarr account | an administrator account: the module's screens are reserved for it |
| Shopify | a store, and an account allowed to install an application on it |
| Scheduler | the Dolibarr "Scheduled jobs" module enabled, with its system trigger in place (see section 8) |
Doli2Shop relies on the Dolibarr modules Products, Third parties, Customer orders, Stock and Categories: Dolibarr enables them along with it if they are not already on.
2. Install the package and activate the module
You received a .zip file (DoliStore confirmation email).
There are two ways to install it.
From Dolibarr. Go to Home → Setup →
Modules/Applications, open the Deploy/install external
app/module tab and drop the .zip file. If Dolibarr
refuses (installation from the application locked, or
custom folder not declared), use the second way.
By hand. Unzip the archive into the
htdocs/custom/ folder of your server: you must end up with
htdocs/custom/doli2shop/. Dolibarr's
conf/conf.php file must declare this folder:
$dolibarr_main_url_root_alt='/custom';
$dolibarr_main_document_root_alt='/path/to/htdocs/custom';
Then activate the module:
- Go back to Home → Setup → Modules/Applications.
- Type
doli2shopin the search field. - On the module's tile, switch the toggle to "active".
- Click the gear icon on the tile to open the configuration.
The module has no entry in Dolibarr's left-hand menu: the gear in this list is always your way in. You land on a row of tabs; the first one is Wizard.
3. Connect the Shopify store
You can connect the store in two ways that lead to the same result: from the Wizard tab (step 1), or from the Stores tab.
Before the connection, step 1 shows Not connected and the Connect my Shopify store button. In the Stores tab, the equivalent button is called Connect a store (via Shopify).
- Click the button. If your Dolibarr is not on HTTPS, the module
refuses and says so: fix the address
(
$dolibarr_main_url_rootinconf/conf.php) before trying again. - You leave Dolibarr for a page on doli2shop.ptitetete.org that announces four steps. Click "Install Doli2Shop".
- At Shopify: sign in to your account, pick the store if you have several, read the requested permissions and approve them. Shopify displays these permissions itself; check that the browser address really is Shopify's before approving. The application is also presented at https://apps.shopify.com/doli2shop.
- Shopify sends you back to Dolibarr automatically. The module saves the store's credentials, detects its stock location and registers the webhooks (the notifications Shopify sends to Dolibarr). A message "Successfully connected to your-store.myshopify.com!" confirms it.
To check: in the Stores tab, the store is listed with its Shopify domain; in the wizard, step 1 shows Connected to followed by the domain, with the connection date and the location identifier. To reconnect a store (expired token, changed permissions), use the reconnect button on the same row or in step 1: the configuration already done is kept.
4. Activate the licence
The licence is managed store by store.
- In the Stores tab, click Edit on the store's row, then the License sub-tab.
- Under Activate a DoliStore License, enter your
serial number, in the format
SI-YYYY-XXXX-XXXX(the one in the DoliStore confirmation email; letters are turned into capitals automatically), then click Activate this license. The module needs the store's Shopify domain: a store that is not connected yet (section 3) cannot receive a licence. - The message "DoliStore license activated successfully" confirms the activation and License status switches to Licence valid.
- At any time, Verify now queries the licence server and updates the status and the date of the last check.
Good to know:
- Trial. A trial is a short-lived
SI-…serial number issued by the maintainer: it is activated exactly like a normal licence, and ends like one (section 10). - Default store. The first connected store is the default store. As long as the licence server announces no stop date, it is not blocked: the Health screen shows it as Exempt (default store) and this sub-tab carries the never blocked mention. Read that mention together with section 10: once the stop date announced by the server has passed, the default store stops like any other.
- Community edition. The Community edition, free and published under an open licence, contains no licence system: it works without a key, the Health screen shows Community edition (free) and technical support is reserved for members.
- Licence server unreachable. The module shows Unable to verify your license right now and retries by itself. For the default store, synchronisation continues as long as the last successful check is less than 14 days old (default delay); after that it stops until the server is back. A secondary store is only synchronised when its licence could be verified: a long server outage pauses it, and it resumes by itself afterwards.
- Never verified. A default store whose licence has never been successfully verified is not blocked, even if the server stays unreachable.
5. The configuration wizard
The Wizard tab has six steps. It remembers the step you were at, and a button lets you start over.
| Step | Title | What you set there |
|---|---|---|
| 1 | Shopify Connection | the connection described in section 3 |
| 2 | Dolibarr Setup | Default warehouse and CRON / Webhook user (mandatory), then Shopify customer category and Third-party type mapping B2B/B2C |
| 3 | Orders | the order prefix, the delivery delay, Order Origin, Payment Terms, the bank account for payments and the automatic processing (shipment orders, invoices, payments) |
| 4 | Shipping | Shipping Methods Mapping, per store |
| 5 | Payment | Payment Methods Mapping, per store |
| 6 | Activation | the final check, enabling the webhooks and the scheduled jobs |
Points to watch:
- In step 2 the warehouse is essential: without a default warehouse, stock is not decremented when a Shopify order arrives, and nothing tells you. These settings are shared by all stores; they can only be changed from the default store.
- In steps 4 and 5 the mappings belong to each store. If you have several, first pick the store in the Configure store selector, then set its mappings.
- In step 6 the module checks the connection, the warehouse and the user, and shows Registered webhooks and Active CRONs. The Activate webhooks and Activate CRONs buttons fix an incomplete counter; Finish configuration closes the wizard, flagging what is still missing.
6. The synchronisation direction
The Sync Directions tab decides, data type by data type, who writes to whom.
The first five rows (Products Synchronization, Orders Synchronization, Payments Synchronization, Shipping Synchronization and Stocks Synchronization) are set by a direction: Shopify to Dolibarr, Dolibarr to Shopify or Bidirectional. No synchronization is only offered outright for products; for orders, payments, shipments and stocks it appears only if that setting is already saved. The sixth row, Conflict Resolution Strategy, is not a direction: it offers five strategies to settle which side wins when the same data changed on both sides (Shopify first, Dolibarr first, most recent change, oldest change, or manual resolution).
What to know before saving:
- Stocks: as long as nothing has been saved on this screen, the direction shown and applied is Dolibarr to Shopify. Dolibarr is the source of truth for stock (replenishment, production, inventory) and Shopify does not write to it.
- Products: there is no preselected direction. The list shows Select synchronization direction: pick a direction, then save. As long as you do not pick one, none is saved.
- Orders, payments, shipments: only the Shopify to Dolibarr direction works. The Dolibarr to Shopify direction is not implemented yet for these three types: a setting that includes it is saved but has no effect, and the screen announces it with a warning. For shipments, the direction shown by default is Bidirectional: choose Shopify to Dolibarr.
- Payments and shipments depend on orders: do not turn off order synchronisation if you want the others.
Click Save at the bottom of the screen to validate the six rows.
7. Real or virtual stock, Shopify location
These settings belong to each store: first pick the store concerned in the store selector displayed at the top of the screen.
Real or virtual. In the Product Sync tab, the Synchronize Stocks box enables sending stock to Shopify. The Use Virtual Stock for Shopify box, which can only be ticked if the first one is, sends Shopify the virtual stock (real stock, minus customer orders, plus supplier orders) instead of the real stock. Virtual stock is recommended: it avoids selling what is already promised.
Location. Shopify manages stock per location. The module detects the location when connecting (section 3). To check or change it: Stores tab, Edit on the store's row, Shipping sub-tab, Shopify location ID field. The identifier is found in the Shopify admin, in the locations settings.
8. The scheduled jobs
Doli2Shop works mostly through Dolibarr scheduled jobs. They are
under Home → Admin Tools → Scheduled jobs; filter on
the doli2shop module.
Dolibarr only runs these jobs if its scheduler is itself triggered
regularly (a crontab line on the server). The command to
use is displayed in the configuration of the "Scheduled jobs" module
(the gear on its tile, in the module list). Without this trigger nothing
runs, even if the jobs are "scheduled".
Active from installation:
| Job | Role |
|---|---|
Doli2ShopWebhookProcess |
processes the webhooks received from Shopify |
Doli2ShopOrdersCatchup |
catches up orders a webhook may have missed |
Doli2ShopFulfillmentCatchup |
catches up missed shipments |
Doli2ShopStockPushQueueProcess |
sends stock changes to Shopify |
Doli2ShopTokenRefresh |
renews the connection token before it expires |
Doli2ShopWebhookHealthCheck |
checks the webhooks and re-registers them if needed |
Doli2ShopHeartbeat |
daily report of the module's metrics |
Product jobs. Doli2ShopProductsExport and
Doli2ShopProductsImport are inactive at installation. Since
version 2.6.3, saving the products direction (section 6) sets these two
jobs according to the chosen direction, for stores that are connected
and licensed. This only happens when the expected state changes, and a
job you paused on purpose is never re-enabled. After saving, check their
state in the scheduled jobs list: the screenshot shows a connected,
licensed demonstration store where they are already scheduled.
To enable by hand as needed (inactive at installation):
| Job | Enable if |
|---|---|
Doli2ShopOrdersHistoricalImport |
you import the order history of a store already in service |
Doli2ShopHistoricalCleanup |
you started that historical import (clean-up afterwards) |
Doli2ShopAlertCheck |
you want email alerts on repeated errors |
9. Check the installation
The Health & Diagnostic tab gathers the checks. It includes Per-store summary (connection, active webhooks, licence status of each store), System checks, Module status, Shopify API connectivity and Scheduled jobs. A coloured badge on the tab flags a degradation.
Go through it after installing: Shopify connection successful, webhooks active, jobs active, no missing right. If in doubt, the "Sending the module log and JSON exports to support" procedure (https://doli2shop.ptitetete.org/en/documentation/support-export) tells you what to send us.
To connect the module to an already populated Dolibarr (existing products, third parties and orders), follow the "Go-live procedure" (https://doli2shop.ptitetete.org/en/documentation/go-live) before enabling the synchronisations.
10. When the licence ends
What follows describes the default store. A secondary store has no grace period: it is only synchronised while its licence is valid, and its synchronisation stops as soon as it is no longer valid.
- Expired licence: degraded mode. The module shows Your license has expired!. Synchronisation keeps working, but support and downloads are disabled.
- Sixty days of grace. After expiry, synchronisation keeps going for 60 more days. The module then shows Synchronization will stop soon and, when the licence server provides the date, the day everything will stop. Without that date, no stop day is shown.
- Stop. Once the date has passed, Synchronization stopped (license) is shown: all synchronisation with Shopify stops, including the retrieval of orders. Your Shopify orders no longer arrive in Dolibarr until the licence is renewed.
Renew your licence before the stop: synchronisation resumes as soon as the new licence is activated (section 4). If no licence has ever been linked to a store, the module says so with No license is linked to this store.