B&Q Integration – Feature & Process Guide

B&Q is Kingfisher's UK home-improvement marketplace and one of the Mirakl-based integrations connected to Pentagon Connect. It's a standard Mirakl Marketplace Platform implementation, so most of its behaviour matches Pentagon Connect's other Mirakl-powered marketplaces, with B&Q's own attribute requirements, condition list and courier set layered on top.

This page describes what the B&Q 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 B&Q as products first, then offers (price/stock/availability) second — an offer can't go live until its product exists on B&Q. Both steps run automatically once a product is ready.

• Required fields: category, SKU, and a main image, plus an EAN (barcode) sourced from a B&Q-specific EAN field first, falling back to the product's general EAN. A missing EAN blocks product creation entirely, before anything is sent.
• Recommended fields: up to 8 secondary images.
• Category-specific attributes: B&Q's catalogue is organised into categories, each with its own required/recommended attribute set (a long list of B&Q-specific fields — unique selling points, pack quantity/type, guarantee terms, sustainability/material flags, and similar). Every product is checked against its category's requirements before being sent — a product missing a category-required attribute is the most common reason a product fails to reach B&Q.
• Variants: products are grouped into variant sets (e.g. size/colour of the same item) by setting a shared Variation Group. Without a Variation Group, only general product attributes are sent; with one, both general and variant-specific attributes are sent, and if the same attribute is set at both levels, the variant-specific value wins. Each variant is still created as its own product record; removing a product from a group is done by resending it without that field.
• Warnings count as success: warning-level results on the product import report are treated as a successful creation (standard Mirakl behaviour), though this was still being confirmed specifically for B&Q at the time of writing.

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.
• Full updates (content, images, attributes, price and stock together) run as a separate flow.
• Protect Price — when set, that product's price is left out of every update sent to B&Q, so its price on the marketplace is never overwritten.
• Protect Quantity — when set, stock is left out of updates, so the quantity live on B&Q isn't touched.
• Protect the whole item — when set, the product is skipped entirely for content/price updates; a quantity-only update can still go through.

Deactivating / removing products

Marking a product "Closed" means only a zero-stock update is ever sent for it going forward — this applies to both brand-new and already-listed products. There's no separate delete action; closing is how a listing is taken down.

Pricing & Stock Sync

• RRP-based discounting: if RRP is set and higher than the selling price, B&Q receives RRP as the reference ("was") price and the selling price as the discounted price, so the item displays as on sale. If no discount dates are set, the window defaults to two years from today. If RRP isn't set or isn't higher than the price, no discount fields are sent.
• Condition: unlike some Pentagon Connect Mirakl integrations, B&Q accepts a full condition range — New, Excellent, Very Good, Good, Sufficient, and four grades of Refurbished (like new, very good, good, acceptable) — matched against a fixed condition list.
• Protect Price / Protect Quantity flags (see Product Management above) apply equally to routine price and stock sync, not just full updates.
• VAT-per-country and eco-tax/EPR handling are not covered in the B&Q source material — see Known Limitations.

Order Management

Getting orders

Orders are downloaded from B&Q automatically. The first run pulls the last 90 days of orders; every run after that picks up anything new or changed since the previous run, with new orders and status updates handled in the same automated pass — no manual import step is required.

Orders don't always arrive at Pentagon Connect at the very start of their lifecycle — an order can be downloaded for the first time already at a later stage (e.g. already shipping or already shipped), and the integration handles this by picking up wherever the order actually is rather than assuming every order starts fresh. If an order is downloaded already accepted, it's recorded as accepted straight away; if it's downloaded already shipped, its shipment and tracking details are backfilled automatically rather than waiting for a separate shipping step.

Order information we store

For every order, Pentagon Connect stores:

• Marketplace order ID, order status, currency, and key dates
• Buyer contact details, including billing and shipping phone numbers
• Billing and shipping addresses
• Payment method, order subtotal/total, discount amount, and marketplace fee information
• Carrier, shipping cost, tracking number/URL, and shipped date
• Per line item: SKU, product title, item price, quantity, and 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
• Whether the order has an open claim/incident on any line (see Claims / incidents below), tracked independently of the order's main status

Order status is tracked as one of: Incomplete, Pending, Ready for Shipping, Shipped, or Cancelled. Orders are auto-accepted by default.

Shipping orders

Once an order is accepted and ready, Pentagon Connect pushes carrier and tracking information to B&Q and marks the order shipped.

