Channel Integrations Through Mirakl

 
 

Overview

Mirakl is a marketplace platform software that helps website retailers partner with third-party sellers to grow their online offerings and expand their market reach. Sellercloud lets you connect with various selling channels through Mirakl. You can automate your daily e-commerce operations and manage your inventory, orders, and shipping for these channels through Mirakl:

Click the links above for step-by-step instructions on integrating these channels. For a full list of integrations, see Mirakl’s Website.

These integrations work by transmitting information via API. The following plugins for Sellercloud are currently available:

  • Order Import – Imports orders from Mirakl channels to Sellercloud.
  • Tracking Export  – Exports tracking information to Mirakl channels.
  • Inventory Export – Updates inventory on Mirakl channels.
  • RMA Import – Imports RMAs to Sellercloud.

If necessary, you can contact Sellercloud Support to request additional customizations or other plugins for each integration. Note that these customizations are billable, and you will be provided a quote.


Prerequisites 

You integrate channels through Mirakl by following these steps:

  1. Contact Sellercloud Support and request:
    1. To install the Mirakl Plugins.
    2. To create Custom Product and Order Columns.
  2. Create a new Company for the integration.

    Sellercloud imports Mirakl orders under the Website channel. If you integrate multiple channels through a single company, you won’t be able to tell which channel your orders are coming from. Creating a company for each channel integration prevents this issue – you can search by Company instead of by Channel to see only orders from a specific channel.
  3. Create Custom Company Settings for authentication and to configure how the integration works.
  4. Enable the integration by preparing your products and then creating Scheduled Tasks. These tasks use Saved Searches to target specific orders or products and run the plugins on a regular basis.
You can sign up for Premium Support to get a dedicated Sellercloud Representative who will take you through the whole process and assist you every step of the way.

See the following sections for a detailed description of each step.

Contact Sellercloud Support

To get started, contact Sellercloud Support and request to install the Mirakl plugins on your server.

In addition, ask to add the following Custom Product and Order Columns:

Custom Product Columns

  • CHANNEL_Enabled – Optional setting. Type Boolean. Replace CHANNEL with the channel you are integrating through Mirakl. Use this setting if you only want to enable specific products for the integrated channel – set to True to enable a product.
  • MIRAKL_SKU – Type String. If a product’s SKU on Mirakl is not the same as the Sellercloud SKU, you must use this setting to enter the product’s Mirakl SKU, or else the Inventory Export will fail.
  • MIRAKL_PRICE – Type Decimal. The product’s price on Mirakl.
  • MIRAKL_AVAILABLE_STARTED – Type DateTime. This is the start date of the listing.
  • MIRAKL_AVAILABLE_ENDED – Type DateTime. This is the end date of the listing.

    MIRAKL_AVAILABLE_STARTED and MIRAKL_AVAILABLE_ENDED can be set to past dates as long as the start date is before the end date. Otherwise, Mirakl will reject the inventory and price update of the product.
  • MIRAKL_SHOP_IDS – Type String. Used only if the company setting Mirakl_Shop_IDs isn’t empty. Contains the ID of the Mirakl shop with the product.
  • MIRAKL_DISCOUNT_PRICE – Type Decimal. Optional setting. Sets a discounted price for a product on Mirakl.
  • MIRAKL_DISCOUNT_AVAILABLE_STARTED – Type DateTime. Optional setting. Sets the product discount’s start date.
  • MIRAKL_DISCOUNT_AVAILABLE_ENDED – Type DateTime. Optional setting. Sets the product discount’s end date.
  • MIRAKL_SAFETY_QTY – Type Integer. A Safety Quantity for products on the integrated channel.
  • MIRAKL_MANUFACTURER_WARRANTY – Type Integer. Used to set a product’s manufacturer warranty.
  • MIRAKL_MANUFACTURER_WARRANTY_USE_DEFAULT – Type Boolean, defaults to False. If you set it to False, your products’ warranty will come from the product custom column MIRAKL_MANUFACTURER_WARRANTY. If you set it to True, the warranty will come from the custom company setting Mirakl_Manufacturer_Warranty.
  • MIRAKL_LOGISTIC_CLASS – Type String with an optional selected value. If in use, adds a drop-down where a single value can be selected. See the links in the Overview for more information about the values for each channel.
  • MIRAKL_DESCRIPTION – Type String. Sets the product’s description on Mirakl. If you don’t use this setting, the product’s name in Sellercloud will be sent as the description.
  • MIRAKL_INTERNAL_DESCRIPTION – Type String. Sends an internal description of the product.
  • MIRAKL_PRICE_ADDITIONAL_INFO – Type String. Sends additional information about the price.
  • MIRAKL_OFFER_STATE – Type String, a dropdown menu that indicates the product’s condition. The default will be 11 (NEW) if this setting is missing or there’s an invalid Mirakl_Integration_Name. The following integrations default to 1: Weight Watchers, Bed Bath and Beyond, Hudson’s Bay, UNFI, Snappy, Ahold Delhaize, Peapod Digital Labs, and Belk.
    • Hudson’s Bay US state codes: 1 (New), 8 (Pre-Loved), 10 (Refurbished), 11 (Vintage) – find attached
    • Belk state codes: 1 (New), 10 (Refurbished)
    • Shop Premium Outlets state codes: 11 (New), 1 (Preowned – Pristine), 2 (Preowned – Very Good), 3 (Preowned – Good), 4 (Preowned – Fair), 10 (Refurbished),
    • Giant Eagle state codes: 11 (New), 1 (Used – Like New), 2 (Used – Very Good Condition), 3 (Used – Good Condition), 4 (Used – Acceptable Condition), 5 (Collectors – Like New), 6 (Collectors – Very Good Condition), 7 (Collectors – Good Condition), 8 (Collectors – Acceptable Condition), 10 (Refurbished)
    • Darty.com state codes: 11 (New), 1 (Used – Very Good Condition), 2 (Used – Perfect Condition), 3 (Used – Correct Condition), 10 (Used – Good Condition)
  • MIRAKL_EXPORT_OFFER_STATE_NEW – Type Boolean. Defaults to False. This setting is required and used only when the company setting MiraklEnableExportOfferStateNew is enabled. Then the plugin will export the default offer state code (NEW) instead of the selected MIRAKL_OFFER_STATE.
  • MiraklMaxQtyEnabled – Type Boolean. Set to True to enable the MiraklMaxQty setting below.
  • MiraklMaxQty – Type Integer, used if MiraklMaxQtyEnabled is set to True. Sets the product’s maximum product quantity on the channel.
  • MiraklMaxQtyUseDefault – Type Boolean, set to True to use the maximum quantity set on the Company Level instead of the product-level setting above.
  • MIRAKL_OFFER_TAXCODE – Type String. Stores the tax code associated with a Mirakl offer. This setting overrides the company-level custom setting Mirakl_Offer_TaxCode, which sets a default tax code value. If this setting is missing, the default will be used.
  • MiraklReplenishableQtyToSend – Type Integer. Sends a replenishable quantity. The product must be configured as Replenishable.
  • MiraklUseDefaultReplenishableQty – Type Boolean. Set to True to use the default replenishable quantity set on the company level with the MiraklDefaultReplenishableQty setting instead of the product-level quantity set in the MiraklReplenishableQtyToSend product custom column.
  • Mirakl_MinQtyAlert – Type Integer. Optional setting. Defaults to 1. Sets a minimum quantity for the product. Mirakl will send you an alert when this quantity is reached.

