Orders

Overview

Order synchronization is bidirectional:

• Omnium → Flow: When an order is created or updated in Omnium (e.g., a web order), it is sent to Flow via a webhook event. Flow creates the order locally for processing in the POS.

• Flow → Omnium: When a POS transaction occurs in Flow (sale, return, cancellation), the order is pushed to Omnium through the async job queue.

Both Click & Collect and Online order types from Omnium are supported, each with their own handling flow in Flow.

Omnium → Flow (inbound orders)

How inbound orders arrive

1. An order is created or updated in Omnium

2. Omnium sends a webhook event to Flow's Omnium Event API endpoint

3. Flow creates an inbound sync job in the external_order_sync queue

4. The sync engine picks up the job and fetches the full order from Omnium's REST API

5. The order is created or updated in Flow

Deduplication is built in — if a pending sync job already exists for the same order, no duplicate job is created.

Click & Collect orders

When the order type is ClickAndCollect:

1. The order is created in Flow with state PARKED

2. A Click & Collect handling task is attached to the order (configured via OMNIUM_CLICK_COLLECT_ORDERHANDLING_UID)

3. If OMNIUM_CLICK_COLLECT_EXPIRY_DAYS is set and the order has no validUntil date, a pickup deadline is calculated using working days from the current date

4. Store staff can then process the order — pick items, notify the customer, and complete the handover

Online orders

When the order type is OnlineOrder:

1. The order is created in Flow with state CONFIRMED

2. An Online order handling task is attached (configured via OMNIUM_ONLINE_ORDER_HANDLING_UID)

3. The order is ready for shipping or further processing

Order updates from Omnium

When an existing order is updated from Omnium:

1. Flow reopens the order (sets state to OPEN)

2. New line items from Omnium are added to the Flow order

3. Existing line items are updated if quantities, prices, or discounts have changed

4. Line items removed from Omnium are deleted from the Flow order (unless they are referenced returns)

5. Order deliveries are synchronized (created, updated, or removed)

6. Additional notes are synced

7. The order state is set back to PARKED or CONFIRMED

If the update adds items that weren't in the Omnium order, a new outbound sync job is created to push the changes back.

Delivery processing from Omnium

When an Omnium order reaches state COMPLETE with delivery information:

1. Flow compares its order items with Omnium's shipment line items

2. For each item with a deliveredQuantity in Omnium, Flow triggers a delivery

3. If the shipment warehouse differs from the Flow item's warehouse, the warehouse is updated first

4. Items are delivered only if the reserved quantity is sufficient

Flow → Omnium (outbound orders)

Order creation (POS sales)

When a sale is completed in Flow POS:

1. An outbound sync job is added to the queue

2. The sync engine checks if the order already exists in Omnium (GET by order UID)

3. If not found (404), the order is created in Omnium

4. Omnium returns the created order with assigned IDs

5. Flow updates its order heading with the externalOrderNumber from Omnium

6. Flow updates each order line with the externalId from Omnium's response

Order updates

When a Flow order that already exists in Omnium is modified:

1. The current Omnium order is fetched

2. Line items removed from Flow are cancelled in Omnium via the cancel order line API

3. The Flow order is mapped to an Omnium order and merged with the existing Omnium data

4. The merged order is sent as an update

5. Shipment statuses are updated individually via Omnium's workflow API

6. The order status is updated via Omnium's workflow API

Order cancellation

When a Flow order is cancelled:

1. The Omnium order status is updated to OrderCanceled via the workflow API

Return orders

Returns are handled differently depending on whether they reference an original order:

Referenced returns (with credit links to original order lines):

1. The original order is locked to prevent concurrent modifications

2. A return request is created in Omnium using the Returns API, referencing the original order's line items

3. If the return includes new sales lines (exchange), an exchange order is created in Omnium

4. The exchange order is then updated with full order details

Non-referenced returns (standalone returns without links):

• Treated as regular orders and created directly in Omnium

• Return quantities are sent as negative creditQuantity values on the line items

Only settled return orders are exported — unsettled returns are skipped and retried later.

Invoice and receipt sync

When OMNIUM_SEND_ORDER_RECEIPT_TO_OMNIUM is enabled:

1. After the order is synced, Flow checks for pending receipt sync records

2. For each receipt, a PDF is generated from the Flow receipt

3. An invoice is created in Omnium with line items and payment details

4. The PDF is attached to the invoice as a file

5. The sync record is marked as complete

Two invoice types are supported:

• Standard invoice — maps order receipt line items and settlements

• Payment invoice — for payment-type orders (e.g., down payments), uses a single REMITTANCE line item

Order status mapping

Flow → Omnium

