# Setup and configuration

### Prerequisites

* Flow Retail (doh)
* Omnium OMS account with API access
* OAuth2 client credentials (client ID and client secret) for the Omnium API

### Extension activation

The Omnium integration is a **tenant-level extension** in Flow. It must be activated per tenant before any synchronization occurs.

Once activated, the following parameters must be configured.

### Tenant-level settings

These settings apply to the entire tenant (all stores):

<table><thead><tr><th width="386.59375">Key</th><th width="109.92578125">Required</th><th width="203.48046875">Description</th></tr></thead><tbody><tr><td><code>OMNIUM_CLIENT_ID</code></td><td>Yes</td><td>OAuth2 client ID for Omnium API authentication</td></tr><tr><td><code>OMNIUM_CLIENT_SECRET</code></td><td>Yes</td><td>OAuth2 client secret for Omnium API authentication</td></tr><tr><td><code>OMNIUM_TOKEN</code></td><td>No</td><td>Access token for Omnium API (managed automatically — do not set manually)</td></tr><tr><td><code>OMNIUM_DEFAULT_SHIPPING_METHOD_ID</code></td><td>No</td><td>Default shipping method ID for orders sent to Omnium</td></tr><tr><td><code>OMNIUM_CLICK_COLLECT_ORDERHANDLING_UID</code></td><td>No</td><td>Handling UID for Click &#x26; Collect orders from Omnium</td></tr><tr><td><code>OMNIUM_ONLINE_ORDER_HANDLING_UID</code></td><td>No</td><td>Handling UID for Online orders from Omnium</td></tr><tr><td><code>OMNIUM_CLICK_COLLECT_EXPIRY_DAYS</code></td><td>No</td><td>Working days until Click &#x26; Collect pickup deadline</td></tr><tr><td><code>OMNIUM_INCLUDE_MAIN_PACKAGE_IN_ORDER_ITEMS</code></td><td>No</td><td>Include package parent product in order line items (default: <code>false</code>)</td></tr><tr><td><code>OMNIUM_CUSTOMER_MARKET_GROUP_ID</code></td><td>No</td><td>Market group ID for creating customers in Omnium</td></tr><tr><td><code>OMNIUM_CUSTOMER_LOYALTY_ID_PROPERTY_KEY</code></td><td>No</td><td>External ID key for resolving customer loyalty IDs (e.g., <code>"Voyado"</code>)</td></tr><tr><td><code>OMNIUM_SEND_ORDER_RECEIPT_TO_OMNIUM</code></td><td>No</td><td>Send receipt PDFs to Omnium as invoices (default: <code>false</code>)</td></tr><tr><td><code>OMNIUM_PROPERTY_PREFIX</code></td><td>No</td><td>Prefix for read-write order properties (default: <code>"flow"</code>)</td></tr></tbody></table>

### Store-level settings

These settings can be configured per store:

<table><thead><tr><th width="259.02734375">Key</th><th width="121.1875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>OMNIUM_FLOW_STOCK_MASTER</code></td><td>No</td><td>Flow is the stock master for this store (default: <code>false</code>)</td></tr></tbody></table>

### Omnium connector settings

These settings are configured on the **Omnium side** in the FlowRetail connector:

| Setting                             | Description                           | Default     |
| ----------------------------------- | ------------------------------------- | ----------- |
| `OmniumIsMasterForStock`            | Omnium is the stock authority         | `false`     |
| `SyncCategoriesToFlow`              | Enable category synchronization       | `false`     |
| `ProductGroupRootId`                | Root category ID for product groups   | Not set     |
| `DefaultProductGroupUid`            | Fallback product group UID            | Not set     |
| `DefaultVatCodeUid`                 | Default VAT code UID                  | Required    |
| `MainPricesListUid`                 | Primary price list UID in Flow        | Required    |
| `StorePriceListsInFlow`             | Generate per-store price lists        | `false`     |
| `OrganizationUid`                   | Fallback organization UID for stores  | Required    |
| `PurchaseNumberSeriesUid`           | PO number series UID                  | Conditional |
| `VoucherNumberSeriesUid`            | Voucher number series UID             | Conditional |
| `ExportDeliveryAsPo`                | Export each delivery as a separate PO | `false`     |
| `SendPackageProductOnPurchaseOrder` | Consolidate packages in POs           | `false`     |
| `CreatePackageSlots`                | Enable package/bundle products        | `false`     |
| `UseCostPriceListInInventoryExport` | Include cost prices in inventory sync | `false`     |
| `UseMarketGroupFlowTenants`         | Group stores by market group          | `false`     |

#### VAT code mapping

Map Omnium tax rates to Flow VAT code UIDs using the `VatCodeUids` key group:

```json
{
  "key": "25",
  "value": "standard-vat-uid",
  "keyGroup": "VatCodeUids"
}
```

#### Payment method mapping

Map Flow payment methods to Omnium payment method names using the system code `OMNIUM` on tenant payment method mappings. When a mapping exists, the Omnium payment method name is used instead of the Flow settlement code.

### Background services

#### Order sync engine

The order sync engine runs as a background service processing order-related sync jobs:

* **Inbound jobs:** Creates/updates Flow orders from Omnium webhook events
* **Outbound jobs:** Pushes Flow POS orders to Omnium

#### Receivement sync engine

The receivement sync engine processes goods reception sync jobs:

* Sends goods reception confirmations to Omnium
* Sends inventory level updates when the PO doesn't exist in Omnium

#### Retry behavior

Both sync engines implement exponential backoff for failed jobs:

| Retry # | Delay       |
| ------- | ----------- |
| 1       | 2 minutes   |
| 2       | 2 minutes   |
| 3       | 5 minutes   |
| 4       | 10 minutes  |
| 5       | 20 minutes  |
| 6       | 30 minutes  |
| 7       | 45 minutes  |
| 8       | 60 minutes  |
| 9       | 90 minutes  |
| 10+     | 120 minutes |

Failed jobs are retried indefinitely with the maximum delay capping at 120 minutes.

### Omnium scheduled tasks

These tasks are configured on the **Omnium side** and run on a schedule:

| Task                         | Description                   | Typical schedule         |
| ---------------------------- | ----------------------------- | ------------------------ |
| `FlowInventoryScheduledTask` | Push inventory levels to Flow | Every 30 minutes         |
| `FlowPriceScheduledTask`     | Push selling prices to Flow   | Every 30 min – few hours |
| `FlowCostPriceScheduledTask` | Push cost prices to Flow      | Daily                    |
| `FlowSoaScheduledTask`       | Push SOA prices to Flow       | Daily                    |
| `FlowCategoryScheduledTask`  | Push categories to Flow       | Daily (e.g., 02:00)      |

All scheduled tasks use **delta synchronization** — only items modified since the last run are processed.

Example scheduled task configuration in Omnium:

```json
{
  "schedule": "*/30 * * * *",
  "implementationType": "FlowInventoryScheduledTask",
  "isDisabled": false
}
```

### Webhook configuration

Omnium must be configured to send webhook events to Flow's Omnium Event API endpoint. The endpoint receives order creation and update events and queues them for processing.

The webhook endpoint is available at Flow's API under the Omnium event route. Deduplication is built in — duplicate events for the same order are automatically filtered.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flowretail.com/docs/integrations/order-management/omnium-oms-integration/setup-and-configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.