Custom Order Columns

  • MIRAKL_CHANNEL – Type String. The Order Import plugin uses this column to save the name of the order’s channel.
  • MIRAKL_SHOP_ID – Type Integer. The Order Import plugin populates the Mirakl shop ID from which the order has been imported if the custom company setting Mirakl_Shop_IDs is not empty or missing.

Create and Configure a Company 

As mentioned above, Mirakl orders are imported under the Website channel. If you integrate multiple channels through a single company, you won’t be able to tell which channel your orders are coming from. 

Creating a company for each channel integration prevents this issue, as you can search by Company instead of by Channel to see only orders from a specific channel. This is why it’s best to create a new Company for the Custom Company Settings and Scheduled Tasks.

Next, create the following Custom Company Settings on the company you created for your integration:

  • Mirakl_Integration_Name – This setting’s value will be added to the custom order column MIRAKL_CHANNEL to show each order’s source channel. The following values are acceptable: BestBuy.Ca, BestBuyCa, BestBuy Canada, Catch, Catch.com, Express, Express.com, BlueFly, WW, Weight Watchers, Kroger, HudsonsBayUS, Knott, Knot, The Knot, The Knott, OrientalTrading US, Verishop US, Belk, BedBathAndBeyond, BedBathAndBeyond US, Ahold, Peapoddigital, Snappy, Carrefour, Carrefour.es, ShopPremiumOutlets, SPO, GiantEagle, Madewell, UrbanOutfitters, Kohls, Kohl’s, Saks, Macys, Macys US, Maisonette (not case sensitive), 1800flowers, Darty.com, MathisBrothersUS, SalonCentric, NBCUniversal, Reitman, Tiendamia, Liverpool, and General Electric. 
  • Mirakl_API_URL – Enter the API URL of the channel you are integrating through Mirakl. Check with Mirakl’s support team for the value of the setting.
  • Mirakl_API_Key – Your Mirakl authentication key. On Mirakl, you can find it by clicking your email address in the top right corner and selecting API Key.
  • MiraklOAuthTokenId – Used as an alternative to Mirakl_API_Key. Don’t assign it any value, and you will automatically get a token from the scheduled tasks.
  • Mirakl_Always_Accept_Orders – Optional setting. Can be set to True or False. Determines if orders with pending acceptance will be accepted even if there’s not enough inventory on hand to fulfill them. If this setting is missing, the plugin will not accept such orders.
  • Mirakl_Get_Only_Recent_Orders – Set to True for the Order Import plugin to get only orders modified in the past 10 days. Don’t create the setting or set it to False for the initial order import. Then, set it to True to speed up the plugin and avoid reaching API limits.
  • Mirakl_Shop_IDs Type String. Enter a comma-separated list of Mirakl shop IDs. The Order Import plugin will only import orders from the Mirakl shops you list here. If this setting is missing, the plugin will only import orders from the first shop associated with your Mirakl user account.
  • Mirakl_Order_Statuses – Optional setting. Only orders with the order statuses listed here (comma-separated) will be imported. If you don’t create this setting, only orders with the status of WAITING_ACCEPTANCE, PAYMENT_COLLECTED, SHIPPING, SHIPPED, RECEIVED, and CLOSED will be imported.
  • Mirakl_Import_orders_with_source_BestBuy_instead_of_Website – Optional setting. Defaults to False. Determines if BestBuy orders will be imported under the Website or BestBuy channel.
  • Mirakl_Shipping_Method – Optional setting. Sets a specific shipping method for imported orders.
  • RunPostOrderPluginAfterOrderCreation – Optional setting. Defaults to False. Set it to True if you need to run a post-order plugin once Mirakl orders are created/updated.
  • Mirakl_Manufacturer_Warranty – Defaults to 0. Sets a default manufacturer warranty period for Mirakl products. Used when the MIRAKL_MANUFACTURER_WARRANTY_USE_DEFAULT custom product column is set to True.
  • Mirakl_Warehouse_IDs – A comma-separated list of warehouse IDs to export inventory from. Works with both the Basic and Advanced Safety Quantity workflows.
  • Mirakl_Enable_Advanced_Safety_Qty – Defaults to False. Enables the Advanced Safety Quantity workflow.
  • MIRAKL_UseAdvancedKitProjecting – Defaults to False. When set to True, Independent Kit Products get an estimated sellable quantity if there are no assembled items. All Component kits get items out of Independent kits when projecting.
  • Mirakl_Inventory_Percent – Used with the Advanced Safety Quantity workflow. Decimal value (80 means 80%), defaults to 100%. 
  • MiraklEnableExportOfferStateNew – Defaults to False. When set to True, this setting enables the use of the custom product column MIRAKL_EXPORT_OFFER_STATE_NEW. With this setting enabled, the Inventory Export plugin will export the default offer state code (NEW) instead of the selected MIRAKL_OFFER_STATE.
  • Mirakl_Offer_TaxCode – Optional String. Sets a default tax code for all products. If this setting doesn’t exist, you must set each product’s tax code individually using the MIRAKL_OFFER_TAXCODE setting. The tax code is a required field for Inventory Export updates to go through successfully.
  • MiraklDefaultReplenishableQty – This value is exported as the inventory for Replenishable Products if the MiraklUseDefaultReplenishableQty custom column is enabled on the product level.
  • Mirakl_ExcludeNonPayableToShopTaxes – Set to True to determine if the Order Import should include taxes facilitated by the marketplace or not.
  • Mirakl_DontRunPostOrderOnWaitingAcceptanceOrders – If you set this to True, Sellercloud will not run post-order actions on orders that were created with the WAITING_ACCEPTANCE status from Mirakl, have an empty shipping address, or the payment status is not Charged.
  • Mirakl_ProductIDType – This setting determines the product ID type sent by the Inventory Export. The value you enter will be the exact value that gets sent to Mirakl. If this setting doesn’t exist, SHOP_SKU will be sent as the value.

