🔗 QLS: Data Mapping & Synchronisation

This guide details exactly how data flows between your QLS environment and Optiply. It outlines synchronisation schedules, unique configuration options, and the specific logic used to handle stock calculations and order statuses.

⏱️ 1. Synchronisation Overview

The table below outlines how often Optiply pulls data from (or pushes data to) QLS.

Entity	Sync Direction	Frequency
Products	QLS → Optiply	Every 30 mins
Product Stock Only	QLS → Optiply	Every 10 mins
Product Deletions	QLS → Optiply	N/A (See note below)
Suppliers	QLS → Optiply	Every 30 mins
Supplier Products	QLS → Optiply	Every 30 mins
Sell Orders	QLS → Optiply	Every 30 mins
Buy Orders (V1 & V2)	QLS → Optiply	Every 30 mins
Buy Orders (V1 & V2)	Optiply → QLS	Every 15 mins
Receipt Lines (Item Deliveries)	QLS → Optiply	Every 30 mins

⚠️ Important Sync Rules & Limitations:

Deleted Products: QLS currently does not flag deleted products via their API. Because we cannot accurately identify them, product deletions are not automatically synced. (We are exploring alternatives to solve this).
Supplier Product Deletions: Supplier Products are deleted in Optiply if they return an empty object in the Suppliers column, or if they disappear entirely from the Products detail array in QLS.
Buy Order Exports: Exporting placed Buy Orders from Optiply to QLS is supported on either the V1 or V2 endpoints.

⚙️ 2. Integration Options & Features

Optiply offers two specific configuration options for your QLS connection to customise your data flow:

Product Stock Only from QLS (sync_prod_stock_only)
- Default: False
- If enabled, Optiply uses the QLS integration only to pull stock levels. No other product data, supplier data, or order data will be pulled or processed. (Note: This speeds up the stock sync to every 10 minutes).
Supplier Products from QLS (use_supplier_products)
- Default: True
- Allows you to choose whether Optiply should pull your Supplier Products from QLS. If you manage suppliers elsewhere, you can toggle this off.

🗺️ 3. Product & Supplier Mapping

Products Source Path: `/fulfilment-products`

Optiply Field	QLS Field	Notes
Article Code	`id`
Name	`name`
SKU Code	`sku`
EAN Code	`ean`	Mandatory. Products without an EAN will not be mapped, as it is required to send Buy Orders to QLS.
Price	`price_store`
Assembled	`bundle_product`	`False` if the `bundle_product` array is empty, `True` otherwise.
Unlimited Stock	Hardcoded	Hardcoded to `False` upon creation in Optiply. Will not be updated after creation.
Stock Level	Calculated	Uses the formula: `amount_available` - `amount_backorder` + `amount_internally_moving`.
Created Date	`created`

Suppliers

Optiply Field	QLS Field
Name	`name`
Remote ID	`id`

Supplier Products Source Path: `/fulfilment-products`

Optiply Field	QLS Field	Logic / Notes
Name	`name`	Multiple suppliers per product are supported.
SKU Code	`sku`	Mapped by default; can be disabled upon request.
EAN Code	`ean`
Price	`price_cost`	Mapped by default. Note: This is mapped from the main product, meaning all suppliers for a product will share the same purchase price.
Lot Size	`order_unit` OR `product_master_cartons.amount`	Maps from `order_unit` by default. Can map from master cartons upon request (uses the minimum value if multiple amounts exist).
Article Code	`suppliers._joinData.supplier_code`

🛒 4. Sell Order Mapping

Optiply Field	QLS Field	Notes
Total Value	Calculated	Sum of the lines' `subtotalValue`.
Placed Date	`createdAt`
Remote ID	`id`

Sell Order Lines

Product ID: optiplyWebshopProductArticleCode
Quantity: amount_ordered
Subtotal Value: price_store * quantity

⚠️ Sell Order Sync Limitation:

Optiply does not sync changes made to Sell Orders after their initial import. Edits to order lines, deleted lines, or new lines added to existing orders in QLS will not be reflected in Optiply.

📦 5. Buy Order Mapping (Importing: QLS → Optiply)

Because QLS operates with two different API versions, the mapping logic depends on which version your integration is utilising.

Buy Orders (V1 vs. V2 Logic)

Optiply Field	QLS V1 Field	QLS V2 Field
ID & Remote ID	`id`	`id`
Supplier ID	Extrapolated from `supplier_name`	Extrapolated from `supplier_name`
Placed Date	`created`	`created`
Completed Date	Sets to `DateNow` when status is completed.	Sets to `DateNow` when status is archived.

Buy Order Lines (V1 vs. V2 Logic)

V1 Sync Rules: Does not sync order line changes after the initial pull.
V2 Sync Rules: Fully syncs Order Line changes (new lines added, quantity edits, and line deletions will update in Optiply).

Optiply Field	QLS V1 Field	QLS V2 Field
Product ID	`products.id`	`purchase_order_products.products.id`
Quantity	`products.amount_expected`	`purchase_order_products.amount`
Subtotal Value	`amount_expected` * `price_cost`	`amount_expected` * `price_cost`
Buy Order ID	`id`	`id`

Receipt Lines / Item Deliveries (V1 vs. V2 Logic)

Note: For V2, Receipt Lines come from the BuyOrderLinesById_v2 endpoint, specifically within the purchase_order_products.purchase_order_label_products tag.

Optiply Field	QLS V1 Field	QLS V2 Field
Quantity	`amount_received`	`purchase_order_label_products.amount`
Occurred Date	`created`	`purchase_order_label_products.created`
Buy Order Line ID	`optiply.buyOrderLineId`	`optiply.buyOrderLineId`
Remote ID	`receipt_id`	N/A

📤 6. Exporting Buy Orders (Exporting: Optiply → QLS)

When Optiply pushes a placed Buy Order into QLS, we sort the Buy Order Lines by SKU Code (Ascending). This ensures your lines match easily between the Optiply frontend and the QLS frontend.

Optiply	QLS V1 Destination	QLS V2 Destination
Order ID	`customer_reference`	`customer_title`
Supplier	`supplier_name`	`suppliers` (via `supplier.remoteId`)
Created Date	N/A	`deliveries.estimated_arrival`
Line Product	`products.product_id`	`purchase_order_products.fulfillment_product_id`
Line Quantity	`products.amount_expected`	`purchase_order_products.amount`

❓ 7. Frequently Asked Questions (FAQs)

Why aren't some of my products importing from QLS?

In order to successfully send Buy Orders to QLS, an EAN code is strictly required. If a product does not have an EAN configured in QLS, Optiply will skip mapping it entirely.

If a customer changes their Sell Order in QLS, will Optiply update the stock requirement?

No. Optiply only imports Sell Orders once. If order lines are changed, deleted, or added to an existing Sell Order in QLS later, those changes will not sync to Optiply.

Why is my Buy Order showing as completed in QLS, but not in Optiply?

This depends on your API version. If you are on V1, Optiply marks the order complete when QLS says completed. However, if you are on V2, Optiply waits until the QLS status is officially changed to archived.

QLS - Data Mapping & Synchronisation