Invoices and receipts

Overview

Invoice synchronization is one-way from Flow to Omnium. When a receipt is created in Flow Retail, it can optionally be sent to Omnium as an invoice with an attached PDF document. This is controlled by the OMNIUM_SEND_ORDER_RECEIPT_TO_OMNIUM setting.

Sync process

1. A receipt is created in Flow (after settlement is completed)

2. An invoice sync record is queued in external_order_receipt_sync

3. During the next order sync cycle, the sync engine processes pending invoice records

4. For each pending receipt:

   • A PDF receipt is generated from Flow

   • An invoice is created in Omnium via the Invoice API

   • The PDF file is attached to the Omnium invoice

   • The sync record is marked as complete with the Omnium invoice ID

If the PDF generation fails, the invoice is not created in Omnium. This ensures Omnium never has an invoice without its corresponding document.

Invoice types

Standard invoice

For regular sales and return orders, the invoice includes the actual order line items, payments, and customer details. Each line item on the receipt is mapped to an Omnium invoice line using the same mapping as order lines.

Payment invoice

For payment-type orders (e.g., down payments, deposits), the invoice is simplified:

• A single line item with SKU REMITTANCE and quantity 1

• The display name includes the referenced voucher number and order number (e.g., "Payment for invoice 12345 (order #678)")

• The amount is the total settlement amount from the receipt

Invoice field mapping

Omnium field	Flow source	Notes
id	orderReceipt.Uid	—
orderId	orderReceipt.Order.Uid	—
invoiceDate	orderReceipt.CreatedAt	—
invoiceNumber	orderReceipt.VoucherNumber	—
amount	orderReceipt.OrderTotals.GrandTotal	Converted to float
amountExcludingTax	Grand total minus VAT	Converted to float
currency	tenant.Country.Currency	—
deliveryDate	orderReceipt.SettledAt	—
invoiceDueDate	orderReceipt.SettledAt	—
customerEmail	Contact or address email	Contact person takes priority
customerId	customer.Uid	—
customerName	Display name	Contact person, invoice address, or order address
customerType	"B2C" or "B2B"	Based on customer/address
customerAddress	Invoice address or order address	Invoice address preferred
origin	order.Origin	—
storeId	order.Store.Uid	—
marketId	store.ExternalId	—

Invoice line items

For standard invoices, line items use the same mapping as order line items (see Orders), with these differences:

• Line items are sourced from the receipt items (not the order items)

• Each line includes the receipt voucher number as a property

• The voyado.order.id property is set to the voucher number

For payment invoices, a single line item is created:

Field	Value
code	"REMITTANCE"
displayName	"Payment for invoice {voucherNumber} (order #{orderNumber})"
quantity	1
placedPrice	Receipt settlement total
extendedPrice	Receipt settlement total

Invoice payments

Payments are mapped the same way as order payments (see Orders):

• Only completed settlements are included

• Pre-payments and settlements linked to pre-payments are skipped

• Cash and cashback settlements are merged

Invoice properties

Property key	Key group	Description
flow.order_number	flow.Invoice	Flow order number
flow.customer.loyalty_id	flow.Invoice	Customer loyalty ID (standard invoices only)
flow.seller.code	flow.Invoice	Seller user code
flow.order.type	flow.Invoice	Order type

PDF attachment

After the invoice is created in Omnium, the receipt PDF is attached:

• File name: {voucherNumber}.pdf

• API call: AddFileToInvoice(invoiceId, fileName, pdfContent)

The PDF contains the full receipt as rendered by Flow's receipt template engine.

Configuration reference

Setting	Description	Default
OMNIUM_SEND_ORDER_RECEIPT_TO_OMNIUM	Enable invoice sync to Omnium	false