Integration Setup 

Now that the Mirakl plugins have been installed on your server, the custom product and order columns have been created, and you have created the custom company settings, you’re ready to move on to the final part of the setup – automating the integration.

The automation consists of three parts – preparing your products, creating saved searches, and creating scheduled tasks.

Prepare Products 

For the Inventory Export plugin to send product updates successfully, these required Custom Product Columns must be populated on each product:
  • SKU – If a product’s SKU on Mirakl is not the same as the Sellercloud SKU, you must use the MIRAKL_SKU custom product column to enter the product’s Mirakl SKU, or else the Inventory Export will fail.
  • Product ID – Comes from the MIRAKL_SKU custom product column unless the Mirakl_ProductIDType custom company setting specifies a different product ID type.
  • Product ID Type – Comes from the Mirakl_ProductIDType custom company setting.
  • Start and End Dates – The MIRAKL_AVAILABLE_STARTED date must be before the MIRAKL_AVAILABLE_ENDED date.
  • Price – Comes from the MIRAKL_PRICE custom product column. It may also be set by the MIRAKL_DISCOUNT_PRICE.
  • State – Comes from the default set in the Mirakl_Offer_TaxCode custom company setting or the MIRAKL_OFFER_TAXCODE custom product column.
  • Quantity – Comes from the product’s available quantity in Sellercloud. The Safety Quantity Workflow, the MIRAKL_SAFETY_QTY custom product column, and the MiraklMaxQty and MiraklMaxQtyUseDefault custom company settings affect the quantity.
  • Product Tax Code – Comes either from the default set in the Mirakl_Offer_TaxCode custom company setting or the MIRAKL_OFFER_TAXCODE custom product column.
If something is missing, the plugin will generate an error message in the Queued Job with more details, and the product with the issue will be skipped.

If you only want to enable specific products for the inventory export, you must enable these products now. You do this by updating the CHANNEL_Enabled (where CHANNEL is replaced with the channel you are integrating) custom product column’s value to True. You can do this per product or in bulk:

  • For one product at a time: Go to the Product Details Page > click Toolbox and select Custom Columns > click Edit > Update the CHANNEL_Enabled column >  click Save.
  • For multiple products in bulk: Follow the steps to Bulk Update Products and add the CHANNEL_Enabled column – set it to True for all products you want to enable.

Create Saved Searches 

The Saved Searches determine the orders and products targeted by the plugins when the scheduled tasks run. You must create one saved search for orders for the Tracking Export and one saved search for products for the Inventory Export.

For the Tracking Export, go to Orders > Manage Orders and filter by:

  • Company – Choose the integration company
  • Order Status – InProcess Or Completed
  • Shipping Status – FullyShipped
  • Payment Status – Charged
  • Tracking Uploaded – No

For the Inventory Export, go to Catalog > Manage Catalog and filter by:

  • CHANNEL_Enabled – True.
  • Active Status – Active
  • You can add more filters per your preference.

Create Scheduled Tasks 

Next, you need to create a Scheduled Task for each plugin:

For the Order Import plugin:

  • Set the Task Type to Import Orders.
  • Create Orders For Company – select the company you designated for this integration.
  • Set the Plugin to Mirakl Order Import.

For the Tracking Export plugin:

  • Set the Task Type to Export Orders
  • Set the User ID to the user you used to create the saved search for orders.
  • Set the Saved Search to the orders search you created for the Tracking Export.
  • Set the Export Via to Mirakl Order Tracking Export.
  • Check Mark Orders As Exported.
  • Check This Is Tracking Export.

For the Inventory Export plugin:

  • Set the Task Type to Export Products
  • Set the User ID to the user you used to create the saved search for products.
  • Set the Saved Search to the products search you created for the Inventory Export
  • Set the Export Via to Mirakl Inventory Export Plugin.

