Tesco Integration – Feature & Process Guide

Tesco Marketplace is one of the Mirakl-based marketplaces connected to Pentagon Connect. It is a standard Mirakl Seller API implementation, with a handful of Tesco-specific rules layered on top — Clubcard pricing, a defined logistic-class/shipping-size system, and its own registered carrier list.

This page describes what the Tesco integration supports — which product, pricing, order and refund/cancellation 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 Tesco as products first, then offers (price/stock/availability) second — an offer can't go live until its product exists in Tesco's catalogue. Both steps run automatically once a product is ready; there's no manual per-product action needed from the seller.

• Key fields: SKU, description, marketing text, brand, unit quantity, country of origin, age restriction, colour, barcode, VAT rate, up to 10 images, dimensions/weight, shipping dimensions, packaging and safety-warning information.
• Category-specific attributes: every product is checked against Tesco's category attribute requirements (downloaded from Tesco's taxonomy) before it's sent — a product missing a category-required attribute is the most common reason a product fails to reach Tesco.
• Channel Item ID: once a product is created, its Channel Item ID is set to its EAN/barcode.
• Variants: a product is only treated as part of a variant set when it's assigned to a shared Variation Group. Each variant is still created as its own product record, so sibling variants don't need to be submitted together — only the ones actually changing. Removing the group reference takes a product out of the variation group. A variation group with no variant-level attributes at all is treated as an error.
• Pausing before creation: marking a product “Closed” stops it from being created at all.

Updating products

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

• Price-only updates run as their own lightweight flow, for cases where only the price needs refreshing.
• Stock-only updates run as their own lightweight flow, used both while a product is active and to push stock back up after it's been deactivated.
• Full updates (content, images, attributes, price and stock together) run as a separate flow, and are only picked up once a product is already live on Tesco.
• Protect Price — when set, price is left out of every update sent to Tesco, so the price live on the marketplace is never overwritten.
• Protect Quantity — when set, stock is left out of updates (a dedicated stock update is skipped entirely).
• Protect the whole item — when set, the product is skipped entirely for a full content update (its stock can still update independently).
• Clubcard pricing — when enabled on a listing, an additional Clubcard price/RRP/discount block is sent alongside the standard price; when disabled, that block is left out entirely.

Deactivating / removing products

There are two distinct ways to take a Tesco listing off sale:

• Zero-stock / deactivation — pushes the item's stock to zero and marks it inactive on Tesco, without removing it from the catalogue. This keeps working even when the account is otherwise marked “Closed.”
• Offer delete — a dedicated flow that removes the offer from Tesco's marketplace entirely, distinct from a zero-stock update.

Marking a product “Closed” stops all other updates (creation, full update, price, stock) but not the two actions above, so listings can still be pulled from sale even while an account is administratively closed.

Pricing & Stock Sync

• RRP-based discounting: if an RRP is set and it's higher than the current price, Tesco automatically shows the item as discounted. If no discount dates are set, the window defaults to two years from today.
• Clubcard pricing: a Tesco-specific price tier for Clubcard members, sent only when explicitly enabled on the listing; it sits alongside, not instead of, the standard price update.
• Condition: only “New” condition items are accepted by Tesco.
• Logistic classes: every offer carries a logistic class — either “Small” (1-man delivery) or “Large” (2-man delivery), or one of eight custom “Supplier Logistic Class” slots that can be mapped to specific size/weight tiers. This is what Tesco uses to cost and handle delivery for that item, alongside a per-listing lead time to ship.
• Feed splitting: price-protected and non-price-protected products can't be sent in the same update batch — Hemi automatically splits full-update feeds in two so a protected price is never accidentally overwritten. See Known Limitations.

Order Management

Getting orders

Orders are pulled from Tesco automatically on a recurring schedule — new orders are picked up, and orders already stored in Pentagon Connect have their status and shipping/tracking info kept in sync as they progress. No manual import step is required. The very first run looks back 90 days of order history.

Order information we store

For every order, Pentagon Connect stores:

