BestBuy Create Offer

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

Version	Date	Name	Applied changes
v1.0	29.05.2025	Bogomil	First publish

The purpose of this page is to describe in details the process of creating offer to already existing product on MIRAKL.

To create offer we should use following API calls - POST OF01 (Import a file to add offers), GET OF02 (Get information and statistics about an offer import), GET OF03 (Get the error report file for an offer import)

Please note that in order to pick the product for offer creation we will need to have Channel Item Id and all relevant internal flags (described in additional information)

All other triggers, validations etc are per the listing abstraction Product Listing general requirements

POST OF01 - Import a file to add offers

API Call: /api/offers/imports

API Docs: https://help.mirakl.net/help/api-doc/seller/mmp.html#OF01

Example file:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<body>
    <active>true</active>
    <all_prices>
        <pricing>
            <channel_code xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
            <discount_end_date>2025-06-17T06:59:59Z</discount_end_date>
            <discount_start_date>2025-06-06T07:00:00Z</discount_start_date>
            <price>839.99</price>
            <unit_discount_price>839.99</unit_discount_price>
            <unit_origin_price>1124.99</unit_origin_price>
            <volume_prices>
                <volume_price>
                    <price>839.99</price>
                    <quantity_threshold>1</quantity_threshold>
                    <unit_discount_price>839.99</unit_discount_price>
                    <unit_origin_price>1124.99</unit_origin_price>
                </volume_price>
            </volume_prices>
        </pricing>
    </all_prices>
    <allow_quote_requests>false</allow_quote_requests>
    <applicable_pricing>
        <channel_code xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
        <discount_end_date>2025-06-17T06:59:59Z</discount_end_date>
        <discount_start_date>2025-06-06T07:00:00Z</discount_start_date>
        <price>839.99</price>
        <unit_discount_price>839.99</unit_discount_price>
        <unit_origin_price>1124.99</unit_origin_price>
        <volume_prices>
            <volume_price>
                <price>839.99</price>
                <quantity_threshold>1</quantity_threshold>
                <unit_discount_price>839.99</unit_discount_price>
                <unit_origin_price>1124.99</unit_origin_price>
            </volume_price>
        </volume_prices>
    </applicable_pricing>
    <currency_iso_code>CAD</currency_iso_code>
    <description xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
    <leadtime_to_ship>4</leadtime_to_ship>
    <min_shipping_price_additional>40.00</min_shipping_price_additional>
    <min_shipping_price>89.00</min_shipping_price>
    <min_shipping_type>M</min_shipping_type>
    <min_shipping_zone>BCLocal</min_shipping_zone>
    <msrp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
    <price>839.99</price>
    <price_additional_info xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
    <shipping_deadline>2025-06-20T06:59:59.999Z</shipping_deadline>
    <state_code>11</state_code>
    <total_price>928.99</total_price>
    <category_code>CAT_1003</category_code>
    <category_label>Desktop Computers</category_label>
    <fulfillment>
        <center>
            <code>DEFAULT</code>
        </center>
    </fulfillment>
    <product_brand>ViprTech</product_brand>
    <product_description>Crush demanding workloads and games with the Avalanche 2.0 AMD-powered desktop. Outfitted with the AMD Ryzen 7 2700 8-core processor, 32GB of DDR4 RAM, and a 1TB NVMe SSD, this system handles multitasking, streaming, and gaming with ease. The AMD Radeon RX 580 8GB graphics card delivers vibrant visuals and reliable 1080p performance. Backed by a 700W power supply and Windows 11 Pro, the Avalanche 2.0 is built to perform right out of the box.</product_description>
    <product_references>
        <product_reference>
            <reference>364061875862</reference>
            <reference_type>UPC-A</reference_type>
        </product_reference>
    </product_references>
    <product_sku>17540074</product_sku>
    <product_title>ViprTech Avalanche 2.0 Gaming PC - AMD Ryzen 7 (4.1Ghz Turbo), AMD RX 580 8GB, 32GB DDR4 3200, 1TB NVMe SSD, 700w PSU, VR-Ready, RGB, WiFi, Prebuilt Computer Desktop White</product_title>
    <channels>
        <channel_code>INIT</channel_code>
    </channels>
    <discount>
        <discount_price>839.99</discount_price>
        <end_date>2025-06-17T06:59:59Z</end_date>
        <origin_price>1124.99</origin_price>
        <ranges>
            <range>
                <price>839.99</price>
                <quantity_threshold>1</quantity_threshold>
            </range>
        </ranges>
        <start_date>2025-06-06T07:00:00Z</start_date>
    </discount>
    <logistic_class>
        <code>MED</code>
        <label>Medium Box (3.0 - 15.0kg/6.6 to 33.0Lbs)</label>
    </logistic_class>
    <offer_additional_fields>
        <offer_additional_field>
            <code>manufacturer-warranty</code>
            <type>REGEX</type>
            <value>365</value>
        </offer_additional_field>
    </offer_additional_fields>
    <offer_id>123226997</offer_id>
    <quantity>73</quantity>
    <shop_sku>S517956</shop_sku>
