Laredoute 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)
| Date | Version | Name | Applied changes |
|---|---|---|---|
| 07/03/2023 | v1.0 | Hristiyan | First Published |
| 19/04/2023 | v1.1 | Bogomil | Add validation for conditions tagged with v1.1 |
| 18/05/2023 | v1.2 | Bogomil | Eco contributions amendments |
| 30/05/2023 | v1.3 | Danail | VAT validations change and transformation |
| 15.10.2024 | v1.4 | Bogomil | Vat format |
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)
Create offer cron should pick products only with statuses:
Product status = Product created and Listing Status = Inactive and List/Update the whole item =Pending
When the offer is successfully sent for creation we will set:
Product status = Product created and Listing Status = Inactive and List/Update the whole item =Sent
When the offer is created, we set statuses:
Product status - Product Published and Listing Status - Active and List/Update the whole item =Not Needed
If there is an error during offer creation, we will set following statuses:
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
- POST OF01 - Import a file to add offers
API Call: /api/offers/imports
API Docs: https://laredoutestg-stg.mirakl.net/help/api-doc/seller/mmp.html#OF01
Example file:
<?xml version = '1.0' encoding = 'UTF-8' ?>
<import>
<offers>
<offer>
<sku>OFFRE_SKU_1</sku>
<product-id>PRODUIT_SKU_1</product-id>
<product-id-type>SHOP_SKU</product-id-type>
<description>Ceci est la description de mon incroyable offre !</description>
<internal-description>Ceci est la description interne de mon offre.</internal-description>
<price>1000</price>
<price-additional-info>Prix incluant les taxes</price-additional-info>
<quantity>1</quantity>
<min-quantity-alert>20</min-quantity-alert>
<state>11</state>
<available-start-date>2012-12-25</available-start-date>
<available-end-date>2013-05-17</available-end-date>
<logistic-class></logistic-class>
<discount-price>1</discount-price>
<discount-start-date>2012-12-25</discount-start-date>
<discount-end-date>2013-12-25</discount-end-date>
<leadtime-to-ship>15</leadtime-to-ship>
<update-delete>UPDATE</update-delete>
<eco-contributions>
<eco-contribution>
<producer-id>Identifiant1</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<producer-id>Identifiant2</producer-id>
<eco-contribution-amount>3.49</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-ASL</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-DDS</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-DEA</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-DEEE</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-DIY</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-EMBM</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-JOUETS</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-PA</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-PAP</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-PNEU</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-TLC</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
<eco-contribution>
<epr-category-code>FR-VEHICULE</epr-category-code>
<producer-id>IDmetteur_marché_1234</producer-id>
<eco-contribution-amount>0.99</eco-contribution-amount>
</eco-contribution>
</eco-contributions>
<offer-additional-fields>
<offer-additional-field>
<code>ecopart</code>
<value></value>
</offer-additional-field>
<offer-additional-field>
<code>vat</code>
<value>20</value>
</offer-additional-field>
<offer-additional-field>
<code>rcp</code>
<value></value>
</offer-additional-field>
</offer-additional-fields>
</offer>
</offers>
</import>
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 UPPERCASE |
| description | | | Offer description - Recommended - Maximum 2000 characters | No | Product Account > Description | |
| 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 | Product Account Laredoute > Price Additional Info | |
| 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 | |
| eco-contributions | | | | | | |
| | eco-contribution | | | | | |
| | | producer-id | | No | Product Account Laredoute > Eco Producer Id | (v1.2)If empty we do not want to include it in the payload |
| | | eco-contribution-amount | | No | Product Account Laredoute > Eco Contribution Amount | (v1.2)If empty we do not want to include it in the payload |
| state | | | The state code of the offer
The accepted values are defined from the Mirakl back office | Yes | Product > Condition | Mapping to our conditions:
11- New > 1000;
(v1.1)We need to include additional validation which return internal error if we select condition different from New
“[INTERNAL]The item condition is incorrect. The only item condition allowed is New(with tags)!” |
| available-start-date | | | The first day the offer becomes available. The offer has no start date if blank.
yyyy-MM-dd
or
yyyy-MM-ddThh:mm:ss+00
| No | N/A | |
| available-end-date | | | The last day the offer is available. The offer has no end date if blank.
yyyy-MM-dd
or
yyyy-MM-ddThh:mm:ss+00
| No | N/A | |
| logistic-class | | | | No | Product Account Laredoute > Logistic Class
OR
Account Laredoute >
Logistic Class | Product Account Laredoute > Logistic Class is with priority |
| 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 Laredoute > 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+01If RRP <= Price We include the discount fields with empty values | |discount-end-date| | | | No | Product Account Laredoute > 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+01If RRP <= Price We include the discount fields with empty values | |leadtime-to-ship| | | | | Product Account > Dispatch Time Max OR Shipping Template >Dispatch Time Max | Product Account > Dispatch Time Max is with priority.
If we Product Account > Shipping Template we get the Dispatch Time Max from the Shipping Template
If we do nota have set Product Account > Shipping Template and we have Default Shipping Template set we get the Dispatch Time Max from the default Shipping Template
else we do not push anything. |
| update-delete | | | Used only in "Normal" import mode. Update mode is used if blank.
"", "update", "delete" | No | N/A | |
| offer-additional-fields | | | | | | |
| | offer-additional-field | | | | | |
| | | code | vat | Yes | “vat“ | Hardcoded as “vat“ |
| | | value | | Yes | Product Account > VAT
OR
Account > VAT | Product Account > VAT is with priority
Available values: 20, 10, 5.5, 2.1
We need to make sure we are using only VAT% of the possible values
<v1.4>
Vat should be with dot instead of comma.
</v1.4>
|
| | offer-additional-field | | | | | |
| | | code | rcp | No | | Hardcoded as “rcp“ |
| | | value | | No | Product Account Laredoute > RCP | |
| | offer-additional-field | | | | | |
| | | code | ecotax | No | | Hardcoded as “ecotax“ |
| | | value | | No | Product Account Laredoute > Eco Tax | |
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://laredoutestg-stg.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 "has_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 "has_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://laredoutestg-stg.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