Do not update more than 60,000 products per hour, or you will reach the limit of 60 API calls per hour.

For the RMA Import plugin:

  • Set the Task Type to Import Orders.
  • Set the Plugin to Mirakl Order Import.

On all four scheduled tasks, do the following:

  • In the Export Options section, set Export To/Import From to None.
  • In the Frequency section, specify the task frequency. For optimal performance, select a range between thirty minutes and one hour.
  • In the General section, click the Enable toggle button on top.

Integration Details

See the following sections for details on how Mirakl integrations work.

Order Import

This plugin downloads orders through the API and imports them as Website orders in Sellercloud. Orders will be created with the email customer_id@integrationName.com. For example, 12345@catch.com, 67890@bestbuy.ca.

The plugin will send order acceptance to Mirakl if all your ordered items have enough inventory to fulfill the order. Orders will be set as canceled on Sellercloud and Mirakl if an item has insufficient inventory.

Note the following important details describing how the plugin interacts with orders with different statuses:

  • If the custom company setting Mirakl_Order_Statuses doesn’t exist, only orders with a Mirakl status WAITING_ACCEPTANCE, SHIPPING, PAYMENT_COLLECTED, SHIPPED, RECEIVED, and CLOSED will be imported. If this setting exists, then only orders with the statuses you list there will be imported.
  • Orders with the status SHIPPED, RECEIVED, and CLOSED will be imported as completed. 
  • Orders with the status SHIPPED and RECEIVED will be marked as fully shipped, while CLOSED ones will be marked as shipped only if they have a tracking number or a carrier name.
  • Orders with the status WAITING_ACCEPTANCE are downloaded with empty addresses. After acceptance, Mirakl sends them again with the status SHIPPING, and addresses are added to the relevant orders by the plugin.
  • After an order that’s pending acceptance is created in Sellercloud, the plugin will check the custom company setting Mirakl_Always_Accept_Orders. If True, the order will be automatically accepted. If False, an acceptance is sent to Mirakl only if there’s sufficient product inventory to fulfill the whole order. Otherwise, it will be rejected, and the Sellercloud status will be changed to Cancelled.
For each imported order, the ordered products must exist in Sellercloud with either the same SKU or with the Mirakl product ID in the MIRAKL_SKU custom column. Otherwise, order items will be Unknown, their inventory on hand will be considered 0, and the order will be refused on Mirakl.

Tracking Export

The Tracking Export plugin exports the shipping carrier and tracking number, then marks the order as shipped on Mirakl.

Tracking confirmation is saved to the order action documents as a TrackingUpload_PreShip. If it’s successful, the plugin will skip tracking updates for this order and will try sending a shipping confirmation.

Shipping confirmation is saved to the order action documents as a TrackingUpload. If it’s successful, the plugin will skip sending it again.

Inventory Export

The Inventory Export plugin exports the available inventory, price, and offer start and end date from Sellercloud to the channel:

  • The price is set in the custom column MIRAKL_PRICE.
  • The description is the product’s name in Sellercloud by default. If the MIRAKL_DESCRIPTION custom column exists, it is used to set the description.
  • The offer start and end dates are set in the custom columns MIRAKL_AVAILABLE_STARTED and MIRAKL_AVAILABLE_ENDED.

Products are matched by Mirakl SKU (either the Sellercloud SKU or the custom column Mirakl_SKU, matched to the Mirakl SKU under Settings, not the one in the summary on top). If the Mirakl SKU is missing, the Sellercloud SKU will be used.

Do not update more than 60,000 products per hour, or you will reach the limit of 60 API calls per hour.

There are two Safety Quantity workflows that function as follows:

  • The Basic Safety Qty workflow, when Mirakl_Enable_Advanced_Safety_Qty is missing or False.
    • Aggregate inventory from all sellable warehouses or from the specified ones (if Mirakl_Warehouse_IDs is not empty) – MIRAKL_SAFETY_QTY custom column.
  • The Advanced Safety Qty workflow, when Mirakl_Enable_Advanced_Safety_Qty is True. This workflow uses custom columns and product fields found on the Amazon Product Properties Page. It is a Custom Inventory Calculation embedded in the Mirakl plugin that follows these rules:
    • Quantity to Export = (Total Available Quantity * Mirakl_Inventory_Percent) – Amazon Safety Qty.
    • Quantity = Aggregate inventory from all sellable warehouses or from the specified ones (if Mirakl_Warehouse_IDs is not empty).
    • Amazon Safety Qty = Amazon safety quantity, either on product or company level, depending on Use Company Default.
    • If a product has the MiraklMaxQtyEnabled custom product column set to True, and the exported quantity is greater than the MiraklMaxQty value, then the latter will be exported.
The Basic and Advanced Safety Qty workflows will never export negative values. In such a case, they will export 0 instead.

RMA Import

The RMA import plugin downloads completed refunds from Mirakl and creates them in Sellercloud. Orders that are in process and with a closed full refund will be marked as completed. 

While returns are imported into Sellercloud, you must always process them on Mirakl.

Overview

Mirakl is a marketplace platform software that helps website retailers partner with third-party sellers to grow their online offerings and expand their market reach. Sellercloud lets you connect with various selling channels through Mirakl. You can automate your daily e-commerce operations and manage your inventory, orders, and shipping for these channels through Mirakl:

Click the links above for step-by-step instructions on integrating these channels. For a full list of integrations, see Mirakl’s Website.

