🔗 Picqer Fulfilment: Data Mapping & Synchronisation

This guide details exactly how data flows between a Picqer Fulfilment environment and Optiply. Because working with a fulfilment partner involves different data access permissions than a standard setup, this guide outlines the specific entity mappings, visibility rules, and limitations you need to know.

🔑 1. The Impact of Your API Key (Admin vs. Scoped)

There are two different types of API keys in Picqer Fulfilment, and your choice determines what data we can map:

Admin Key: Has access to the whole organisation and can sync more objects, including native supplier data.
Scoped Key: Restricts access specifically to your company's objects and does not have access to suppliers.

⚠️ Important Limitation on Key Changes:

Alternating from one type of API key to another requires completely different data sets and configurations. If you need to switch key types, we highly recommend starting a brand new webshop/integration within Optiply to prevent severe data conflicts. Please contact support if you plan to do this. (For more details, see our dedicated guide on Admin vs. Scoped API keys).

🏢 2. Warehouse Configuration

Our Picqer Fulfilment integration supports fine-grained warehouse syncing so you can align Optiply with your 3PL's physical locations.

Select Your Warehouses: You must choose which Picqer Warehouses you want to import data from. Your selection directly dictates what we import regarding Stocks, Sell Orders, Buy Orders, and Item Deliveries.
Uploading Orders: If you want Optiply to push placed Buy Orders back into Picqer Fulfilment, you must explicitly select which Warehouse those orders should be routed to.

⚠️ Note on Historical Data: When adding or removing warehouses, data sync changes apply only from that point forward. If you need historical data updated to reflect your new warehouse setup, please request a manual update through our Customer Support team.

👁️ 3. Product Visibility & Compositions

Optiply uses specific rules to handle product bundles and determine what actually shows up in your dashboard.

Composed Products (Product Types)

Every product in Picqer has a type key. Here is how Optiply maps the unlimited_stock and assembled statuses based on that type:

Picqer type	Optiply unlimited_stock	Optiply assembled	Notes
`normal`	`false`	`false`
`unlimited_stock`	`true`	`false`
`virtual_composition`	`false`	`true`	Imports compositions; hard-sets composed product to 0 stock.
`composition_with_stock`	`false`	`true`	Imports compositions.

⚠️ Visibility Reminder: If a product evaluates to unlimited_stock = true OR assembled = true, it will not be displayed in the Optiply interface.

🗺️ 4. Data Mapping Details

Important Note on Suppliers

Suppliers: Do not exist natively in Picqer Fulfilment (unless using an Admin key).
Supplier Products: Do not exist in Picqer Fulfilment.

(Because these do not exist, mapping relies on extrapolation during the Buy Order sync—see below).

Products (`/api/v1/products`)

Optiply	Picqer	Notes
Name	`name`	Will be `""` if there is no name.
SKU Code	`productcode`
Article Code	`productcode`
Price	`price`
Unlimited Stock	`unlimitedstock`	Evaluated as `true` or `false`.
Purchase In Quantities Of	`purchase_in_quantities_of`
Stock On Hand	`stock.freestock`
Current Stock Date	`now`
Status	`active`	Evaluated as `true` or `false`.
EAN Code	`barcode`
Assembled	`assembled`	Evaluated as `true` or `false`.

Buy Orders (`/api/v1/purchaseorders` | Pulled nightly)

Optiply	Picqer	Logic / Notes
Supplier	`idsupplier` OR `supplier_name`	If using a Scoped key, Optiply extrapolates the supplier directly from the text in `supplier_name`.
Completed	`status`	IF `'received'` or `'cancelled'` → Maps to `updated` [date]. Otherwise → `'null'`.
Placed Date	`created` [date]

Note: A Buy Order with one or more products still not received does not automatically get the status "completed". It will remain null in Optiply, though, you can manually close it in the Optiply interface.

Buy Order Lines (`/api/v1/purchaseorders.products`)

Optiply	Picqer	Logic / Notes
Price	`purchaseorders.products.price`	If missing, falls back to `/api/v1/products.price`.
Quantity	`amount`
Subtotal Value	Calculated	`amount` * `price`.

Sell Orders (`/api/v1/orders`)

Optiply	Picqer	Logic / Notes
Status	`status`
Placed Date	`created` [date]
Completed Date	`updated` [date]
Total Value	`0`	Hardcoded.

Note: If the Sell Order has exactly 0 (zero) order lines, it will not be imported.

Sell Order Lines (`/api/v1/orders`)

Optiply	Picqer	Logic / Notes
Price	`products.price`
Quantity	`products.amount`
Subtotal Value	Calculated	`amount` * `price`.

Item Deliveries

Optiply	Picqer
Occurred Date	`received date` from receipt.
Quantity	`amount` from receipt.

❓ 5. Frequently Asked Questions (FAQs)

Why aren't my suppliers syncing into Optiply?

Native supplier objects do not exist in standard Picqer Fulfilment environments accessed via a Scoped API key. Instead, Optiply creates suppliers based on the text found in the supplier_name field of your imported buy orders.

Can I change from a Scoped key to an Admin key later?

While possible, it is highly disruptive. Because the two keys access entirely different data sets, switching keys mid-stream will break your sync. We strongly advise creating a brand new integration in Optiply if you need to upgrade your key type.

Why does my Buy Order still show as open in Optiply when part of it arrived?

Optiply will not mark a Buy Order as "completed" until all products on that order are received. If even one product line is pending, the order remains open. However, you can manually close the order inside Optiply if you do not expect the remaining items to arrive.

Picqer Fulfilment - Data Mapping & Synchronisation