</body>

Mapping:

Mirakl Field					Mirakl Notes	Required	Hemi Field	Hemi Note
`sku`					The offer’s unique identifier in the shop - Required - Maximum 40 characters, no "/" character	Yes	Product >SKU
`product-id`					Unique product identifier for a given product-id-type - Required at offer creation - Maximum 40 characters	Yes	Product Account > Marketplace EAN

OR Product >EAN	Product Account > Marketplace EAN is with priority		`product-id-type`						Yes	hardcoded as “ean“	Must be lowercase
`internal-description`					The description of the offer as shown in the back office view - Optional - Maximum 2000 characters	No	N/A
`price`					The selling price in the currency.

It is up to the operator to define with the seller whether the selling price includes or excludes taxes. Decimal number; a period is used to separate cents | Yes | Product Account > Start Price OR Product Account> RRP | we send Product Account > RRP If RRP is populated and is bigger than Price | | price-additional-info | | | | | Information regarding the price of the offer. Check with your operator if this information appears on the front. Character string limited to 100 characters | No | | | | quantity | | | | | The quantity available in stock (maximum: one billion). Integer greater than or equal to 0 | No | Product Account > Quantity | | | min-quantity-alert | | | | | | | N/A | | | state | | | | | The state code of the offer The accepted values are defined from the Mirakl back office | Required | Product > Condition | Only two conditions are supported in SecretSales Mapping to our conditions:

11- New > 1000; 10- Vintage> 1500; | | available-start-date | | | | | The first day the offer becomes available. The offer has no start date if blank.

yyyy-MM-dd or

yyyy-MM-dd or

yyyy-MM-ddThh:mm:ss+00 | No | N/A | | | discount-price | | | | | | No | Product Account > Price | If RRP > Price

If there are discount dates imported in Hemi we use them

If there are no dates imported in Hemi we use the default dates (Now) and (Now + 2y) If RRP <= Price 3.We include the discount fields with empty values		`discount-start-date`						No	Product Account BestBuy > Discount Start Date	If RRP > Price and If we do not specify any dates in the relevant fields we hardcoded current date (“NOW“) Date format - `2017-02-20T10:45:53+01` If RRP <= Price We include the discount fields with empty values		`discount-end-date`						No	Product Account BestBuy > Discount End Date	If RRP > Price and If we do not specify any dates in the relevant fields we hardcode current date + 2 year (“NOW“ +2y) Date format - `2017-02-20T10:45:53+01` If RRP <= Price We include the discount fields with empty values		`update-delete`					Used only in "Normal" import mode. Update mode is used if blank. "", "update", "delete"	No	N/A			all_prices											pricing											channel_code										discount_end_date										discount_start_date										price										unit_discount_price										unit_origin_price										volume_prices											volume_price											price										quantity_threshold										unit_discount_price										unit_origin_price						allow_quote_requests										applicable_pricing											channel_code										discount_end_date										discount_start_date										price										unit_discount_price										unit_origin_price										volume_prices											volume_price											price										quantity_threshold										unit_discount_price										unit_origin_price							currency_iso_code										`description`					Offer description - Recommended - Maximum 2000 characters	No	Product Account > Description			leadtime_to_ship										min_shipping_price_additional										min_shipping_price										min_shipping_type										min_shipping_zone										msrp										price										price_additional_info										shipping_deadline										state_code										total_price										category_code										category_label										fulfillment

