John Lewis Integration – Feature & Process Guide

John Lewis runs its third-party marketplace on Mirakl, so from Pentagon Connect's side this is a standard Mirakl integration rather than a bespoke John Lewis build. Products and offers are pushed to John Lewis's Mirakl instance, orders are pulled back automatically, and shipments, cancellations and refunds flow through the same standard Mirakl mechanisms Pentagon Connect uses for its other Mirakl marketplaces.

A small number of John Lewis-specific rules sit on top of the standard Mirakl pattern — notably a pay-on-acceptance payment workflow that changes how cancellations work, a courier-mapping table for shipping, and some John Lewis-specific field limits and reason codes.

Quick Reference

Product Management

Pricing & Stock

Orders & Fulfilment

Refunds, Returns, Cancellations & Claims

Product Management

Creating products

New products are sent to John Lewis as products first, then offers (price/stock/availability) second — an offer can't go live until its product exists on John Lewis. Both steps happen automatically once a product is ready; there's no manual per-product action needed.

• Required fields: category, SKU, title, description, brand, and a main image, plus every attribute John Lewis's category taxonomy marks as required for that product's category. A product missing a category-required attribute is the most common reason a product fails to reach John Lewis.
• Barcode (EAN): Pentagon Connect looks for a marketplace-specific EAN first, then falls back to the product's own EAN, then its UPC. If none of those are available, Pentagon Connect can still get the product accepted by asking John Lewis to auto-generate a barcode rather than blocking the listing.
• Title and description length limits: the short title John Lewis displays is trimmed to 20 characters, and the product name is capped at 50 characters by John Lewis itself — long titles are silently truncated, not rejected.
• 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, and removing a product from a group is done by re-pushing it without that grouping.
• Warnings returned during import are treated as a successful creation — this is standard Mirakl behaviour, not something specific to John Lewis, and isn't something to chase 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 too — used both for everyday quantity changes and for re-activating a previously zero-stocked offer.
• Full updates (content, images, attributes, price and stock together) are split into two variants depending on whether price is protected, because John Lewis rejects a batch that mixes priced and un-priced offers.
• Protect Price — when set on a product, price is left out of every update sent to John Lewis, so its price on the marketplace never gets overwritten.
• Protect Quantity — when set, stock is left out of updates, so the quantity live on John Lewis isn't touched.
• Protect the whole item — when set, the product is skipped entirely for a full content update, though a stock-only update can still go through.
• Zero-stock override: if a product is due to be zero-stocked (taken off sale), Pentagon Connect always sends quantity 0 for it, even if Protect Price, Protect Quantity, Protect the whole item, or Pause are all set — ending a listing always wins.

Deactivating / removing products

Marking a product "Closed" stops all further creation and updates to it on John Lewis, with one exception: if that item also needs its stock zeroed out, that zero-stock push still goes out even while it's closed, so the listing actually comes off sale rather than being left showing as available. There's no separate delete action — ending a listing on John Lewis (removing it from sale) is a distinct, final step from simply pausing it.

Pricing & Stock Sync

• RRP-based discounting: if an RRP is set and it's higher than the current price, Pentagon Connect sends the RRP as the discount reference and the item shows as discounted on John Lewis. If no discount dates are set, the discount window defaults to two years from today.
• Lead time to ship: taken from the product's own dispatch time if set, otherwise from its shipping template, otherwise from the account's default shipping template; if none of those apply, no lead time is sent.
• Condition: only "New" condition items are accepted by John Lewis — any other condition is rejected before it's sent.
• Stock updates and zero-stock (ending a listing) run as separate flows from a full content update, so stock can be kept in sync independently of price or content changes.

Order Management

Getting orders

Orders are pulled from John Lewis automatically and continuously — the first run brings in the last 90 days of orders, and every run after that picks up anything new or changed since the last check. Because an order can first be seen by Pentagon Connect at any point in its life (not just brand new), the integration has to recognise and correctly backfill an order that already arrives part-way through its lifecycle — for example, one that's already shipped by the time it's first downloaded — rather than assuming every order starts from scratch.

Order information we store

For every order, Pentagon Connect stores:

• Marketplace order ID, order status, currency, created date
• Buyer ID, buyer email, buyer first and last name, buyer locale
• Billing address: name, phone number, company, country, state, street (2 lines), city, postal code
• Shipping address: name, phone number, company, country, state, street (2 lines), city, postal code
• Payment method, order subtotal, order total, discount amount/type, marketplace fee, total fee, payment date and transaction ID
• Carrier (name and code), shipping service, shipping cost, tracking number, tracking URL, shipped date
• Per line item: channel item ID, SKU, product title, item price, quantity, line status, line shipping cost and shipping tax
• 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: Incomplete, Awaiting Acknowledge, Pending, Ready for Shipping, Shipped, or Cancelled. An order can also carry an open "Incident" flag at the line-item level (see Claims below) independently of its main status.

