Shopify Store Management

Shopify Store Management connects a Shopify store to Odoo. This page is the installation and configuration guide for the module you downloaded from your ECOSIRE dashboard. Everything below describes the shopify_store_management module as it ships today.

Technical name	shopify_store_management
Odoo versions	17.0, 18.0, 19.0 (Community or Enterprise)
Current shipped version	17.0 → 17.0.1.0.2, 18.0 → 18.0.1.1.2, 19.0 → 19.0.2.0.0
Price	$499 USD — one-time, per Odoo version
Odoo module licence	LGPL-3
Category	Connector

Licences are bound to one Odoo major version

A licence issued for Odoo 17 unlocks only the 17.0 download and only validates on an Odoo 17 database. It will not activate on 18 or 19, and the 18.0/19.0 ZIPs will not appear in your dashboard. Buy the version you actually run — and if you later upgrade Odoo, you need the licence for the new version. This is enforced on both the download and the activation paths, so there is no way round it.

Requirements

Requirement	Detail
Odoo	17.0, 18.0 or 19.0, Community or Enterprise. Self-hosted or Odoo.sh — Odoo Online (SaaS) cannot install third-party modules
Odoo apps	base, sale_management, stock, account, delivery, mail, web, portal, product, contacts, digest — Odoo installs any that are missing
ECOSIRE dependency	ecosire_license_client — a separate free download, not bundled in this ZIP. See step 3
Python packages	requests
Platform account	A Shopify seller/partner account with API access
Licence	An active ECOSIRE licence for this module and your Odoo version

Install the Python packages into the same interpreter that runs Odoo:

sudo -u odoo pip install requests

Installation

1. Download the ZIP for your Odoo version

Sign in at ecosire.com and open your dashboard downloads. You will only be offered the file matching your licence's Odoo version — that is expected, see the warning above.

2. Extract into your addons path

unzip shopify_store_management_v19_*.zip -d /opt/odoo/addons/
ls /opt/odoo/addons/shopify_store_management/__manifest__.py   # sanity check

The archive contains a single top-level shopify_store_management/ directory. If your ls check fails, the module folder ended up one level too deep — move it up so __manifest__.py sits directly inside shopify_store_management/.

3. Install the ECOSIRE licence client

shopify_store_management declares ecosire_license_client as a hard dependency. It is a separate, free module and it is not bundled in the connector ZIP — Odoo will refuse to install the connector until the licence client is present in your addons path. Download it from your ECOSIRE dashboard alongside the connector and extract it the same way:

unzip ecosire_license_client_v19_*.zip -d /opt/odoo/addons/

4. Restart Odoo and install

sudo systemctl restart odoo

1. Go to Apps and click Update Apps List (developer mode must be on).
2. Search for Shopify Store Management and click Install.
3. Odoo pulls in ecosire_license_client and the Odoo apps listed above automatically.

When the install finishes, a Shopify menu appears in the main Odoo app switcher.

Activate your licence

How to obtain a licence key

The steps below activate a key you already hold. This is how you get one in the first place.

1. Create an ECOSIRE account at ecosire.com, using the email address you want the licence issued to. Your keys and your downloads both live in that account's dashboard.
2. Buy the module — either directly on ecosire.com, or from the Odoo App Store.
3. Bought on ecosire.com? The key is issued to your dashboard automatically once the order completes. Nothing else to do.
4. Bought on the Odoo App Store? Send us proof of purchase: email [email protected] from the same address as your ecosire.com account, with the Odoo sales-order slip or order reference (the purchase receipt Odoo emails you at checkout). The App Store does not tell ECOSIRE who bought what, so this is how we match your purchase to your account.
5. We issue the key to your dashboard, next to the ZIP for your Odoo version, in the form ECO-XXXX-XXXX-XXXX.

One licence, one Odoo major version

The key is issued against the Odoo major version you bought — see the warning at the top of this page. Tell us which version you run when you send proof of purchase, so we issue the right one.

Before you activate

Set your instance's public URL first. The licence is bound to the domain derived from web.base.url, so activating with a placeholder value binds the licence to the wrong host:

1. Turn on developer mode.
2. Settings → Technical → System Parameters, find web.base.url.
3. Set it to the real HTTPS URL your users browse to, e.g. https://erp.example.com.

Activate

1. Go to Settings → ECOSIRE.COM → Activate License.
2. Paste your licence key.
3. Choose Shopify Store Management in the module dropdown (it lists the installed ECOSIRE modules).
4. Click Activate.

Settings → ECOSIRE.COM → License Status then shows, per module, the licence state, last-verified time, Odoo version, module version, support expiry, and whether an offline token is cached.

What the client sends

Activation and validation are plain HTTPS JSON calls to https://api.ecosire.com/api. Every request carries the same five fields:

{
  "key": "ECO-XXXX-XXXX-XXXX-XXXX",
  "module_name": "shopify_store_management",
  "domain": "erp.example.com",
  "hw_fingerprint": "<sha256 of this installation's hardware/db identity>",
  "odoo_version": "19.0"
}