Example Response:

<offer_import_tracking>
    <import_id>2035</import_id>
    <product_import_id>2036</product_import_id>
</offer_import_tracking>

After each successfully send feed for creation we will receive the feed id from the response and need to store it in Marketplace Feeds table.

Mirakl Field	Hemi Field	Comment
import_id	Marketplace Feed > External ID
	Marketplace Feed > Account	For which account is the feed generated.
	Marketplace Feed > Type	Hardcoded as “Offer Create“
	Marketplace Feed > Submitted Date	When the feed is submitted
	Marketplace Feed > Sent Objects Count	How many products we have pushed in the feed

Please note we will also add the feed objects which after processing need to be removed.

GET OF02 - Get information and statistics about an offer import

API Call: /api/offers/imports/{import}

API Docs: https://help.mirakl.net/help/api-doc/seller/mmp.html#OF02

Parameter	Integration Notes / Value	Required
`import`	Import identifier	Yes

Using this call, we are able to check the status of the imported file.

Example Response:

{
  "date_created": "2019-04-01T15:16:31Z",
  "has_error_report": false,
  "import_id": 2035,
  "lines_in_error": 0,
  "lines_in_pending": 0,
  "lines_in_success": 1,
  "lines_read": 1,
  "mode": "NORMAL",
  "offer_deleted": 0,
  "offer_inserted": 1,
  "offer_updated": 0,
  "status": "COMPLETE"
}

OF02 call is returning the response for the actual offer import (all offers).

Based on the response, we will need to check if we have to continue with the error report (if "error_report": true ) we continue with OF03, otherwise we treat it as success.

Success case (once the offer is created successfully)

Product status = Product Published and Listing Status = Active/Inactive and List/Update the whole item =Not Needed

Error case: If "error_report": true this means there is an error and we need to reach each of the reports in order to check for which item and what is the error.

Product status = Product created and Listing Status = Inactive and List/Update the whole item =Error

and we need to store the relevant error in Update Item Error field

GET OF03 - Get the error report file for an offer import

In order to check if there are any errors related to the products, into imported file we should use the GET OF03 API Call.

API Call: /api/offers/imports/{import}/error_report

API Docs: https://help.mirakl.net/help/api-doc/seller/mmp.html#OF03

"sku";"product-id";"product-id-type";"description";"internal-description";"price-additional-info";"quantity";"min-quantity-alert";"state";"available-start-date";"available-end-date";"logistic-class";"update-delete";"discount-start-date";"discount-end-date";"price";"discount-price";"discount-ranges";"price-ranges";"discount-start-date[channel=FR]";"discount-end-date[channel=FR]";"price[channel=FR]";"discount-price[channel=FR]";"discount-ranges[channel=FR]";"prices-ranges[channel=FR]";"discount-start-date[channel=CA]";"discount-end-date[channel=CA]";"price[channel=CA]";"discount-price[channel=CA]";"discount-ranges[channel=CA]";"prices-ranges[channel=CA]";"leadtime-to-ship";"error-line";"error-message"
"OFFER_SKU_004";"MKP100000000195360";"SKU";"My Offer Description n°1";"My Internal description 1";"My price Additional innformations";"1000000";"20";"11";"2017-02-20T10:45:53+01";"2017-04-30T10:45:53+01";"S";"update";"2017-02-22T10:45:53+01";"2017-04-30T10:45:53+01";"110.52";"108,56";"";"5|109.20,10|108.736";"2017-02-22T10:45:53+01";"2017-03-31T10:45:53+01";"105.56";"102,36";"";"5|104.56,10|103.27";"2017-02-22T10:45:53+01";"2017-03-31T10:45:53+01";"190.23";"175,36";"";"5|182.58,10|181.27";"15";"2";"The product does not exist"

As described above, this response give us detailed report of the SKUs and the actual SKUs errors are in the “error-message“ which we store in the Product Account >Update Item Error

Additional Information:

For this integration we will need to make sure the protect flags are working as expected:

Closed -will stop all the updates to the MPs

Marketplaces / BestBuy Technical Scope / BestBuy Product & Offer management / BestBuy Create Offer

BestBuy Create Offer