Matalan Integration – Feature & Process Guide

Matalan is one of the Mirakl-based marketplaces connected to Pentagon Connect. It runs on standard Mirakl seller-platform behaviour, with a small number of Matalan-specific business rules layered on top — a single UK VAT setting, Matalan's own logistic classes for sizing/delivery type, and its own carrier list.

This page describes what the Matalan 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 Matalan as products first, then offers (price/stock/availability) second — an offer can't go live until its product exists on Matalan. Both steps happen automatically once a product is ready; there's no manual per-product action needed from the seller.

• Required fields: category, SKU, and a main image, plus an EAN/barcode and brand — Matalan-specific image, EAN and brand fields take priority over the general product-level fields when both are set.
• Category-specific attributes: Matalan's catalogue is organised into categories, each with its own required/optional attribute set. Every product is checked against its category's requirements before it's sent — a product missing a category-required attribute is a common reason a product fails to reach Matalan.
• Dimensions: height, length and width are combined into a single dimensions value — if even one of the three is missing, the whole thing is left blank. Weight is converted to kilograms automatically.
• Variants: products can be grouped into variant sets (e.g. size/colour of the same item) by setting a shared variation group. Each variant is still created as its own product record; you don't need to submit every sibling variant together. A variant product with none of its own variant-level attributes set is rejected as an error.

Updating products

Price, stock and full product content can each be updated after a product is live, and price/stock can be updated independently of the rest of the content:

• Price-only updates run as their own lightweight flow, for cases where only the price needs refreshing.
• Stock-only updates run as their own flow as well, used both for normal restocks and for bringing a previously zeroed-out item back with positive stock.
• Full updates (content, images, attributes, price and stock together) run as a separate flow. When some products in the same update have their price locked and others don't, the update is automatically split into two separate submissions behind the scenes (one with pricing, one without) — Matalan doesn't accept a single mixed batch.
• Protect Price — when set on a product, that product's price is left out of every update sent to Matalan, so its price on the marketplace never gets overwritten.
• Protect Quantity — when set, stock is left out of updates, so the quantity live on Matalan isn't touched.
• Protect the whole item — when set, the product is skipped entirely for that update cycle.

Deactivating / removing products

There are two distinct ways to take a listing down on Matalan:

