Metadata-Version: 2.1
Name: odoo-addon-shopify_connector
Version: 19.0.1.5.2
Requires-Dist: odoo-addon-queue_job==19.0.*
Requires-Dist: odoo==19.0.*
Requires-Dist: requests
Summary: GraphQL-first Shopify commerce synchronization
Home-page: https://github.com/OCA/connector-shopify
License: AGPL-3
Author: Sawir Studio, Odoo Community Association (OCA)
Author-email: support@odoo-community.org
Classifier: Programming Language :: Python
Classifier: Framework :: Odoo
Classifier: Framework :: Odoo :: 19.0
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Description-Content-Type: text/x-rst

.. image:: https://odoo-community.org/readme-banner-image
   :target: https://odoo-community.org/get-involved?utm_source=readme
   :alt: Odoo Community Association

=================
Shopify Connector
=================

.. 
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! This file is generated by oca-gen-addon-readme !!
   !! changes will be overwritten.                   !!
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
   !! source digest: sha256:b70fa89aa441dec80493c4371b2ce478d37f0904f17c9656d30a792a2a899936
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
    :target: https://odoo-community.org/page/development-status
    :alt: Beta
.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fconnector--shopify-lightgray.png?logo=github
    :target: https://github.com/OCA/connector-shopify/tree/19.0/shopify_connector
    :alt: OCA/connector-shopify
.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
    :target: https://translation.odoo-community.org/projects/connector-shopify-19-0/connector-shopify-19-0-shopify_connector
    :alt: Translate me on Weblate
.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
    :target: https://runboat.odoo-community.org/builds?repo=OCA/connector-shopify&target_branch=19.0
    :alt: Try me on Runboat

|badge1| |badge2| |badge3| |badge4| |badge5|

The core Shopify connector links any number of Shopify stores to Odoo 19
Community through company-scoped binding records. It synchronizes
products, inventory, customers, orders, returns, refunds, and
fulfillment through the GraphQL Admin API.

Signed webhooks provide the fast path, OCA ``queue_job`` provides
durable execution, and scheduled reconciliation repairs missed or
delayed events. Onboarding, health checks, a sync dashboard, error
recovery, and configurable retention support day-to-day operation.

Product images cover the main image of each product and the images of
its variants. Synchronizing the other Shopify product media needs the
glue module Shopify Connector Website Sale, which installs automatically
with eCommerce.

**Table of contents**

.. contents::
   :local:

Configuration
=============

**Shopify app**

Since January 1, 2026, Shopify no longer lets merchants create legacy
custom apps from the Shopify admin. Create the app in the Shopify Dev
Dashboard:

1. Open the Dev Dashboard of the organization that owns the store. Odoo
   gets its access tokens with the client credentials grant, which only
   works when the app and the store belong to the same organization.
   Owning the store or installing the app on it is not enough. For a
   test store, create it from the **Dev stores** page of that same Dev
   Dashboard.
2. Create the app and fill in its version. The connector has no page in
   the Shopify admin and never sends users through Shopify's
   authorization pages, so:

   - **App URL**: ``https://shopify.dev/apps/default-app-home``, the
     default Shopify gives for apps that are not embedded.
   - **Embed app in Shopify admin**: unchecked.
   - **Allowed redirection URL(s)**: none. If Shopify asks for one,
     enter the App URL again.
   - **Use legacy install flow**: unchecked, so that installing the app
     grants the scopes selected on the version. With the legacy flow the
     app would have to request them itself, which the connector cannot
     do.
   - **Webhooks**: none. Odoo creates its own subscriptions during
     onboarding.
   - **Webhooks API version**: ``2026-01``, the Admin API version the
     connector uses. Shopify writes the payloads of the subscriptions
     Odoo creates in this version.
   - **Scopes**: ``read_customers``, ``write_customers``,
     ``read_draft_orders``, ``read_fulfillments``, ``read_inventory``,
     ``write_inventory``, ``read_locations``,
     ``read_merchant_managed_fulfillment_orders``,
     ``write_merchant_managed_fulfillment_orders``, ``read_orders``,
     ``read_products``, ``write_products`` and ``read_returns``. To
     import orders older than 60 days, also select ``read_all_orders``,
     which Shopify may have to approve.

3. Release the version and install the app on the store. After a later
   scope change, release a new version and approve the change on the
   store.
4. Copy the client ID and the client secret from the app's **Settings**
   page.

The app must have access to protected customer data: names, addresses,
emails and phone numbers. For merchant-created apps this depends on the
store's plan, and the Basic plan does not include it. Without it,
Shopify refuses some of the order webhooks and the order and customer
imports fail.

A legacy custom app created before 2026 keeps working. Leave the client
ID empty and enter the app's Admin API access token and API secret key
instead.

**Odoo**

1. Add OCA ``queue_job`` and this repository to the Odoo addons path,
   then install **Shopify Connector**.
2. Grant operators the **Shopify Manager** group. The administrator gets
   it on install.