• Carrier matching: the carrier on the order is checked against B&Q's registered courier list via an account-level 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 under a generic "Other" carrier so tracking information isn't lost.
• Partial shipment is not supported — Mirakl always marks the whole order shipped once any shipment is sent for it, even if only part of the order actually went out.
• If B&Q already considers an order shipped (for example, it was marked shipped directly on the marketplace) when Pentagon Connect tries to ship it, the attempt is rejected by B&Q — this is treated as a status-sync situation and the order is simply marked shipped internally rather than as a failure.

Cancellations

• Before an order has been charged to the customer, only a full cancellation of the order is possible — partial cancellation isn't available at that stage.
• Once an order has been charged, cancellation can be requested at the order-line level.
• If an order is somehow both cancellable and refundable at the same time, cancellation is treated as the default action.
• See Return & Refund Reason Codes below for the cancellation reasons available.

Refunds & returns

• Refunds are requested at the order-line level and can be full or partial, covering products and/or shipping charges.
• Each refund or cancellation line is sent to B&Q as its own separate request, so one failure doesn't affect the others in the same batch.
• A single refund can correspond to more than one transaction on B&Q's side; the outcome is tracked accordingly as fully successful, partially successful (with the failing part flagged separately), or failed.
• B&Q doesn't have a distinct "return" object — a customer return is handled as a refund, using a reason that describes the return (e.g. changed mind, wrong product delivered, damaged). See Return & Refund Reason Codes below.

Claims / incidents

Operators and customers can open a claim ("Incident") on an order once it's shipping, shipped, or received. An incident is tracked per order line rather than as a change to the whole order's status. If an order hasn't been paid yet when an incident is opened, the seller doesn't get paid for that line. Exactly how to handle an order that's downloaded for the very first time already showing an open incident was still an open question in the source documentation — see Known Limitations.

Carriers Supported

Carriers aren't a fixed list we maintain — they're whichever couriers B&Q has registered on their side, which Pentagon Connect reads live from B&Q. A carrier used on an order is matched against that live list via an account-level courier-mapping table, or an account-level default carrier if no match is found; if neither applies, the carrier name and tracking number are still sent through under a generic "Other" carrier so tracking information isn't lost. Exactly when the integration should fall back to "Other" versus flag an error was still an open question in the source documentation, so treat unmapped-carrier shipping issues as worth double-checking against current behaviour.

Return & Refund Reason Codes

Refund reasons (current, seller-selectable):

• Damaged
• Missing part
• Overbought
• Wrong product delivered
• Could not assemble
• Product recall
• Out of stock
• Item not received by customer
• Order cancelled prior to dispatching (customer requested)
• Customer has changed mind

Cancellation reasons:

• Cancelled by the customer prior to shipping
• Cancelled due to late shipment (system-generated)
• Cancelled due to payment/debit failure (system-generated)
• Cancelled due to payment/debit timeout (system-generated)

B&Q's reason list also still returns a set of older, deprecated refund reasons alongside the current ones above; these are legacy values from before the reason list was refreshed and shouldn't be relied on for new refunds.

Known Limitations

• No documented authentication/API-key setup steps for B&Q exist in the current source material — flag this as a documentation gap if credential setup is ever needed, not necessarily a technical gap.
• No partial shipment — a shipment covering only part of an order still marks the whole order as shipped on B&Q.
• Open-incident-on-first-download is unresolved — how to handle an order downloaded for the first time already showing an open claim/incident was an open question in the source documentation.
• Shipping an already-shipped order is a real, expected case — if an order is shipped directly on B&Q outside the normal flow, our attempt to ship it is rejected and handled as a status-sync case, but support should expect to see this, not treat it as a bug.
• Carrier fallback logic still had open questions at time of writing about when to use "Other" versus flag an error — treat unmapped-carrier issues as an area to verify against current behaviour.
• EAN is mandatory — a product without an EAN (at either the B&Q-specific or general product level) cannot be listed at all.
• Discount pricing is entirely RRP-driven — if RRP isn't set or kept in sync with price, discounts won't appear even when intended.
• Variant attribute conflicts resolve silently — if the same attribute is set both generally and per-variant, the variant-specific value wins without a warning.
• Warning-level import results are treated as success, following standard Mirakl convention — this was still unconfirmed specifically for B&Q at the time of writing.
• VAT-per-country, eco-tax/EPR fields and multiple free-shipping thresholds are not covered in the B&Q source material, unlike some of Pentagon Connect's other Mirakl integrations — treat as undocumented rather than confirmed unsupported.

Source Materials

This guide was built from Pentagon Connect's internal B&Q integration specifications covering taxonomy, product and offer creation, order retrieval and acceptance, shipping, and refunds/cancellations, together with B&Q's own Mirakl marketplace seller documentation.