Endpoint	Used for
POST /api/licenses/activate	First-time activation — binds the licence to this domain
POST /api/licenses/validate	Ongoing verification
POST /api/licenses/issue-token	Fetches the RSA-signed offline token used for the grace period
POST /api/licenses/deactivate-self	Releases this domain so the key can move to another database

The base URL is overridable through the ecosire.license.api_url system parameter, and the client refuses any value that is not HTTPS. You do not need to change it.

Activation slots, and moving between databases

Each licence carries its own activation limit. New licences default to a single domain; some licences are issued with more. Check License Status, or the licence detail page in your ECOSIRE portal, for the number on yours. Re-activating on a domain that is already bound is a no-op success, not a second slot.

• Odoo.sh staging and development builds do not consume a slot — they are recognised as non-production hosts and activate without binding.
• To move a live licence to a different database, use Deactivate on the activation screen first; that releases the domain server-side so you can activate elsewhere.
• Ten failed activation attempts within an hour trips a client-side rate limiter. Wait up to 60 minutes, or contact support — do not keep retrying a key you are unsure about.

Staying licensed after activation

A daily scheduled action, ECOSIRE License: Background Re-verification, re-checks the licence out of the request path, refreshes the cached offline token, and keeps the last-known-good timestamp fresh. Because of that, a transient network problem, an Odoo.sh rebuild or a worker restart does not lock you out. Verification results are cached for five minutes, so a licence change can take a few minutes to show up.

If you see a hard rejection instead — LICENSE_NOT_FOUND, LICENSE_INACTIVE, LICENSE_EXPIRED, MODULE_MISMATCH, VERSION_MISMATCH or NOT_ACTIVATED_ON_DOMAIN — the grace period is deliberately not granted; fix the underlying problem. See Troubleshooting.

Configuration

Connect to Shopify

Open Shopify → Configuration → Instances and create a record (model shopify.instance). The connection fields are:

Label	Technical name	Required	Values
—	shop_url	Yes	Text
—	api_key	No	Text
—	password	No	Text
—	shared_secret	No	Text
—	access_token	No	Text
API Version	api_version	Yes	Selection

Where the Label column shows —, the module does not set an explicit label and Odoo derives one from the technical name, so the wording on screen may differ slightly. The technical name is the reliable identifier.

Create a custom app in your Shopify admin and copy the Admin API Access Token. Shop URL is your *.myshopify.com domain. API Version is a dropdown on the instance — pin it to a version Shopify still supports.

The same record carries 4 behaviour checkboxes — auto_validate_inventory, auto_confirm_order, auto_create_invoice, auto_validate_invoice. They gate what the connector is allowed to do automatically once it is connected. Leave anything you are not ready for switched off, and turn them on one at a time.

Credentials are issued from the Shopify admin (custom app) or Shopify Partners — see shopify.dev/docs. The connector talks to your own shop domain — https://<shop>.myshopify.com/admin.

When the fields are filled in, click Test Connection. The record's status moves to connected only when the platform answers successfully — do not run a first import until it does.

Public endpoints: the OAuth install and callback URLs

Filling in an Admin API access token by hand (above) is one way to connect. The other is Shopify's OAuth flow, and it needs two publicly reachable URLs on your Odoo instance. These are the only endpoints on this module served without an Odoo login.

Endpoint	Method	Auth	Register it in the Shopify app as
/shopify/install	GET	public (no Odoo session)	App URL — where Shopify sends the merchant to start or reopen the app
/shopify/callback	GET	public (no Odoo session)	Allowed redirection URL — where Shopify returns after the merchant approves

Use your real host, e.g. https://erp.example.com/shopify/install and https://erp.example.com/shopify/callback. The connector builds the redirect_uri it sends to Shopify from the web.base.url system parameter, so that value must already be your real HTTPS URL — the same prerequisite as licence activation. If web.base.url is wrong, Shopify rejects the redirect as a mismatch.

Before you start the flow, the shopify.instance record must exist and carry API key (api_key) and Shared secret (shared_secret) from your Shopify app, and its Shop URL must be the *.myshopify.com domain. If the instance is missing those, /shopify/install simply sends you to the Instances form in Odoo instead of starting the flow.

What each endpoint does:

• /shopify/install validates that the shop parameter is a real <name>.myshopify.com domain, finds the matching instance, verifies Shopify's request HMAC when one is present, mints a one-time random state nonce onto the instance, and redirects the merchant to https://<shop>/admin/oauth/authorize with the connector's requested scopes.
• /shopify/callback is the return leg. It re-validates the shop domain, verifies the HMAC against your shared secret, checks the returned state matches the nonce it issued (so a replayed or forged callback is refused), then exchanges the authorization code for a permanent access token server-side. On success it stores the token and granted scopes on the instance, clears the nonce, sets the instance to connected, and drops you on the instance form in Odoo. Any failure renders a plain error page with a link back to Odoo — it never silently half-connects.

The scopes requested are read/write on products, orders, customers, inventory, fulfilments and shipping, plus read_all_orders and read_locations. Your Shopify app must be configured to grant them, or the authorize step will fail.