Flow's order state is a combination of three fields (orderState, settleState, deliveryState), which maps to a single Omnium status:

Flow state	Omnium status
PARKED	Parked
CONFIRMED	Confirmed
CANCELED	OrderCanceled
COMPLETE + settle NOT_STARTED	AwaitingPayment
COMPLETE + settle IN_PROGRESS	SettlementInProgress
COMPLETE + settle COMPLETE + delivery NOT_STARTED	DeliveryNotStarted
COMPLETE + settle COMPLETE + delivery IN_PROGRESS	Picking
COMPLETE + settle COMPLETE + delivery COMPLETE	PickedUp
COMPLETE + settle COMPLETE + delivery COMPLETE + Click & Collect complete	PickedUpAndPaid
COMPLETE + settle COMPLETE + delivery COMPLETE + Online order complete	Ship

Click & Collect / Online handling states

When an order has a handling task and is not yet settled, the handling state overrides the order status:

Handling state	Omnium status
NotStarted	InProgress
Complete	ReadyForPickup

Omnium → Flow

Omnium status	Flow orderState	Flow settleState	Flow deliveryState
Parked	PARKED	NOT_STARTED	NOT_STARTED
Confirmed	CONFIRMED	NOT_STARTED	NOT_STARTED
OrderCanceled	CANCELED	NOT_STARTED	NOT_STARTED
CompletedInPos	COMPLETE	COMPLETE	COMPLETE
DeliveryNotStarted	COMPLETE	COMPLETE	NOT_STARTED
Picking	COMPLETE	COMPLETE	IN_PROGRESS
PickedUp	COMPLETE	COMPLETE	COMPLETE

Shipment status mapping

Delivery state	Omnium shipment status
DeliveredAtSale	CompletedInPos
Delivered (online order)	Ship
Delivered (other)	PickedUp
Default with items	PartiallyPickedUp
Default without items	DeliveryNotStarted
Order is PARKED	Parked

Order field mapping (Flow → Omnium)

Order header

Omnium field	Flow source	Notes
id	order.Uid	—
orderNumber	order.OrderNumber	—
orderType	"FlowPos"	Set on creation only
status	Derived	See status mapping above
storeId	order.Store.Uid	—
marketId	store.ExternalId	—
customerId	customer.ExternalId or customer.Uid	ExternalId preferred
customerType	Derived	"B2C" or "B2B" based on customer/address
customerEmail	orderAddress.Email	—
customerName	Display name	From order address
customerPhone	orderAddress.Mobile	—
billingAddress	Invoice address or order address	Invoice address preferred
billingCurrency	tenant.Country.Currency	—
total	orderTotals.GrandTotal	Converted to float
subTotal	orderTotals.SubTotal	Converted to float
taxTotal	orderTotals.TotalVat	Converted to float
discountTotalIncVat	orderTotals.TotalDiscount	Converted to float
lineItemsCost	orderTotals.TotalCost	Converted to float
remainingPayment	settlementTotals.Remaining	Converted to float
salesPersonId	tenantUser.UserCode	—
salesPersonName	tenantUserDisplayName	—
orderOrigin	order.Origin	—
created	order.OrderDate or order.CreatedAt	With regional timezone
modified	order.LastModifiedAt	With regional timezone
orderNotes	order.Note + order.AdditionalNotes	—

Line items

Omnium field	Flow source	Notes
lineItemId	orderLine.Uid	—
code	orderLine.Sku	—
displayName	orderLine.Name	—
quantity	orderLine.QtyOrdered	Absolute value for sales
returnQuantity	orderLine.QtyOrdered	Absolute value for returns
deliveredQuantity	orderLine.QtyDelivered	0 if order is parked
placedPrice	orderLine.Price	Converted to float
extendedPrice	orderLine.LineTotal	Converted to float
discounted	orderLine.LineDiscountAmount	Converted to float
cost	orderLine.CostPrice	Converted to float
costTotal	orderLine.LineCostPrice	Converted to float
taxRate	orderLine.VatRate	Converted to float
taxTotal	orderLine.LineVatAmount	Converted to float
serialNumber	orderLine.SerialNumber	—
comment	orderLine.Note	—
imageUrl	orderLine.CoverImage.MainUrl	—
reservedInventory	orderLine.QtyReserved != 0	Boolean
reservedInventoryQuantity	orderLine.QtyReserved	Converted to float
isBackorder	Derived	True if reservation type is purchase order
createPurchaseOrder	Derived	True if reservation type is REQUEST_PURCHASE_ORDER
updateStock	orderLine.QtyDelivered != 0	Boolean
isPackage	Derived	True for package products
returnType	orderLine.ReturnReasonCode	—

Line item properties