• Marketplace order ID, order status, currency, created date, last-updated date, expected delivery window (earliest/latest), and the ship-by deadline
• Buyer name, buyer ID, and a marketplace-anonymised notification email address
• 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
• Carrier, tracking number, tracking URL, shipped date
• Per line item: SKU, product title, category, item price, quantity, line status, shipping cost
• 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 customer message, and whether it's been fully refunded

Order status is tracked in Pentagon Connect following Tesco's own status flow (from awaiting acceptance, through ready-for-shipping and shipped, to cancelled). Tesco's terminal “Closed” status doesn't say whether an order shipped or was cancelled, so Pentagon Connect resolves it by checking whether all order lines ended up refunded.

Shipping orders

Once an order is accepted and its information is complete, Pentagon Connect sends the carrier and tracking details to Tesco and marks the order shipped in a closely-linked pair of automated steps.

• Carrier matching: the carrier on the order is matched against Tesco'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 — Tesco 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 Tesco.
• If Tesco already shows an order as shipped by the time Pentagon Connect tries to confirm it, that's treated as a success rather than an error — the order is marked shipped and its shipping info populated anyway.

Cancellations

Whether an order can be cancelled, and which flow applies, depends on whether the customer has already been debited:

• Before debit: only a full-order cancellation is possible; a partial cancellation can't be requested until the order has been debited.
• After debit: cancellation happens per order line, each with its own reason code and amount.

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

Refunds & returns

Refunds can be full or partial (by quantity or amount), and can cover products only, or products plus shipping charges. Tesco doesn't have a separate “return” object — a customer return is handled as a refund using a “returned”/“not received”-style reason code. Each refunded order line is submitted to Tesco as its own request, so one failing line doesn't block the rest of a multi-line refund — a multi-line refund can end up partially completed, with some lines refunded and others left in an error state for support to retry.

Carriers Supported

Carriers aren't a fixed list we maintain — they're whichever couriers Tesco has registered on their side, which Pentagon Connect reads live from Tesco. Couriers seen on this account include DPD, DHL, Evri (Hermes), UPS, Royal Mail, Yodel, ParcelForce, Tuffnells, Whistl, XDP and ArrowXL, plus an explicit untracked option for deliveries with no tracking number. 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 (as registered on Tesco's Mirakl account):

• No response from the shop
• Out of stock
• Cancelled by the client prior to shipping
• Item returned
• Item not received
• Agreement found with the vendor
• Cancelled before fulfilment
• Cancelled by customer
• Refunded through EDI integration (system-generated)

Cancellation reasons:

• Cancelled by the client prior to shipping
• Cancelled due to late shipment (system-generated)
• Debit failed (system-generated)
• Debit timed out (system-generated)
• Cancelled through EDI integration (system-generated)
• Cancelled due to a failed fraud check (system-generated)
• Cancelled due to a fraud-check timeout (system-generated)
• Default reason, used only when none is given (system-generated)

Known Limitations

• No partial shipment — every order ships to Tesco as one complete shipment.
• No line-level order acknowledgement — Tesco only supports accept/reject at the whole-product level; a mixed accept/reject across the same product's lines is rejected before it's even sent.
• Only “New” condition is accepted for offers.
• Only full cancellation before debit — partial cancellation isn't possible until an order has been debited, at which point per-line cancellation applies instead.
• Price-protected and non-protected products must travel in separate feeds — Tesco/Mirakl rejects a feed that mixes the two.
• Closed accounts still push zero-stock and offer-delete — the “Closed” flag stops nearly everything else, but listings can still be pulled off sale while an account is administratively closed.
• A “Closed” terminal order status on Tesco's side is ambiguous — Pentagon Connect has to infer shipped vs. cancelled by checking whether all order lines were refunded.
• Clubcard pricing only applies when explicitly enabled per listing; it isn't part of the standard price update.
• No documented click & collect / pick-up point delivery flow.
• Order polling and updates are subject to Mirakl rate limits (e.g. order status checks are capped at once per minute), so a delayed order sync is more likely a rate-limit backoff than a fault.

Source Materials

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