These integrations work by transmitting information via API. The following plugins for Sellercloud are currently available:

  • Order Import – Imports orders from Mirakl channels to Sellercloud.
  • Tracking Export  – Exports tracking information to Mirakl channels.
  • Inventory Export – Updates inventory on Mirakl channels.
  • RMA Import – Imports RMAs to Sellercloud.

If necessary, you can contact Sellercloud Support to request additional customizations or other plugins for each integration. Note that these customizations are billable, and you will be provided a quote.


Prerequisites 

You integrate channels through Mirakl by following these steps:

  1. Contact Sellercloud Support and request:
    1. To install the Mirakl Plugins.
    2. To create Custom Product and Order Columns.
  2. Create a new Company for the integration.

    Sellercloud imports Mirakl orders under the Website channel. If you integrate multiple channels through a single company, you won’t be able to tell which channel your orders are coming from. Creating a company for each channel integration prevents this issue – you can search by Company instead of by Channel to see only orders from a specific channel.
  3. Create Custom Company Settings for authentication and to configure how the integration works.
  4. Enable the integration by preparing your products and then creating Scheduled Tasks. These tasks use Saved Searches to target specific orders or products and run the plugins on a regular basis.
You can sign up for Premium Support to get a dedicated Sellercloud Representative who will take you through the whole process and assist you every step of the way.

See the following sections for a detailed description of each step.

Contact Sellercloud Support

To get started, contact Sellercloud Support and request to install the Mirakl plugins on your server.

In addition, ask to add the following Custom Product and Order Columns:

Custom Product Columns

  • CHANNEL_Enabled – Optional setting. Type Boolean. Replace CHANNEL with the channel you are integrating through Mirakl. Use this setting if you only want to enable specific products for the integrated channel – set to True to enable a product.
  • MIRAKL_SKU – Type String. If a product’s SKU on Mirakl is not the same as the Sellercloud SKU, you must use this setting to enter the product’s Mirakl SKU, or else the Inventory Export will fail.
  • MIRAKL_PRICE – Type Decimal. The product’s price on Mirakl.
  • MIRAKL_AVAILABLE_STARTED – Type DateTime. This is the start date of the listing.
  • MIRAKL_AVAILABLE_ENDED – Type DateTime. This is the end date of the listing.

    MIRAKL_AVAILABLE_STARTED and MIRAKL_AVAILABLE_ENDED can be set to past dates as long as the start date is before the end date. Otherwise, Mirakl will reject the inventory and price update of the product.
  • MIRAKL_SHOP_IDS – Type String. Used only if the company setting Mirakl_Shop_IDs isn’t empty. Contains the ID of the Mirakl shop with the product.
  • MIRAKL_DISCOUNT_PRICE – Type Decimal. Optional setting. Sets a discounted price for a product on Mirakl.
  • MIRAKL_DISCOUNT_AVAILABLE_STARTED – Type DateTime. Optional setting. Sets the product discount’s start date.
  • MIRAKL_DISCOUNT_AVAILABLE_ENDED – Type DateTime. Optional setting. Sets the product discount’s end date.
  • MIRAKL_SAFETY_QTY – Type Integer. A Safety Quantity for products on the integrated channel.
  • MIRAKL_MANUFACTURER_WARRANTY – Type Integer. Used to set a product’s manufacturer warranty.
  • MIRAKL_MANUFACTURER_WARRANTY_USE_DEFAULT – Type Boolean, defaults to False. If you set it to False, your products’ warranty will come from the product custom column MIRAKL_MANUFACTURER_WARRANTY. If you set it to True, the warranty will come from the custom company setting Mirakl_Manufacturer_Warranty.
  • MIRAKL_LOGISTIC_CLASS – Type String with an optional selected value. If in use, adds a drop-down where a single value can be selected. See the links in the Overview for more information about the values for each channel.
  • MIRAKL_DESCRIPTION – Type String. Sets the product’s description on Mirakl. If you don’t use this setting, the product’s name in Sellercloud will be sent as the description.
  • MIRAKL_INTERNAL_DESCRIPTION – Type String. Sends an internal description of the product.
  • MIRAKL_PRICE_ADDITIONAL_INFO – Type String. Sends additional information about the price.
  • MIRAKL_OFFER_STATE – Type String, a dropdown menu that indicates the product’s condition. The default will be 11 (NEW) if this setting is missing or there’s an invalid Mirakl_Integration_Name. The following integrations default to 1: Weight Watchers, Bed Bath and Beyond, Hudson’s Bay, UNFI, Snappy, Ahold Delhaize, Peapod Digital Labs, and Belk.
    • Hudson’s Bay US state codes: 1 (New), 8 (Pre-Loved), 10 (Refurbished), 11 (Vintage) – find attached
    • Belk state codes: 1 (New), 10 (Refurbished)
    • Shop Premium Outlets state codes: 11 (New), 1 (Preowned – Pristine), 2 (Preowned – Very Good), 3 (Preowned – Good), 4 (Preowned – Fair), 10 (Refurbished),
    • Giant Eagle state codes: 11 (New), 1 (Used – Like New), 2 (Used – Very Good Condition), 3 (Used – Good Condition), 4 (Used – Acceptable Condition), 5 (Collectors – Like New), 6 (Collectors – Very Good Condition), 7 (Collectors – Good Condition), 8 (Collectors – Acceptable Condition), 10 (Refurbished)
    • Darty.com state codes: 11 (New), 1 (Used – Very Good Condition), 2 (Used – Perfect Condition), 3 (Used – Correct Condition), 10 (Used – Good Condition)
  • MIRAKL_EXPORT_OFFER_STATE_NEW – Type Boolean. Defaults to False. This setting is required and used only when the company setting MiraklEnableExportOfferStateNew is enabled. Then the plugin will export the default offer state code (NEW) instead of the selected MIRAKL_OFFER_STATE.
  • MiraklMaxQtyEnabled – Type Boolean. Set to True to enable the MiraklMaxQty setting below.
  • MiraklMaxQty – Type Integer, used if MiraklMaxQtyEnabled is set to True. Sets the product’s maximum product quantity on the channel.
  • MiraklMaxQtyUseDefault – Type Boolean, set to True to use the maximum quantity set on the Company Level instead of the product-level setting above.
  • MIRAKL_OFFER_TAXCODE – Type String. Stores the tax code associated with a Mirakl offer. This setting overrides the company-level custom setting Mirakl_Offer_TaxCode, which sets a default tax code value. If this setting is missing, the default will be used.
  • MiraklReplenishableQtyToSend – Type Integer. Sends a replenishable quantity. The product must be configured as Replenishable.
  • MiraklUseDefaultReplenishableQty – Type Boolean. Set to True to use the default replenishable quantity set on the company level with the MiraklDefaultReplenishableQty setting instead of the product-level quantity set in the MiraklReplenishableQtyToSend product custom column.
  • Mirakl_MinQtyAlert – Type Integer. Optional setting. Defaults to 1. Sets a minimum quantity for the product. Mirakl will send you an alert when this quantity is reached.