Each line item includes properties with detailed Flow metadata:

Property key	Key group	Description
flow.order_line.id	flow.OrderLine	Flow line item ID
flow.order_line.uid	flow.OrderLine	Flow line item UID
flow.product.id	flow.OrderLine	Flow product ID
flow.product.uid	flow.OrderLine	Flow product UID
flow.order_line.product_group_uid	flow.OrderLine	Product group UID
flow.order_line.product_type	flow.OrderLine	Product type
flow.seller.code	flow.OrderLine	Seller user code
flow.vat_code	flow.OrderLine	VAT code UID
flow.line_no	flow.OrderLine	Line number
flow.warehouse.id	flow.OrderLine	Warehouse ID
flow.warehouse.uid	flow.OrderLine	Warehouse UID
flow.order_line.voucher_number	flow.OrderLine	Receipt voucher number
flow.discount_reason_code	flow.OrderLine	Discount reason code
flow.discount_reason_reference	flow.OrderLine	Discount reference
flow.return_reason_code	flow.OrderLine	Return reason code
flow.order_line.credit_reference.*	flow.OrderLine	Credit reference details (voucher, order, line)
flow.main_product.line_no	flow.OrderLine	Parent product line (for services/insurance/freight)
flow.main_product.link_type	flow.OrderLine	Link type (INSURANCE, SERVICE, FREIGHT_SERVICE)
voyado.order.id	voyado	Voyado order ID (voucher number, for FlowPos orders)

Payments

Omnium field	Flow source	Notes
id	settlement.Uid	—
amount	settlement.Amount	Converted to float
paymentMethodName	Omnium mapping or settlement code	Uses Omnium system code mapping if available
paymentType	settlement.SettlementCode	—
status	Derived	Processed for complete, Failed otherwise
transactionType	—	Always "Sale"
transactionId	settlement.Uid	—
paidDate	settlement.SettledAt	—
invoiceId	Receipt voucher number	—
internalReference	settlement.DeviceIdentifier	—

Skipped settlements:

• Incomplete or cancelled settlements

• Pre-payments

• Settlements linked to a pre-payment

Cash/cashback merging: If both a CASH and CASHBACK settlement exist, they are merged into a single CASH payment before export.

Rounding: Rounding settlements have their amount negated before export.

Payment properties

Property key	Key group	Description
flow.settlement.code	flow.Settlement	Settlement code
flow.settlement.id	flow.Settlement	Settlement ID
flow.settlement.uid	flow.Settlement	Settlement UID
flow.settlement.voucher_number	flow.Settlement	Voucher number
flow.settlement.voucher_reference	flow.Settlement	Original voucher (for linked payments)
flow.settlement.issuer_name	flow.Settlement	Settlement issuer name
flow.settlement.issuer_code	flow.Settlement	Settlement issuer code
flow.settlement.external_payment_reference	flow.Settlement	External payment reference
flow.settlement.psp_payment_reference	flow.Settlement	PSP reference
flow.settlement.till_number	flow.Settlement	Till number
flow.settlement.device_name	flow.Settlement	Device name
flow.settlement.masked_card_number	flow.Settlement	Masked card number
flow.settlement.approval_code	flow.Settlement	Approval code
flow.settlement.parameter.*	flow.Settlement	Custom settlement parameters
flow.settlement.recurring_payment_token	flow.Settlement	Recurring payment token
flow.settlement.stored_payment_method_id	flow.Settlement	Stored payment method ID

Adyen card properties

For Adyen card payments, additional properties are extracted from the transaction log:

Property key	Description
flow.settlement.adyen_properties.acquirerReference	Acquirer reference
flow.settlement.adyen_properties.paymentMethod	Payment method
flow.settlement.adyen_properties.paymentMethodVariant	Payment method variant
flow.settlement.adyen_properties.issuerCountry	Issuer country
flow.settlement.adyen_properties.posAuthAmountCurrency	POS auth amount currency
flow.settlement.adyen_properties.cardHolderName	Card holder name
flow.settlement.adyen_properties.expiryMonth	Card expiry month
flow.settlement.adyen_properties.expiryYear	Card expiry year
flow.settlement.adyen_properties.cardScheme	Card scheme
flow.settlement.adyen_properties.cardType	Card type

Shipments

Omnium field	Flow source	Notes
shipmentId	orderDelivery.Uid	—
warehouseCode	orderDelivery.ExternalDeliveryReference	Derived from item warehouse
orderStatus	Derived	See shipment status mapping
status	"Released" or "OnHold"	Released when delivered
completed	orderDelivery.CreatedAt	Only for delivered state
expectedDeliveryDate	orderDelivery.DeliveryDateTime	—
shippingMethodId	Extension parameter or provider mapping	Default from OMNIUM_DEFAULT_SHIPPING_METHOD_ID
shippingMethodName	"PickUpInStore" or provider name	—
address	Delivery address fields	—
lineItems	Delivery order items	Same mapping as order line items

