Overview

Main Entry Points

Webhook handlers live in: `v1/webhooks/deliverect/`

Authentication

Secrets, by environment

Event Routing

Routing priority:

Supported query parameters:

?event=payment_completed
?event=order_updated
?event=sync_opening_hours
?event=menu_update
?event=order_status_update
?event=snooze_unsnooze
?event=busy_mode
?event=opening_hours
?event=channel_registration

Internal OrderLemon webhook URLs usually use `?event=`.

Example:

/v1/webhooks/deliverect?event=payment_completed

Supported Events

Deliverect Status Values

Reference: https://developers.deliverect.com/page/order-status

Deliverect status values

Deliverect -> OrderLemon Status Mapping

Current implementation maps Deliverect final statuses to OrderLemon `done` (`status_id=3`), not `delivered` (`status_id=7`).

Notes:

Final Statuses: `done` (`3`) and `delivered` (`7`) are final OrderLemon statuses 

Current Deliverect final mapping: Deliverect `90/95` maps to OL `done` (`3`)

Cash orders: Cash orders are marked `payment_status_label = paid` when finalized/delivered by Deliverect

Archive fallback: Status update searches `orders_active_{shop_id}` first, then `orders_archive_{shop_id}`

OrderLemon -> Deliverect Status Mapping

Meaning of __G_ in OrderLemon Reference

The `__G_` suffix means that an OrderLemon product row is group-scoped.
Example: XTRA-CHEESE__G_fb271dcb
Base reference: XTRA-CHEESE
The suffix identifies a specific modifier-group or upsell-group context.
This exists because the same Deliverect item can appear in multiple groups with different sync context. A scoped row allows OrderLemon to store group-specific assignment, pricing, relations, and availability without overwriting the base reference.
When comparing product identity, compare the base reference before `__G_`.
Scoped `__G_` rows are expected in modifier and upsell sync. They are not random duplicates and should not be skipped or deleted only because the base reference already exists.

Data Format Rules

Day Mapping:

Webhooks from OrderLemon

`order_updated` only works for orders that have a Deliverect order ID mapping; otherwise returns `not_deliverect_order`.

Example URLs:

/v1/webhooks/deliverect?event=payment_completed
/v1/webhooks/deliverect?event=order_updated

Bearer auth hardening is currently not enforced until OrderLemon reliably sends the expected `Authorization: Bearer <secret>` header.

Order Flow: OrderLemon -> Deliverect

Paid orders are sent from OrderLemon to Deliverect

Delivery courier payload:

{
  "courier": "restaurant"
}

Order flow: Deliverect -> OrderLemon

Deliverect sends order status updates through `order_status_update`

The microservice:

Tax Handling in Order Payloads

OrderLemon cart prices are gross VAT-inclusive.

Do not send `items[].tax`. It is not a valid Deliverect field for this integration.

VAT is sent at order level:

Menu Sync

`menu_update` synchronizes:

Reference resolution:

Reference resolution order is context-dependent. Menu sync prefers `referenceId` first, while the general helper prefers `plu` first.

Important menu sync rules:

Data Storage (metadata)

Deliverect data is stored in the `metadata` JSON column on per-shop tables under the `deliverect` namespace. Other namespaces in metadata are never touched (read-modify-write).

- `categories_{shop_id}` → `external_id` (Deliverect category `_id`)
- `products_{shop_id}` → `product_type` (Deliverect productType), combo_variants (variant references for combo shells), plu (the raw Deliverect PLU, written during the product upsert)
- `orders_active/archive_{shop_id}` → `order_id` (Deliverect order `_id`, set after send), `last_status` (last OL status set by `order_status_update`, used for loop prevention)

plu exists because the stored reference is often derived from the PLU, a canonical referenceId, or a group-scoped row where every unusual character became _ and the base was cut to 48 chars (REDPEPP-#O0#- is stored as REDPEPP-_O0_-__G_c0afa2ce). That is lossy, so snooze resolves its targets through this key instead of reversing the string. Rows published before this change need one menu publish to backfill it.

OAuth2 token is account-level and cached in `shop_settings` as `deliverect.oauth.access_token` and `deliverect.oauth.expires_at` under a shop_id.

Busy Mode

Busy mode updates temporary shop delay through `shops.min_timeframe`

busy statuses:

Rules:

Opening Hours Sync

Opening hours sync goes from Deliverect to OrderLemon.

Rules:

Manual OL -> Deliverect opening hours sync exists as `sync_opening_hours`, but automatic sync is blocked because OrderLemon has no webhook event for opening-hour changes.

Channel Registration

Channel registration stores Deliverect channel link/location mapping and returns event-specific webhook URLs

Returned URLs include:

Key Files

Environment Notes

Known Constraints

Automatic OrderLemon to Deliverect opening-hours sync is blocked by missing OrderLemon webhook events.