Custom Order Columns

  • MIRAKL_CHANNEL – Type String. The Order Import plugin uses this column to save the name of the order’s channel.
  • MIRAKL_SHOP_ID – Type Integer. The Order Import plugin populates the Mirakl shop ID from which the order has been imported if the custom company setting Mirakl_Shop_IDs is not empty or missing.

Create and Configure a Company 

As mentioned above, Mirakl orders are imported under the Website channel. If you integrate multiple channels through a single company, you won’t be able to tell which channel your orders are coming from. 

Creating a company for each channel integration prevents this issue, as you can search by Company instead of by Channel to see only orders from a specific channel. This is why it’s best to create a new Company for the Custom Company Settings and Scheduled Tasks.

Next, create the following Custom Company Settings on the company you created for your integration:

  • Mirakl_Integration_Name – This setting’s value will be added to the custom order column MIRAKL_CHANNEL to show each order’s source channel. The following values are acceptable: BestBuy.Ca, BestBuyCa, BestBuy Canada, Catch, Catch.com, Express, Express.com, BlueFly, WW, Weight Watchers, Kroger, HudsonsBayUS, Knott, Knot, The Knot, The Knott, OrientalTrading US, Verishop US, Belk, BedBathAndBeyond, BedBathAndBeyond US, Ahold, Peapoddigital, Snappy, Carrefour, Carrefour.es, ShopPremiumOutlets, SPO, GiantEagle, Madewell, UrbanOutfitters, Kohls, Kohl’s, Saks, Macys, Macys US, Maisonette (not case sensitive), 1800flowers, Darty.com, MathisBrothersUS, SalonCentric, NBCUniversal, Reitman, Tiendamia, Liverpool, and General Electric. 
  • Mirakl_API_URL – Enter the API URL of the channel you are integrating through Mirakl. Check with Mirakl’s support team for the value of the setting.
  • Mirakl_API_Key – Your Mirakl authentication key. On Mirakl, you can find it by clicking your email address in the top right corner and selecting API Key.
  • MiraklOAuthTokenId – Used as an alternative to Mirakl_API_Key. Don’t assign it any value, and you will automatically get a token from the scheduled tasks.
  • Mirakl_Always_Accept_Orders – Optional setting. Can be set to True or False. Determines if orders with pending acceptance will be accepted even if there’s not enough inventory on hand to fulfill them. If this setting is missing, the plugin will not accept such orders.
  • Mirakl_Get_Only_Recent_Orders – Set to True for the Order Import plugin to get only orders modified in the past 10 days. Don’t create the setting or set it to False for the initial order import. Then, set it to True to speed up the plugin and avoid reaching API limits.
  • Mirakl_Shop_IDs Type String. Enter a comma-separated list of Mirakl shop IDs. The Order Import plugin will only import orders from the Mirakl shops you list here. If this setting is missing, the plugin will only import orders from the first shop associated with your Mirakl user account.
  • Mirakl_Order_Statuses – Optional setting. Only orders with the order statuses listed here (comma-separated) will be imported. If you don’t create this setting, only orders with the status of WAITING_ACCEPTANCE, PAYMENT_COLLECTED, SHIPPING, SHIPPED, RECEIVED, and CLOSED will be imported.
  • Mirakl_Import_orders_with_source_BestBuy_instead_of_Website – Optional setting. Defaults to False. Determines if BestBuy orders will be imported under the Website or BestBuy channel.
  • Mirakl_Shipping_Method – Optional setting. Sets a specific shipping method for imported orders.
  • RunPostOrderPluginAfterOrderCreation – Optional setting. Defaults to False. Set it to True if you need to run a post-order plugin once Mirakl orders are created/updated.
  • Mirakl_Manufacturer_Warranty – Defaults to 0. Sets a default manufacturer warranty period for Mirakl products. Used when the MIRAKL_MANUFACTURER_WARRANTY_USE_DEFAULT custom product column is set to True.
  • Mirakl_Warehouse_IDs – A comma-separated list of warehouse IDs to export inventory from. Works with both the Basic and Advanced Safety Quantity workflows.
  • Mirakl_Enable_Advanced_Safety_Qty – Defaults to False. Enables the Advanced Safety Quantity workflow.
  • MIRAKL_UseAdvancedKitProjecting – Defaults to False. When set to True, Independent Kit Products get an estimated sellable quantity if there are no assembled items. All Component kits get items out of Independent kits when projecting.
  • Mirakl_Inventory_Percent – Used with the Advanced Safety Quantity workflow. Decimal value (80 means 80%), defaults to 100%. 
  • MiraklEnableExportOfferStateNew – Defaults to False. When set to True, this setting enables the use of the custom product column MIRAKL_EXPORT_OFFER_STATE_NEW. With this setting enabled, the Inventory Export plugin will export the default offer state code (NEW) instead of the selected MIRAKL_OFFER_STATE.
  • Mirakl_Offer_TaxCode – Optional String. Sets a default tax code for all products. If this setting doesn’t exist, you must set each product’s tax code individually using the MIRAKL_OFFER_TAXCODE setting. The tax code is a required field for Inventory Export updates to go through successfully.
  • MiraklDefaultReplenishableQty – This value is exported as the inventory for Replenishable Products if the MiraklUseDefaultReplenishableQty custom column is enabled on the product level.
  • Mirakl_ExcludeNonPayableToShopTaxes – Set to True to determine if the Order Import should include taxes facilitated by the marketplace or not.
  • Mirakl_DontRunPostOrderOnWaitingAcceptanceOrders – If you set this to True, Sellercloud will not run post-order actions on orders that were created with the WAITING_ACCEPTANCE status from Mirakl, have an empty shipping address, or the payment status is not Charged.
  • Mirakl_ProductIDType – This setting determines the product ID type sent by the Inventory Export. The value you enter will be the exact value that gets sent to Mirakl. If this setting doesn’t exist, SHOP_SKU will be sent as the value.

