Overview

This microservice connects OrderLemon with Shopify.
It syncs the Shopify catalogue (collections, products, variants, images, inventory) into OrderLemon, sends paid OrderLemon orders to Shopify, and cancels or fulfils them there when their OrderLemon status changes. It also follows the Shopify connection of each shop: when the connection is lost, ordering in OrderLemon is paused.

Shopify never calls this microservice. There are no Shopify webhooks: the catalogue is pulled, and the connection state is learned from the answers of our own GraphQL calls.

Main Entry Points

The endpoints must be listed in `allowed_functions` of the config, or they answer 405:

"allowed_functions": {
  "GET": ["shopify_connection_status"],
  "POST": ["send_order_to_shopify", "shopify_oauth_start"],
  "PUT": ["sync_shopify_products", "sync_shopify_categories"]
}

Each endpoint takes `shop_id` (and `order_id` for orders) in `parameters`:

{
  "function": "send_order_to_shopify",
  "parameters": { "shop_id": 2, "order_id": 71 }
}

A Postman collection with every request is in `shopify.postman_collection.json` (variables `{{shopify.*}}`).

Requirements

Before a shop is connected, all of these must be in place:

Shopify access scopes:

API version: set `orderlemon_config.tokens.shopify.api_version` to a supported Admin API version (format `YYYY-MM`, e.g. `2026-07`). It is never hardcoded: Shopify supports each version for 12 months only, so it must be raised before the pinned version is retired.

Shopify App Setup (bot app)

The app the microservice calls Shopify with. Created in the Shopify Partner / Dev Dashboard of the OrderLemon organization, and installed on our dev store. The microservice gets its token through the client credentials grant, which never opens the app URL or a redirect URL: Shopify only requires them as form fields.

App configuration:

Never use the webhook path (`/v1/webhooks/shopify`) as the app URL: it only accepts OL's POST with the OL secret.

Access scopes (paste as one line):

read_products,read_inventory,read_orders,write_orders,read_customers,write_customers,read_merchant_managed_fulfillment_orders,write_merchant_managed_fulfillment_orders

Steps:

Merchant stores cannot use the client credentials grant: they connect through OAuth. Then App URL and Redirect URLs point at the OAuth start and callback endpoints of the microservice; the scopes stay the same.

Connect a Merchant Store (OAuth)

Merchant stores cannot use the client credentials grant, so they connect through OAuth (authorization code grant), started from MyShop.

Endpoints:

Configuration (`orderlemon_config`):

And `shopify_oauth_start` (POST) and `shopify_connection_status` (GET) in `allowed_functions`.

Outcome on the return URL:

Rules:

Authentication

Webhook secret

The secret is minted here (64 hex characters) and stored in `shop_settings` as `shopify.ol_webhook.secret`, because OL only ever shows it masked. OL keeps webhooks per company, so one secret serves every shop of a company: the newest row of any shop of the company is the one OL signs with. An unknown shop and a wrong secret get the same answer (401), so the caller cannot learn which shops exist.

Shopify access token

Configuration

Secrets JSON, path in `config_path` of `v1/config.php`. Keys under `orderlemon_config` unless noted.

Two different "environment" values exist: alerts read the top-level `env`, the picture URL reads `orderlemon_config.environment`.

Connection Lifecycle

The state of each shop lives in `shop_settings` as `shopify.connection.status`, `.reason` and `.changed_at`. `markShopConnection()` is its only writer; the microservice never uninstalls anything, it records what it observed.

Closing reasons:

What follows a state change (checked on every call, so a failed step is made up for by the next call):

Pause, Resume and 24/7 Opening

Ported from Deliverect busy mode. All three run under the per-shop lock `pause` (10 s wait).

OL Webhook

Registered by this microservice in OL, per company:

Webhook Receiver

URL (mapped to `shopify.php` by `v1/webhooks/.htaccess`):

`https://<host>/v1/webhooks/shopify`

Event routing:

The event type is read from `type`, then `event.type`, then `event`, then `?event=`.

Response codes:

Only error types declared in `v1/assets/errors.json` may be used: an unknown one degrades to 204, which OL would read as delivered.

Order Flow: OrderLemon -> Shopify

`sendOrderToShopify()` in `v1/general/shopify_order_functions.php`:

orderCreate input:

Custom attributes, in this order (empty ones left out):

OrderLemon order
Logistics (delivery | pickup)
Pick-up moment / Delivery moment
Payment reference
Business name / Business VAT / Business TIN
Promotion (one per promotion)

Pick-up and delivery moment labels:

A row for the date wins over the weekday row (`day_of_week` 0 = Monday). A slot at midnight looks like a day without slots; only the calendar tells them apart.

Cancel and Fulfil

Both take the same order lock as the send. A refusal sends a Telegram alert.

Catalogue Sync

`runShopifyCatalogSync()` runs collections first, then products, because `products.category_id` is NOT NULL.

Retirement rules:

OL catalogue limits: error 43 = 10 enabled categories per shop, error 42 = 30 enabled products per category. OL skips both for web catalogue shops, but the API cannot read that setting. They need the merchant or support to act.

OL Module API

Modules used: categories (new, update), products (new, update, info, delete, relations_add), shops (info, update), orders (update), webhook (list, new, update). Reads go straight to the OL database through DBAL.

Data Storage

`shop_settings` (reads take the newest row: the unique key is missing on some live databases)

`metadata` JSON column, `shopify` namespace:

- `categories_{shop_id}` → external_id, gid, handle, title, updated_at, linked, merged_external_ids, image_url, modifier_key, fallback
- `products_{shop_id}` → role (simple | modifier | parent), external_id, variant_id, variant_gid, product_id, product_gid, handle, sku, title, updated_at, category_scope, image_url, image_updated_at

Orders keep no Shopify id in OL: the OL API cannot store one. The order is found in Shopify by its tag `OL-{shop_id}-{order_id}`.

Locks

MariaDB named locks, name `shopify_<kind>_` + md5 of database and id (a long database name must not cut the id off).

Alerts

Telegram, through the `telegram` microservice. Production only. State alerts fire once when a failure starts or changes, and once when it clears.

One-off alerts: order refused by Shopify (and marked lost), cancel refused, fulfil refused.

Cron

Not one of the framework's cron files (those are overwritten on update), so `install.sh` does not register it. Add on every server:

0 * * * * cd <ms_root>/v1/cron/;php shopify_catalog_sync.php

Only shops with status `active` are synced. Output goes to stdout, one line per shop; exit code 1 when any shop failed.

Key Files

Environment Notes

Known Constraints