# 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` |


---

# 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/invoices-and-receipts.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.