Integration Setup 

Now that the Mirakl plugins have been installed on your server, the custom product and order columns have been created, and you have created the custom company settings, you’re ready to move on to the final part of the setup – automating the integration.

The automation consists of three parts – preparing your products, creating saved searches, and creating scheduled tasks.

Prepare Products 

For the Inventory Export plugin to send product updates successfully, these required Custom Product Columns must be populated on each product:
  • SKU – If a product’s SKU on Mirakl is not the same as the Sellercloud SKU, you must use the MIRAKL_SKU custom product column to enter the product’s Mirakl SKU, or else the Inventory Export will fail.
  • Product ID – Comes from the MIRAKL_SKU custom product column unless the Mirakl_ProductIDType custom company setting specifies a different product ID type.
  • Product ID Type – Comes from the Mirakl_ProductIDType custom company setting.
  • Start and End Dates – The MIRAKL_AVAILABLE_STARTED date must be before the MIRAKL_AVAILABLE_ENDED date.
  • Price – Comes from the MIRAKL_PRICE custom product column. It may also be set by the MIRAKL_DISCOUNT_PRICE.
  • State – Comes from the default set in the Mirakl_Offer_TaxCode custom company setting or the MIRAKL_OFFER_TAXCODE custom product column.
  • Quantity – Comes from the product’s available quantity in Sellercloud. The Safety Quantity Workflow, the MIRAKL_SAFETY_QTY custom product column, and the MiraklMaxQty and MiraklMaxQtyUseDefault custom company settings affect the quantity.
  • Product Tax Code – Comes either from the default set in the Mirakl_Offer_TaxCode custom company setting or the MIRAKL_OFFER_TAXCODE custom product column.
If something is missing, the plugin will generate an error message in the Queued Job with more details, and the product with the issue will be skipped.

If you only want to enable specific products for the inventory export, you must enable these products now. You do this by updating the CHANNEL_Enabled (where CHANNEL is replaced with the channel you are integrating) custom product column’s value to True. You can do this per product or in bulk:

  • For one product at a time: Go to the Product Details Page > click Toolbox and select Custom Columns > Update the CHANNEL_Enabled column >  click Save.
  • For multiple products in bulk: Follow the steps to Bulk Update Products and add the CHANNEL_Enabled column – set it to True for all products you want to enable.

Create Saved Searches 

The Saved Searches determine the orders and products targeted by the plugins when the scheduled tasks run. You must create one saved search for orders for the Tracking Export and one saved search for products for the Inventory Export.

For the Tracking Export, go to Orders and filter by:

  • Company – Choose the integration company
  • Order Status – InProcess Or Completed
  • Shipping Status – FullyShipped
  • Payment Status – Charged
  • Tracking Uploaded – No

For the Inventory Export, go to Inventory and filter by:

  • CHANNEL_Enabled – True.
  • Active Status – Active
  • You can add more filters per your preference.

Create Scheduled Tasks 

Next, you need to create a Scheduled Task for each plugin:

For the Order Import plugin:

  • Set the Task Type to Import Orders.
  • Create Orders for Company – select the company you designated for this integration.
  • Set the Order Processor Plugin/Profile to Mirakl Order Import.

For the Tracking Export plugin:

  • Set the Task Type to Export Orders
  • Set the User ID to the user you used to create the saved search for orders.
  • Set the Saved Search to the orders search you created for the Tracking Export.
  • Set the Export Via to Mirakl Order Tracking Export.
  • Check Mark Orders As Exported.
  • Check This Is Tracking Export.

For the Inventory Export plugin:

  • Set the Task Type to Export Products
  • Set the User ID to the user you used to create the saved search for products.
  • Set the Saved Search to the products search you created for the Inventory Export
  • Set the Export Via to Mirakl Inventory Export Plugin.
Do not update more than 60,000 products per hour, or you will reach the limit of 60 API calls per hour.

For the RMA Import plugin:

  • Set the Task Type to Import Orders.
  • Set the RMA Processor Plugin to Mirakl Order Import.

On all four scheduled tasks, do the following:

  • Set Export To/Import From to None.
  • Specify the task frequency. For optimal performance, select a range between thirty minutes and one hour.
  • Check the Schedule Enabled box on top.

Integration Details

See the following sections for details on how Mirakl integrations work.

