# Purchase orders

### Overview

Purchase order synchronization has two components:

* **Omnium → Flow:** Purchase orders are exported from Omnium to Flow through scheduled tasks. This is one-way — Flow does not create purchase orders in Omnium.
* **Flow → Omnium (goods reception):** When goods are received in Flow against a purchase order, the receivement is synced back to Omnium as either a goods reception confirmation or an inventory level update.

### Omnium → Flow (purchase order export)

#### Export modes

Omnium supports two distinct modes for exporting purchase orders to Flow:

| Mode                                           | Setting                      | Behavior                                             |
| ---------------------------------------------- | ---------------------------- | ---------------------------------------------------- |
| **Purchase order as purchase order** (default) | `ExportDeliveryAsPo = false` | Each Omnium PO maps to a single Flow PO              |
| **Delivery as purchase order**                 | `ExportDeliveryAsPo = true`  | Each delivery within a PO becomes a separate Flow PO |

#### Mode 1: Purchase order as purchase order

* Flow PO UID matches the Omnium purchase order ID
* Status is calculated dynamically based on delivery progress
* Line items are automatically removed if they no longer exist in Omnium
* Updates only include line items with actual changes (quantity, price, SKU, warehouse, ETA)

#### Mode 2: Delivery as purchase order

* Flow PO UID is formatted as `{PurchaseOrderId}-delivery-{DeliveryId}`
* Only delivery-specific line items are included
* Status remains constant as `SENTTOSUPPLIER`

#### Status mapping

| Condition                      | Flow PO status      |
| ------------------------------ | ------------------- |
| No items delivered             | `SENTTOSUPPLIER`    |
| Some items partially delivered | `PARTIALLYRECEIVED` |
| All items fully delivered      | `RECEIVED`          |
| Purchase order cancelled       | `CLOSED`            |

#### Field mapping

**Header fields**

| Flow field                | Omnium source        | Notes                                          |
| ------------------------- | -------------------- | ---------------------------------------------- |
| `purchaseOrderUid`        | `Id`                 | UID-sanitized (with delivery suffix in mode 2) |
| `supplierUid`             | `SupplierId`         | Required                                       |
| `currency`                | `BillingCurrency`    | —                                              |
| `supplierReferenceNumber` | `ReferenceNumber`    | —                                              |
| `note`                    | `PurchaseOrderNotes` | Comma-joined if multiple                       |

**Line item fields**

| Flow field             | Omnium source                    | Notes                     |
| ---------------------- | -------------------------------- | ------------------------- |
| `quantityOrdered`      | `OrderedQuantity`                | Converted to cents (×100) |
| `quantityReceived`     | `DeliveredQuantity`              | Converted to cents (×100) |
| `unitPrice`            | Discounted price per unit        | Converted to cents        |
| `expectedDeliveryDate` | `ETA` or `RequestedDeliveryDate` | ETA takes priority        |

#### Order reservations

The integration can track customer orders reserved against purchase order lines. Three reservation types are supported:

| Reservation type          | Description                             |
| ------------------------- | --------------------------------------- |
| `PURCHASEORDER`           | Items with confirmed delivery           |
| `PURCHASEORDER_CONFIRMED` | Ordered items without assigned delivery |
| `WAREHOUSE`               | Standalone warehouse-based reservations |

Reservations are automatically exported after the delivery or PO is created, for matching orders.

#### Package product consolidation

When `SendPackageProductOnPurchaseOrder` is enabled, component items from package products are consolidated into the parent package product before export.

### Flow → Omnium (goods reception sync)

When goods are received in Flow against a purchase order, the receivement sync engine processes the sync job.

#### Sync logic

The behavior depends on whether the purchase order exists in Omnium:

1. **PO exists in Omnium** → Send a **goods reception confirmation**
   * Flow compares its received quantities with Omnium's current quantities
   * If there is no difference, the sync is skipped (avoids unnecessary API calls)
   * If quantities differ, a goods reception is sent with line items, delivered quantities, and warehouse codes
2. **PO does not exist in Omnium** (e.g., a local PO) → Send an **inventory level update**
   * For each received item, Flow looks up the current stock level
   * Sends inventory updates to Omnium with SKU, warehouse code, and stock quantity

#### Goods reception payload

| Field               | Description                            |
| ------------------- | -------------------------------------- |
| `lineItemId`        | Purchase order item UID                |
| `deliveredQuantity` | Received quantity (converted to float) |
| `warehouseCode`     | Warehouse UID                          |

#### Prerequisites

Goods reception sync only runs when:

* The purchase order has an `externalId` (linked to Omnium)
* The store has `OMNIUM_FLOW_STOCK_MASTER` set to `true`

If either condition is not met, the sync is skipped (marked as successful without action).

#### Quantity difference detection

Before sending a goods reception, the sync engine compares Flow's received quantities against Omnium's current delivered quantities per line item. The comparison uses the purchase order item's `externalId` first, falling back to the item UID. Only if a difference is found will the API call be made.

### Configuration reference

| Setting                             | Description                                | Default  |
| ----------------------------------- | ------------------------------------------ | -------- |
| `ExportDeliveryAsPo`                | Export each delivery as a separate PO      | `false`  |
| `SendPackageProductOnPurchaseOrder` | Consolidate package components into parent | `false`  |
| `PurchaseNumberSeriesUid`           | Flow number series for PO numbers          | Required |
| `OMNIUM_FLOW_STOCK_MASTER`          | Store-level: Flow is stock master          | `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/purchase-orders.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.