Freemans Integration – Feature & Process Guide

Freemans is one of the Mirakl-based marketplaces connected to Pentagon Connect. Like our other Mirakl sellers, product and offer data is pushed to Freemans as file imports, and orders, shipments, cancellations and refunds are handled through Mirakl's standard order flow — so most of the behaviour here follows the same patterns as our other Mirakl integrations, with a number of Freemans-specific rules layered on top (a larger set of Freemans-only mandatory product fields, a single accepted product condition, and VAT/discount handling that's more limited than on some other marketplaces).

This page describes what the Freemans integration supports — which product, pricing, order and refund actions are available, what data we capture, and what isn't currently supported.

Quick Reference

Product Management

Pricing & Stock

Orders & Fulfilment

Refunds, Returns, Cancellations & Claims

Product Management

Creating products

New products are sent to Freemans as products first, then offers (price, stock and availability) second — an offer can't go live until its product exists on Freemans. Both steps happen automatically once a product is ready.

• Required data: category, SKU, description, images, fabric/composition, dimensions, and packaging/returns/dispatch details. Every product is checked against Freemans' category-specific requirements before it's sent, and a missing required attribute is the most common reason a product fails to reach Freemans.
• Freemans requires a larger set of mandatory fields than most marketplaces, including approval terms, returns handling method, country of dispatch, country of supplier, and warehouse/storage location. Most of these have sensible defaults (for example, country of dispatch defaults to UK) but can be overridden per product.
• Product SKU is capped at 50 characters — longer values are rejected.
• Variants: products can be grouped into variant sets (e.g. size/colour of the same item) via a shared variation group reference. Each variant is still created as its own product record — you don't need to submit every sibling variant together, and a product can be taken out of a variation group later by re-sending it without that reference.
• Only one product condition is supported: New.

Updating products

Price, stock and full product content can each be updated independently after a product is live:

• Price-only updates run as their own lightweight flow, for cases where only the price needs refreshing.
• Full updates (content, images, attributes, price and stock together) run as a separate flow. Products with price protection on are always processed separately from products without it — Freemans doesn't allow priced and non-priced changes to be mixed together in the same update.
• Protect Price — when set, a product's price is left out of every update sent to Freemans, so its live price is never overwritten.
• Protect Quantity — when set, stock is left out of updates, and dedicated stock-only updates are skipped entirely for that product.
• Protect the whole item — when set, the product is skipped from content and price updates entirely. Stock can still be zeroed (see below) even when this is set.
• RRP can be sent alongside the regular price, but Freemans doesn't support the automatic discount-window feature available on some other marketplaces — discount pricing is out of scope for this integration.

Deactivating / removing products

Freemans supports two distinct ways to take a listing down:

• Zero-stock: sets the product's stock to zero and moves the listing to inactive. This still goes out even when a product is otherwise fully locked ("Closed") — it's the one update type that a full lock doesn't block.
• Delete: removes the offer from Freemans outright, rather than just zeroing its stock.
• Closed — when set on a product, it stops all creation and updates to Freemans, with the zero-stock exception above.

Pricing & Stock Sync

• RRP is supported and sent to Freemans alongside price, but isn't turned into an automatic on-site discount — Freemans doesn't currently support the discount-date-window feature used on some other marketplaces.
• VAT is mandatory, but the amount sent is currently fixed at zero — only the VAT rate/code is set dynamically, taken from the listing's VAT setting or the account default. This is a known limitation rather than a configurable choice.
• Eco-tax / eco-contribution is not documented for Freemans (this is a requirement seen on some other, France-based marketplaces; Freemans is a UK marketplace).
• Condition: only "New" condition items are accepted.
• Logistic class: each product is assigned a logistic class (e.g. Small, Large, or a supplier-specific class) that Freemans uses to determine how the item is shipped and handled.

Order Management

Getting orders

Orders are pulled from Freemans automatically and continuously — the first run looks back 90 days, and every run after that picks up from where the previous one left off. Existing orders already in Pentagon Connect have their status kept in sync as they progress (accepted, shipped, refunded, etc.); no manual import step is required.

Freemans' own "closed" order status doesn't distinguish between a shipped outcome and a cancelled one on its own — when an order reaches it, Pentagon Connect checks the refund/cancellation history on each line to work out whether the order actually shipped or was cancelled.

Order information we store

For every order, Pentagon Connect stores the buyer, delivery and line-item details needed to fulfil it, along with:

• Marketplace order ID and current status
• Whether the customer has actually been charged yet — this determines whether a cancellation or a refund request is used
• Whether the order is currently eligible for cancellation and/or refund
• Per-line cancellation and refund history
• Carrier and tracking number once shipped
• The transaction ID(s) Freemans returns for each refund/cancellation — a single refund covering multiple items can produce several transaction IDs, since each item is processed separately

Shipping orders

Once an order is accepted and ready, Pentagon Connect sends the carrier and tracking details to Freemans and marks the order shipped in the same pass.

• Carrier matching: the carrier on the shipment is matched against Freemans' own registered carrier list; if there's no match, an account-level default carrier is used if one is set; if neither applies, the carrier name and tracking number are still sent through as a generic fallback so tracking information isn't lost.
• Partial shipment is not supported — Freemans always shows the full order as shipped in one go, even though Pentagon Connect can record multiple internal shipments against the order.
• If Freemans already shows the order as shipped by the time we try to mark it (for example, a timing clash with another process), that's treated as a success rather than an error.

Cancellations

Before the customer has been charged, only a full-order cancellation is supported — a partial cancellation can't be requested at this stage. Once the customer has been charged, cancellation-style requests go through the same flow as refunds (see below) and can be partial.

Refunds & returns

Refunds can be full or partial (by quantity or amount), and can cover product cost, shipping charges, or both. Freemans doesn't have a separate "return" object — a customer return is handled through the same refund flow, tagged with a return-type reason rather than a refund-type reason so the two stay distinguishable.

Each item on a refund or cancellation request is sent to Freemans as its own separate action. If a request covers several items and some succeed while others fail, the order is marked partially complete with the specific failures recorded — the whole request isn't rolled back or retried automatically.

Claims / incidents

Freemans has an incident concept: a buyer (or Freemans) can raise an incident against an order once it's shipping, shipped, or received. Incidents are tracked per order line rather than as a whole-order status change. The correct handling for an order that arrives already showing an open incident on its very first download was left as an open question in the original scope material — worth double-checking against current behaviour if it comes up in support.

Carriers Supported

Carriers aren't a fixed list we maintain — they're whichever couriers Freemans has registered on their side, read live from Freemans. A carrier used on a shipment is matched against that list via our own carrier-mapping table (or an account-level default); if it doesn't match anything registered, the carrier name and tracking number are still sent through under a generic "Other" carrier so tracking information isn't lost.

Return & Refund Reason Codes

Refund and cancellation reasons aren't a fixed list maintained in Pentagon Connect — they're read directly from Freemans' own reason list and filtered down to refund-type and return-type entries (other reason types Freemans exposes are ignored). Because refund and return reasons can otherwise look identical, each one is labelled "[REFUND]" or "[RETURN]" so they stay distinguishable.

A default reason can be configured per type (refund, cancellation, or both); if a refund or cancellation is requested with no reason given and no default configured, the request is blocked until one is set. The specific reason text Freemans exposes is not enumerated in the current source material.

Known Limitations

• No partial shipment — an order always ships to Freemans as one complete unit, regardless of how it's fulfilled internally.
• No line-level order acceptance — a product line must be entirely accepted or entirely rejected; this also means bundle components can't be acknowledged individually.
• Only "New" condition is accepted for offers.
• No automatic discount window — RRP is supported, but the discount-date-window feature available on some other marketplaces is explicitly out of scope for Freemans.
• VAT amount is currently fixed at zero at the offer level — only the VAT rate/code is set dynamically.
• SKU length limits — product SKU is capped at 50 characters, and offer SKU is capped at 40 characters and can't contain a "/".
• No partial cancellation before the customer is charged — only full-order cancellation is supported at that stage.
• Refund/cancellation requests are processed one item at a time, so a request covering several items can succeed for some and fail for others.
• Freemans' "closed" order status is ambiguous — it doesn't distinguish a shipped outcome from a cancelled one on its own; this has to be inferred from each line's refund/cancellation history.
• The correct handling for an order that first arrives already showing an open incident was left as an open question in the original scope material.
• Carrier list is dynamic, not a fixed set we can quote in advance — it depends on what Freemans has registered for the account at the time.

Source Materials

This guide was built from Freemans' Mirakl integration specification documents covering product and offer creation and updates, order retrieval, order acknowledgement, shipment, and refund/cancellation handling.