Best Buy US Integration – Feature & Process Guide

Best Buy US is one of the Mirakl-based marketplaces connected to Pentagon Connect. On Mirakl, a product (the catalog entry — title, images, attributes, category) and an offer (price, stock, condition and shipping class) are separate objects, and an offer can only go live once its underlying product already exists on Best Buy.

Most of how the integration behaves follows the standard Mirakl seller platform rather than anything Best Buy–specific, with a small number of Best Buy rules layered on top — a limited set of accepted product conditions, a fixed set of shipping/logistic classes, and Best Buy's own live carrier and refund-reason lists.

Quick Reference

Product Management

Pricing & Stock

Orders & Fulfilment

Refunds, Returns, Cancellations & Claims

Product Management

Creating products

New products are sent to Best Buy as a catalog entry first; an offer (price, stock, condition) is created against it once the product exists. Both steps run automatically once a product is ready – there's no manual per-product action needed from the seller.

• Required content: category, SKU, title and description, brand, a barcode/identifier (resolved from whichever of a marketplace-specific code, EAN or GTIN is available, in that priority order), and a main image.
• Additional images: supported alongside the main image.
• Category-specific attributes: every product is checked against the attribute requirements of its specific Best Buy category before it's sent. A product missing a category-required attribute is the most common reason a product fails to reach Best Buy. Some attributes accept multiple values at once (sent as a single combined value rather than one per option).
• Logistic/shipping class: each offer is assigned a Best Buy shipping class – either "Small" or "Large", or one of eight generic size/weight-based tiers we can map our own products onto.
• Variants: products can be grouped into variant sets (e.g. size/colour of the same item) by setting a shared variation group. Products without a variation group are created as standalone items; once a variation group is set, variant-specific attributes take priority over the shared ones, and a variation group with no variant-specific attributes at all is treated as an error. Each variant is still its own product record – siblings don't need to be submitted together, and a product can be pulled back out of a variation later.
• Condition: only "New" and "Refurbished – Excellent" are accepted; no other condition grades are supported.

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 likewise run independently, and are also how a previously deactivated offer is brought back – sending a positive stock level reactivates it, there's no separate "activate" action.
• Full updates (content, images, attributes, price and stock together) run as a separate flow.
• Protect Price – when set on a product, price is left out of updates sent to Best Buy, so its live price never gets overwritten.
• Protect Quantity – when set, stock is left out of updates, so the quantity live on Best Buy isn't touched.
• Protect the whole item – when set, the product is skipped entirely for that update cycle.

Deactivating / removing products

Two distinct capabilities are available, and they behave differently:

• Force zero stock takes a single offer off sale (sets it inactive) without deleting the underlying product or catalog listing. It's reversed simply by sending a positive stock quantity again through a normal stock update.
• Delete listing removes the offer outright rather than just deactivating it.
• Marking a product "Closed" stops all further creation and updates to it on Best Buy – with one exception: the zero-stock/delete-listing action is still allowed through even when a product is Closed, so a closed product can still be pulled off sale.

Pricing & Stock Sync

• RRP-based discounting: if an RRP is set and it's higher than the current price, Best Buy automatically shows the item as discounted (RRP as the "was" price). If no discount dates are set, the discount window defaults to two years from today.
• Independent price and stock updates: price and stock can each be pushed on their own, without needing a full content update.
• Condition: pricing and stock apply per offer, and only "New" and "Refurbished – Excellent" condition offers are supported (see Product Management above).

Order Management

Getting orders

Orders are pulled from Best Buy automatically and continuously – the first run looks back 90 days, and every run after that keeps checking for anything new or changed since the last run. Existing orders already in Pentagon Connect have their status and details kept in sync as they progress. No manual import step is required.

Order status only ever moves forward through Pentagon Connect's own status stages (never backwards, and a cancelled order is always final). One status Best Buy sends can mean either "completed" or "cancelled" depending on what actually happened to the order's items, so Pentagon Connect checks the underlying line-level refund/cancellation detail to work out which one applies, both when an order first arrives in that state and if it transitions into it later.

Order information we store

For every order, Pentagon Connect stores:

• Marketplace order ID, order status, currency, created date, payment-taken date, delivery date
• Buyer ID and a marketplace-anonymised notification email address
• Billing address: name, phone number, company, country, state, street, city, postal code
• Shipping address: name, phone number, company, country, state, street, city, postal code
• Carrier, shipping cost, tracking number, shipped date
• Per line item: SKU, product title, item price, quantity, line status, shipping cost, category, tax amounts
• 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

Shipping orders

Once an order is accepted and ready, Pentagon Connect pushes the carrier and tracking details to Best Buy first, then marks the order shipped – always in that order, as a paired step in the same run.

• Carrier matching: the carrier on the order is matched against Best Buy'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 – Best Buy 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 Best Buy.
• If Best Buy already considers an order shipped (for example from an earlier attempt), Pentagon Connect treats that as a successful outcome and still records the shipping details, rather than surfacing it as an error.

Cancellations

Whether a cancellation can happen, and at what level, depends on whether the customer's payment has already been taken:

• Before payment is taken: only a full-order cancellation is possible – partial cancellation isn't allowed at this stage.
• After payment is taken: cancellation moves to the line level, so individual items can be cancelled.
• In the rare case where an order looks eligible for both a cancellation and a refund at the same time, Pentagon Connect defaults to treating it as a cancellation.

Refunds & returns

Refunds can be full or partial (by quantity or amount), and can cover products only, or products plus shipping charges. Returns are handled through the same refund flow, using their own set of return-specific reasons (see Return & Refund Reason Codes below). Each returned/refunded item is submitted to Best Buy individually, so one item's failure doesn't block the others in the same order. A default reason can be configured for refunds and for cancellations separately, so a request isn't blocked just because no specific reason was given.

Claims / incidents

Best Buy orders can carry an open "incident" flag. What Pentagon Connect should do when an order first arrives already in this state isn't fully defined in the current source material – see Known Limitations.

Carriers Supported

Carriers aren't a fixed list we maintain – they're whichever couriers Best Buy has registered on their side, which Pentagon Connect reads live from Best Buy. 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 and return reasons are downloaded live from Best Buy rather than being a fixed list we can quote in full here. They fall into two families:

• Cancellation-side reasons – e.g. out of stock, item returned damaged, cancelled by the customer prior to shipping – used when an order or order line is cancelled.
• Return-side reasons – e.g. defective item, customer no longer wants the item – used when a refund is issued for a returned item.

A default reason can be set for each family, so a refund or cancellation isn't blocked just because no specific reason was supplied.

Known Limitations

• No partial shipment – every order ships to Best Buy as one complete shipment.
• Only two condition grades are accepted – "New" and "Refurbished – Excellent".
• No dedicated "activate" action – reactivating a deactivated offer is done purely by sending it a positive stock quantity again.
• Non-debited order cancellations only support full-order cancellation, never partial, until payment has been taken.
• Open "incident" order status isn't fully defined – what should happen when an order first arrives already flagged this way is an open question in the source material.
• Carrier list and refund/return reason list are both dynamic, not fixed sets we can quote in advance – they depend on what Best Buy has registered/configured for the account at the time.
• Carrier mapping has to be maintained manually – there's no automatic refresh of Best Buy's carrier list into our mapping table.

Source Materials

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