Order Import

This plugin downloads orders through the API and imports them as Website orders in Sellercloud. Orders will be created with the email customer_id@integrationName.com. For example, 12345@catch.com, 67890@bestbuy.ca.

The plugin will send order acceptance to Mirakl if all your ordered items have enough inventory to fulfill the order. Orders will be set as canceled on Sellercloud and Mirakl if an item has insufficient inventory.

Note the following important details describing how the plugin interacts with orders with different statuses:

  • If the custom company setting Mirakl_Order_Statuses doesn’t exist, only orders with a Mirakl status WAITING_ACCEPTANCE, SHIPPING, PAYMENT_COLLECTED, SHIPPED, RECEIVED, and CLOSED will be imported. If this setting exists, then only orders with the statuses you list there will be imported.
  • Orders with the status SHIPPED, RECEIVED, and CLOSED will be imported as completed. 
  • Orders with the status SHIPPED and RECEIVED will be marked as fully shipped, while CLOSED ones will be marked as shipped only if they have a tracking number or a carrier name.
  • Orders with the status WAITING_ACCEPTANCE are downloaded with empty addresses. After acceptance, Mirakl sends them again with the status SHIPPING, and addresses are added to the relevant orders by the plugin.
  • After an order that’s pending acceptance is created in Sellercloud, the plugin will check the custom company setting Mirakl_Always_Accept_Orders. If True, the order will be automatically accepted. If False, an acceptance is sent to Mirakl only if there’s sufficient product inventory to fulfill the whole order. Otherwise, it will be rejected, and the Sellercloud status will be changed to Cancelled.
For each imported order, the ordered products must exist in Sellercloud with either the same SKU or with the Mirakl product ID in the MIRAKL_SKU custom column. Otherwise, order items will be Unknown, their inventory on hand will be considered 0, and the order will be refused on Mirakl.

Tracking Export

The Tracking Export plugin exports the shipping carrier and tracking number, then marks the order as shipped on Mirakl.

Tracking confirmation is saved to the order action documents as a TrackingUpload_PreShip. If it’s successful, the plugin will skip tracking updates for this order and will try sending a shipping confirmation.

Shipping confirmation is saved to the order action documents as a TrackingUpload. If it’s successful, the plugin will skip sending it again.

Inventory Export

The Inventory Export plugin exports the available inventory, price, and offer start and end date from Sellercloud to the channel:

  • The price is set in the custom column MIRAKL_PRICE.
  • The description is the product’s name in Sellercloud by default. If the MIRAKL_DESCRIPTION custom column exists, it is used to set the description.
  • The offer start and end dates are set in the custom columns MIRAKL_AVAILABLE_STARTED and MIRAKL_AVAILABLE_ENDED.

Products are matched by Mirakl SKU (either the Sellercloud SKU or the custom column Mirakl_SKU, matched to the Mirakl SKU under Settings, not the one in the summary on top).

Do not update more than 60,000 products per hour, or you will reach the limit of 60 API calls per hour.
The following fields are required for a successful inventory update: 
  • SKU – You can use the MIRAKL_SKU custom product column to specify the SKU if it’s not the same as the Sellercloud SKU.
  • Product ID – Comes from the MIRAKL_SKU custom product column unless the Mirakl_ProductIDType custom company setting specifies a different product ID type.
  • Product ID Type – Comes from the Mirakl_ProductIDType custom company setting.
  • Price – Comes from the MIRAKL_PRICE custom product column. It may also be set by the MIRAKL_DISCOUNT_PRICE.
  • State – Comes from the default set in the Mirakl_Offer_TaxCode custom company setting or the MIRAKL_OFFER_TAXCODE custom product column.
  • Quantity – Comes from the product’s available quantity in Sellercloud. The Safety Quantity Workflow, the MIRAKL_SAFETY_QTY custom product column, and the MiraklMaxQty and MiraklMaxQtyUseDefault custom company settings affect the quantity.
  • Product Tax Code – Comes either from the default set in the Mirakl_Offer_TaxCode custom company setting or the MIRAKL_OFFER_TAXCODE custom product column.
If something is missing, the plugin will generate an error message in the Queued Job with more details, and the product with the issue will be skipped.

There are two Safety Quantity workflows that function as follows:

  • The Basic Safety Qty workflow, when Mirakl_Enable_Advanced_Safety_Qty is missing or False.
    • Aggregate inventory from all sellable warehouses or from the specified ones (if Mirakl_Warehouse_IDs is not empty) – MIRAKL_SAFETY_QTY custom column.
  • The Advanced Safety Qty workflow, when Mirakl_Enable_Advanced_Safety_Qty is True. This workflow uses custom columns and product fields found on the Amazon Product Properties Page. It is a Custom Inventory Calculation embedded in the Mirakl plugin that follows these rules:
    • Quantity to Export = (Total Available Quantity * Mirakl_Inventory_Percent) – Amazon Safety Qty.
    • Quantity = Aggregate inventory from all sellable warehouses or from the specified ones (if Mirakl_Warehouse_IDs is not empty).
    • Amazon Safety Qty = Amazon safety quantity, either on product or company level, depending on Use Company Default.
    • If a product has the MiraklMaxQtyEnabled custom product column set to True, and the exported quantity is greater than the MiraklMaxQty value, then the latter will be exported.
The Basic and Advanced Safety Qty workflows will never export negative values. In such a case, they will export 0 instead.

RMA Import

The RMA import plugin downloads completed refunds from Mirakl and creates them in Sellercloud. Orders that are in process and with a closed full refund will be marked as completed. 

While returns are imported into Sellercloud, you must always process them on Mirakl.

Was this article helpful?

Need Support?
Can't find the answer you're looking for?
Contact Support