3. Set the ``web.base.url`` system parameter to a public HTTPS address
   of Odoo, and set ``web.base.url.freeze`` to ``True`` so that it does
   not change when an administrator logs in from another address.
   Shopify sends its webhooks to
   ``<web.base.url>/shopify/webhook/<instance id>`` and downloads
   exported product images from the same address.
4. Open **Shopify > Configuration > Instances** and click **Start
   Onboarding**:

   - **Credentials**: enter the ``<store>.myshopify.com`` domain, the
     client ID and the client secret, then **Test Connection**. Odoo
     requests the access token and renews it before it expires, every 24
     hours. The client secret also verifies the webhook signatures.
   - **API Scopes**: add any missing scope to a new app version, release
     it, approve the change on the store and check again.
   - Map the Shopify locations, review the generated tax mappings,
     choose the synchronization policies, install the webhooks and queue
     the initial imports.

5. Review the payment-gateway and carrier mappings before enabling
   unattended order and fulfillment processing.

Jobs run on the ``root.shopify.import``, ``root.shopify.export`` and
``root.shopify.webhook`` channels. Add ``queue_job`` to the server-wide
modules, after the Odoo defaults ``base,rpc,web``, and give each channel
a capacity in ``odoo.conf``, for example:

.. code:: ini

   [options]
   server_wide_modules = base,rpc,web,queue_job

   [queue_job]
   channels = root:4,root.shopify.import:2,root.shopify.export:1,root.shopify.webhook:1

Usage
=====

Use **Shopify > Dashboard** to monitor binding states, queue backlog,
recent errors, webhook health, drift schedules, and operational table
sizes.

Normal changes flow through webhooks and idempotent jobs. Use the entity
import or reconcile actions for manual catch-up. For failures, correct
the underlying configuration or data, select error bindings, and choose
**Retry Failed Shopify Bindings**. Resetting to pending clears the state
without scheduling work.

Tax lines with the same rate on one order line are added together before
the tax mapping lookup. For example, an order line with a 1% city tax
and a 1% transit tax needs a tax mapping for 0.02. If you mapped 0.01 to
a 2% tax as a workaround, map 0.02 to that tax instead.

With **Validate Deliveries from Webhooks** enabled on the instance, a
fulfillment made in Shopify or by a fulfillment app validates the
fulfilled items on the Odoo deliveries of the order:

- A sale order that is not confirmed yet is confirmed first.
- Each delivery step is validated for the fulfilled items, including the
  pick and pack steps. Items not fulfilled yet stay on a backorder.
- Kits ship their components.
- The carrier and tracking numbers of the fulfillment are copied to the
  delivery. The carrier comes from the carrier mappings of the instance,
  or else from a delivery carrier with the same name.
- A fulfillment validates deliveries only once. Later updates only
  refresh its carrier and tracking numbers.
- A fulfillment that Odoo missed, because its webhook was lost or
  arrived before the order, is applied the next time the order is
  imported.

The fulfilled items need reserved stock, so lots and serial numbers come
from the reservation. Enable **Ship Unreserved Stock** to also ship the
items that Odoo could not reserve. Products tracked by lot or serial
number still need reserved stock.

When a delivery cannot be validated, for example because of missing
stock or a risk hold, the fulfillment goes to error with the reason. Fix
the cause and retry it. Releasing the risk hold of an order retries its
fulfillments automatically.

The **Shopify Drift: Updated Orders** scheduled action imports again the
orders updated in Shopify since the **Sync Orders Updated Since** date
of each instance, then moves that date forward. It recovers the order
changes whose webhook was missed, and skips the orders whose latest
version Odoo already imported. To import older updated orders on the
next run, set an earlier date on the **Orders** tab of the instance.

Run **Check Webhooks** after changing domains or credentials and repair
any missing or misrouted subscriptions. Never edit Shopify IDs or raw
payloads.

Bug Tracker
===========

Bugs are tracked on `GitHub Issues <https://github.com/OCA/connector-shopify/issues>`_.
In case of trouble, please check there if your issue has already been reported.
If you spotted it first, help us to smash it by providing a detailed and welcomed
`feedback <https://github.com/OCA/connector-shopify/issues/new?body=module:%20shopify_connector%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.

Do not contact contributors directly about support or help with technical issues.

Credits
=======

Authors
-------

* Sawir Studio

Contributors
------------

- `Binhex <https://www.binhex.cloud/>`__:

  - Oliver Garcia

Maintainers
-----------

This module is maintained by the OCA.

.. image:: https://odoo-community.org/logo.png
   :alt: Odoo Community Association
   :target: https://odoo-community.org

OCA, or the Odoo Community Association, is a nonprofit organization whose
mission is to support the collaborative development of Odoo features and
promote its widespread use.

This module is part of the `OCA/connector-shopify <https://github.com/OCA/connector-shopify/tree/19.0/shopify_connector>`_ project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