Connecting stamps an order-import cutoff

The first successful OAuth connection sets Order Import Cutoff on the instance to that moment, if it is not already set. Historic orders placed before you connected are deliberately not imported — only orders placed afterwards sync into Odoo. Clear or backdate that field yourself if you do want the history.

Scheduled actions

The module installs 13 scheduled actions (Settings → Technical → Scheduled Actions):

Scheduled action	Runs every	Enabled on install
Shopify: Sync Products	30 minutes	Yes
Shopify: Sync Orders	15 minutes	Yes
Shopify: Sync Customers	60 minutes	Yes
Shopify: Sync Inventory	10 minutes	Yes
Shopify: Process Queue Jobs	5 minutes	Yes
Shopify: Import Payout Reports	6 hours	Yes
Shopify: Import Refunds	30 minutes	Yes
Shopify: Auto Risk Detection	30 minutes	Yes
Shopify: Generate Analytics	4 hours	Yes
Shopify: Webhook Health Check	60 minutes	Yes
Shopify: Cleanup Old Logs	24 hours	Yes
Shopify: Process Workflows	10 minutes	Yes
Shopify: Daily Summary Report	1 days	Yes

Intervals above are the shipped defaults. Adjust them to your volume — but be aware that the platform, not Odoo, sets the API rate limits, and shortening a sync interval is the usual cause of throttling errors in the logs.

Using the module

The Shopify menu is laid out as:

• Shopify → Dashboard
• Shopify → Orders
• Shopify → Refunds
• Shopify → Products
• Shopify → Customers
• Shopify → Payouts
• Shopify → Analytics
• Shopify → Operations — Run Operations, Queue Jobs, Logs
• Shopify → Configuration — Instances, Locations, Payment Gateways, Scheduled Actions, Webhooks

A normal first run is:

1. Test Connection until the instance reads connected.
2. Review the mapping records (categories, order statuses, payment and shipping methods) so imported data lands on the right Odoo records.
3. Run a small import first — restrict it by date or by a handful of products — and check the results before letting the scheduled actions take over.
4. Watch the Logs view during the first full sync. Every sync writes a log line; failures are recorded there rather than raised at the user.

Module-specific notes

• API Version is a required dropdown. Shopify retires API versions on a schedule — if calls start failing after months of working, check that the pinned version is still supported.
• Shop URL must be the *.myshopify.com domain, not a custom storefront domain.
• Use the Authorize button for the OAuth flow, or paste an Admin API access token from a custom app created in your Shopify admin.

Troubleshooting

Licensing

Symptom / error code	Cause and fix
VERSION_MISMATCH	The licence is for a different Odoo major version than the database you activated on. Licences are not transferable across Odoo versions — you need the licence for the version you run.
MODULE_MISMATCH	The licence belongs to a different ECOSIRE module. Check you selected Shopify Store Management (shopify_store_management) in the activation dropdown.
NOT_ACTIVATED_ON_DOMAIN	The database's web.base.url domain is not among the licence's activated domains. Activate on this domain, or deactivate the old one first.
LICENSE_EXPIRED / LICENSE_INACTIVE	The licence is past its expiry or has been suspended/revoked. Check the licence in your ECOSIRE portal.
LICENSE_NOT_FOUND	The key does not exist. Keys are upper-cased before sending, so case is not the problem — re-copy it from your portal.
Activation limit reached	Every slot on the licence is bound to a domain. Deactivate one first.
Too many failed activation attempts	Ten failures in an hour. Wait up to 60 minutes.
Could not determine your Odoo instance domain	web.base.url is empty. Set it, then activate.
The requests library is required	requests is missing from Odoo's Python environment. Install it into the interpreter that runs Odoo.
The downloaded ZIP is the wrong version	The download list is filtered by your licence's version. If you need a different Odoo version, you need that version's licence.

Syncing

Symptom	Cause and fix
Test Connection fails	Re-check every required field in the table above. Most failures are a mistyped secret, or credentials created for the sandbox while the connector points at production (or vice-versa).
Nothing syncs even though the connection is fine	The scheduled actions are disabled at the Odoo level, or Odoo's cron worker is not running. Check Settings → Technical → Scheduled Actions and that --max-cron-threads is greater than zero.
Sync starts then stops part-way	Read the Logs view for that run. Rate limiting and rejected field values are the two common causes; both are logged with the platform's own error text.
Records import but map to the wrong Odoo values	Fix the mapping records under the module's configuration, then re-run the import.
Duplicated products or customers	Run the initial import once. If a first attempt half-finished, check the existing records before re-running rather than importing on top.

Version history

Odoo version	Version you download today
17.0	17.0.1.0.2
18.0	18.0.1.1.2
19.0	19.0.2.0.0

ECOSIRE module versions are <odoo major>.<module major>.<minor>.<patch>, so 19.0.2.0.3 is the Odoo 19 build of module version 2.0.3. Your installed version is shown in Apps and in Settings → ECOSIRE.COM → License Status.

Support

• General troubleshooting
• Licence verification guide
• Email: [email protected]
• Support portal