Shipping orders

Once an order is accepted and its shipment is ready, Pentagon Connect pushes the carrier and tracking details to John Lewis and validates the shipment in the same run.

• Courier matching follows a priority order: first, the carrier on the order is matched against a John Lewis-specific courier-mapping table; 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 "Other" carrier so tracking information isn't lost (not every Mirakl marketplace supports this fallback, but it's implemented as the Mirakl standard).
• The tracking URL shown to the customer comes from the order's own tracking URL if set, or from the matched courier's tracking-URL template with the tracking number substituted in.
• Partial shipment is not supported — John Lewis always ships the full order in a single shipment. Pentagon Connect can still record multiple internal shipments against an order, but only one, full shipment reaches John Lewis. Because of this, it's expected (not an error) for an order to sometimes already show as shipped on John Lewis's side by the time Pentagon Connect tries to validate the shipment — in that case Pentagon Connect just re-syncs the order to "Shipped" instead of treating it as a failure.

Cancellations

John Lewis runs on a pay-on-acceptance payment workflow, meaning the order is charged as soon as it's accepted. This has a direct effect on what cancellation looks like:

• Line-level cancellation is not used for John Lewis at all — by the time a line could be cancelled it has usually already been charged, so refunds are used instead for anything post-acceptance. Partial cancellations aren't supported.
• Full-order cancellation is available for orders that have been accepted but not yet shipped — this is treated as the "not yet charged" window. Only whole-order cancellation is supported here; partial cancellation attempts are blocked.

Refunds & returns

Refunds can be full or partial (by quantity or amount), and can cover products only, or products plus shipping charges. Each refund line is sent to John Lewis as its own individual request rather than batched together, because a single bad line would otherwise fail the entire batch. Pentagon Connect's own validation makes sure a line isn't refunded for more than what's left refundable on it.

Returns are supported and use their own dedicated set of return reasons (see Return & Refund Reason Codes below), separate from the refund reason list.

Claims / incidents

John Lewis's claims mechanism ("Incident") can be opened by the customer or by John Lewis once an order is shipping, shipped, or received. An incident is tracked per order line rather than as a whole-order status change. If an order isn't yet paid when an incident is raised, payment for that order isn't received.

Carriers Supported

Carriers aren't a fixed list Pentagon Connect maintains — they're whichever couriers John Lewis has registered on their side, read live from John Lewis. A carrier used on an order is matched against that live list via a John Lewis-specific 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 (as returned by John Lewis's own reason list) include:

• Goods are faulty / damaged / not wanted / wrong goods supplied / parts missing
• Safety concern
• Returning under warranty or guarantee (multiple guarantee-length variants, e.g. 1, 2, 5, 7 or 10 year)
• Delivery issue, sleep/comfort trial return, product recall, or lost on the return journey
• Out of stock, no response from the shop, or agreement reached directly with the vendor
• Item returned, item not received, unable to process return, or return reason unknown
• Product allowance or a price-match adjustment
• Supplier fulfilment failure, or no stock available for the order line

Return reasons (used specifically for customer returns, separate from the refund list) include:

• Broken, damaged, defective, or counterfeit item
• Delivered product different from what was ordered, or a missing item
• Changed my mind / don't want the product anymore / don't like the product
• Quality not as expected
• Wrong size or wrong colour, or product doesn't fit (too big / too small)
• Defective on arrival
• Other reason

Cancellation reasons include a small set of seller-visible reasons (e.g. cancellation or price adjustment before acceptance) alongside several system-generated reasons Pentagon Connect can encounter but doesn't itself trigger — for example a failed or timed-out debit, a failed fraud check, or a late-shipment cancellation.

Known Limitations

• No partial shipment — every order ships to John Lewis as one complete shipment, even if it was recorded as multiple shipments internally.
• No line-level order acceptance — accept/reject is all-or-nothing per product, and bundle SKUs are only acknowledged at the parent level, never their component lines.
• No line-level or partial cancellation — only full-order cancellation is available, and only in the window after acceptance but before shipment; after that, refunds are the only route.
• Only "New" condition is accepted for offers — anything else is rejected before it reaches John Lewis.
• Title/description length limits — the short title is trimmed to 20 characters and the product name capped at 50; long values are truncated silently rather than rejected.
• Carrier list is dynamic, not a fixed set that can be quoted in advance — it depends on what John Lewis has registered for the account at the time.
• Refunds are sent one line at a time, never batched, so a single bad refund line doesn't fail every other refund line on the same order.

Source Materials

This guide was built from Pentagon Connect's internal John Lewis Mirakl integration scope documents covering authentication, taxonomy, product and offer creation and updates, order retrieval, order acknowledgement, shipping, and the refund/cancellation flow.