Metadata-Version: 2.1
Name: odoo-addon-shopify_connector
Version: 19.0.1.0.7.1
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:c5d15f7b5b9921aed97622792462f93e001c90b03b27f0ae74a33e01e2ab6027
   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

.. |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.

**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.

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.