• Zero-stock / end item: forces the item's stock to zero and marks the listing inactive on Matalan, without removing the underlying offer. This still goes through even when the connection is otherwise paused/closed — it's the one update type that isn't blocked by the closed flag.
• Offer delete / end listing: removes the offer from Matalan entirely (the product itself is marked removed on Matalan's side).
• Pausing the whole connection ("Closed") stops all further product creation and offer updates — with the zero-stock push as the one deliberate exception above.

Pricing & Stock Sync

• RRP-based discounting: if an RRP is set and it's higher than the current price, Matalan automatically shows the item as discounted (RRP as the "was" price), and RRP is sent as the live price. If no discount dates are set, the discount window defaults to two years from today.
• VAT: Matalan is UK-only, so a single VAT rate applies per listing — either standard-rated or zero-rated. If nothing is set on the listing itself, the account's default VAT setting is used as a fallback.
• Logistic class: each listing can be tagged with one of Matalan's logistic classes (e.g. Small, Large, or a set of seller-defined size/weight classes), which determines how Matalan categorises the item for delivery — for example, whether it needs a single-person or two-person delivery. This is a Matalan-side classification, not something we can override once sent.
• Dispatch time: a specific dispatch/lead time can be set per listing, overriding the account's general shipping-template default.
• Condition: only "New" condition items are accepted by Matalan.

Order Management

Getting orders

Orders are pulled from Matalan automatically and continuously — the first sync looks back 90 days of order history, and every run after that re-checks recently with a short overlap buffer so nothing gets missed. No manual import step is required.

Orders aren't always brand new when we first see them — Matalan can hand us an order that's already been accepted, shipped, or even closed out. When that happens, Pentagon Connect fills in the missing shipment and status history in one pass rather than assuming every order starts from scratch.

One status is worth calling out: Matalan's generic "closed" order status doesn't say on its own whether the order actually shipped or was cancelled. When we see it, we check whether every item on the order has been refunded — if so, the order is treated as cancelled; otherwise it's treated as shipped.

Order information we store

For every order, Pentagon Connect stores:

• Marketplace order ID, order status, currency, order/paid/delivery-by dates
• Buyer name, email and phone number
• Billing address: city, country, state/province, street (2 lines), postal code
• Shipping address: city, country, state/province, street (2 lines), postal code
• Carrier, tracking number, tracking URL, shipping cost
• Payment method, order subtotal, discount, total, marketplace fee
• Per line item: product reference, SKU, item title, item price, quantity, line status
• Sales tax, marketplace VAT and internal VAT are tracked as three separate figures at both order and line level, so different tax views can be reconciled independently

Order status is tracked in Pentagon Connect as one of: Pending, Incomplete, Ready for Shipping, Shipped, or Cancelled. An order line can also carry an open "incident" flag independently of the order's main status (see Claims / incidents below).

Shipping orders

Before an order can ship, it has to be accepted first — either automatically on download, or through a manual review step, depending on the account's setting. Matalan doesn't support accepting some of a product's order lines while rejecting others — all lines belonging to the same product must be accepted or rejected together.

Once an order is accepted and ready, Pentagon Connect pushes the carrier and tracking details to Matalan and marks the order shipped, in one automated step.

• Carrier matching: the carrier on the order is matched against Matalan's registered carrier list (see Carriers Supported below); 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.
• Partial shipment is not supported — Matalan always considers the order fully shipped in one go. Pentagon Connect can still record multiple internal shipments against an order, but Matalan only ever sees it as fully shipped.
• If Matalan already shows an order as shipped (for example, from an earlier attempt that didn't get acknowledged on our side), a repeat shipping attempt is treated as a success rather than an error, and our own records are still updated.

Cancellations

Whether an order can be cancelled — and how — depends on whether the customer has already been charged:

• Before the customer is charged, an order can only be cancelled in full; a partial cancellation isn't possible at this stage.
• After the customer is charged, cancellation follows the same per-line rules as a refund (see below), and can be partial.

See Return & Refund Reason Codes below for the cancellation reasons available.

Refunds & returns

Refunds can be full or partial (by quantity or amount), and can cover products only, or products plus shipping charges. Matalan doesn't have a separate "return" object — a customer return is handled as a refund with the reason Item returned by customer. Each refund line is submitted to Matalan as its own individual request, so one failing line never affects the others in the same batch. See Return & Refund Reason Codes below for the full reason list.

Claims / incidents

Matalan can flag an order line as having an open incident — for example, a delivery dispute raised by the customer or by Matalan itself once an item has shipped. This is reflected in Pentagon Connect at the order-line level so it's visible alongside the order. We don't currently have a documented flow for opening, escalating or resolving an incident ourselves — that side of the process sits with Matalan.

Carriers Supported

Carriers aren't a fixed list we maintain — they're whichever couriers Matalan has registered on their side, which Pentagon Connect reads live from Matalan. A carrier used on an order is matched against that live 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 reasons (customer/seller-facing):

• No response from the seller
• Out of stock
• Cancelled by the client prior to shipping
• Item returned by customer
• Item not received
• Agreement found with the vendor

Cancellation reasons (customer/seller-facing):

• Cancelled by the customer prior to shipping
• Cancelled due to out of stock
• Supplier cannot ship to this address

Matalan also applies a handful of cancellation reasons automatically through its own systems rather than as a manual choice — for example, a failed or timed-out payment debit, a failed fraud check, or a late shipment. These appear on cancelled orders but aren't something we select ourselves.

Known Limitations

• No line-level order acceptance — a product's order lines must all be accepted or all rejected together.
• No partial shipment — every order is marked fully shipped on Matalan in one go, even if fulfilment happened in parts.
• No click & collect / pick-up point delivery.
• Only "New" condition is accepted for offers.
• Partial cancellation isn't available before the customer has been charged — only a full cancellation is possible at that stage.
• Claims/incidents raised on an order are visible but not actionable by us — see Claims / incidents above.
• Carrier list is dynamic, not a fixed set we can quote in advance — it depends on what Matalan has registered for the account at the time.

Source Materials

This guide was built from Matalan's Mirakl-based integration specification documents covering authentication, taxonomy, product and offer management, order retrieval and acknowledgement, shipment, and refund/cancellation handling.