Shipment properties

Property key	Key group	Description
flow.shipment.process_indicator	flow.Shipment	Delivery provider process indicator
flow.shipment.pickup_point_id	flow.Shipment	Pickup point ID
flow.shipment.pickup_point_type	flow.Shipment	Pickup point type
flow.shipment.delivery_timeslot_from	flow.Shipment	Delivery timeslot start
flow.shipment.delivery_timeslot_to	flow.Shipment	Delivery timeslot end

Order field mapping (Omnium → Flow)

Order header

Flow field	Omnium source	Notes
uid	omniumOrder.Id	Used as Flow order UID
orderNumber	omniumOrder.Id	Same as UID
externalOrderNumber	omniumOrder.Id	—
orderType	omniumOrder.OrderType	Mapped to ORDER
orderState	omniumOrder.Status	See status mapping
settleState	omniumOrder.Status	Derived from Omnium status
deliveryState	omniumOrder.Status	Derived from Omnium status
store	Properties or omniumOrder.StoreId	Resolved from flow.store.id/flow.store.uid
customer	Properties or omniumOrder.CustomerId	Looked up or created in Flow
tenantUser	omniumOrder.SalesPersonId	Matched by user code, fallback to webhook user
tenantUserDisplayName	omniumOrder.SalesPersonName	Defaults to "Omnium"
origin	omniumOrder.OrderOrigin	Defaults to "OMNIUM"
createdAt	omniumOrder.Created	—
lastModifiedAt	omniumOrder.Modified	—
validUntil	Properties	flow.order.valid_until (or custom prefix)

Line items

Flow field	Omnium source	Notes
uid	Properties flow.order_line.uid or lineItemId	—
product	Properties flow.product.id or code (SKU)	Looked up by ID first, then by SKU
warehouse	Shipment warehouseCode	Resolved from shipment-to-line mapping
qtyOrdered	quantity or -returnQuantity	Negative for returns
qtyDelivered	deliveredQuantity	—
qtyReserved	reservedInventoryQuantity	—
price	placedPrice	Converted to cents
priceCost	cost	Converted to cents
vatRate	taxRate	Converted to cents
vatAmount	taxTotal	Converted to cents
discountAmount	discounted / quantity	Per-unit discount
serialNumber	serialNumber	—

Cancelled items (where canceledQuantity == quantity) are skipped during import.

Customer resolution

When creating a Flow order from Omnium, the customer is resolved in this order:

1. Look up by flow.customer.uid property

2. Look up by omniumOrder.CustomerId

3. If not found, fetch from Omnium API based on customer type (B2B or B2C)

4. Create the customer in Flow

Address resolution

The order address is resolved from:

1. Customer data (if customer exists)

2. Billing address from the Omnium order

3. First shipment address (fallback)

Order properties (header level)

Property key	Key group	Description
flow.order.id	flow.OrderHeading	Flow order ID
flow.order.uid	flow.OrderHeading	Flow order UID
flow.store.id	flow.OrderHeading	Flow store ID
flow.store.uid	flow.OrderHeading	Flow store UID
flow.customer.id	flow.OrderHeading	Flow customer ID
flow.customer.uid	flow.OrderHeading	Flow customer UID
flow.customer.loyalty_id	flow.OrderHeading	Customer loyalty ID
flow.customer_contact.id	flow.OrderHeading	Customer contact ID
flow.customer_contact.uid	flow.OrderHeading	Customer contact UID
flow.voucher_numbers	flow.OrderHeading	JSON array of voucher numbers

Configuration reference

Setting	Description	Default
OMNIUM_CLICK_COLLECT_ORDERHANDLING_UID	Handling UID for Click & Collect orders	Required for C&C
OMNIUM_ONLINE_ORDER_HANDLING_UID	Handling UID for Online orders	Required for online
OMNIUM_DEFAULT_SHIPPING_METHOD_ID	Default shipping method ID in Omnium	Required
OMNIUM_CLICK_COLLECT_EXPIRY_DAYS	Working days until Click & Collect pickup deadline	Not set
OMNIUM_INCLUDE_MAIN_PACKAGE_IN_ORDER_ITEMS	Include package parent product in order lines	false
OMNIUM_SEND_ORDER_RECEIPT_TO_OMNIUM	Enable invoice/receipt sync to Omnium	false
OMNIUM_PROPERTY_PREFIX	Prefix for read-write order properties	flow