Debenhams Technical Scope

The purpose of this document is to give good understanding how the integration between Hemisphere and Debenhams (MIRAKL) will be automated and set up

The full postman collection is available here or from the file below.

postman.json

New Tables and fields

Authentication

https://debenhamsuk-dev.mirakl.net/help/sellers/topics/home_pages/seller_connectors_api.htm Authentication is done directly from the seller account on MIRAKL where an API key is generated which is used in the API calls.  END POINT -https://debenhamsuk-dev.mirakl.net/api/ API KEY - d0b0eea5-cb4c-4081-ba03-dae2eb9859ac

Product Management

1.Product Creation

Every time we send products for creation we have to do internal check if all required attributes are part of the product as Item Account > Item Specifics and Item Account Debenhams according to their taxonomy which we download and store on the instance.  In order to push a product for creation we must have Listing Status - Inactive and Product status- Awaiting Creation and Revise Item - Pending and Channel Item ID = empty and Closed = 0.   If our validation is successful and the product is send for creation we set our status as Listing Status - Inactive and Product status- Product created and Revise Item - Pending and populate the Channel Item ID.   We leave the status as pending in order to automate the whole flow. The call we have to use in order to create the products is P41. Based on the result, you have to call P45, P47, P31 P47 returns if the import is successful and how may warnings and errors we have in the file. If there are no errors we will receive: "message": "Resource not available : transform_errors on import id 7045173", "status": 404 P45 -get the actual status of the import. P31 - will return the product ID which we will have to store as item account > Channel Item ID If we are listing a variation item we have to include the variation group in the xml from item_account.  Then we are waiting for the products to be approved and then they will appear on MIRAKL with Pending status but if we try to send offers will return "Product does not exist".

2. Offer Creation

Once we have the products created in MIRAKL we can start sending the offers which is the actual stock and price. Create offer should pick products only with statuses Listing status - Inactive and Product Status - Product created and Revise Item - Pending and Channel Item ID != empty or Listing Status- Inactive and Product status - Product Removed and Revise Item - Pending and Channel Item ID != empty Once we create the offer successfully we set the statuses as Listing status - Active and Product Status - Product Published and Revise Item - Not Needed. For offer creation we use OF01 call which allow us to submit XML file with all our products.  Then we check the import status with OF02 In order to get the error if there is any we have to use OF03 and save in item account > Update Item Error again if no result is returned 404 this means the offer is created successfully.

3.Offer Full Update- Update everything possible. The call we use is OF01 with "update_delete": "update". Only if Listing status - Inactive and Product Status - Product Published and Update Item - Pending this mean this product was ended (0 stock send) and we make it active again if this is the case after successful update we have to set the status as Listing status - Active and Product Status - Product Published and Update Item - Not Needed We also send offer update when we have Listing status - Active and Product Status - Product Published and Update Item - Pending. and after successful update we set Update Item - Not Needed.

4.Offer Stock and Price Update - Update both price and stock only. The call we use is OF01 with "update_delete": "update". Only if  Listing status - Inactive and Product Status - Product Published and Update Price - Pending or Update Quantity - Pending this mean this product was ended (0 stock send) and we make it active again if this is the case after successful update we have to set the status as  Listing status - Active and Product Status - Product Published and Update Price - Not Needed and Update Quantity - Not Needed.  We also send offer update when we have  Listing status - Active and Product Status - Product Published and Update Price - Pending or Update Quantity - Pending. and after successful update we set Update Price - Not Needed and Update Quantity - Not Needed

5.Zero quantity updates - The call we use is OF01 with "update_delete": "update". End Item send 0 stock to the offer only if the statuses are   Listing status - Active and Product Status - Product Published and End Item - Yes then after successful update we set Listing status - Inactive and Product Status - Product Published and End Item - No. Please note that End Item - Yes with Closed - Yes  should trigger the update.

6.Delete offer - End listing will delete the whole offer from the MIRAKL. This can be done with OF01 with "update_delete": "delete". We can delete only active offers with status  Listing status - Active and Product Status - Product Published and End Listing = Yes.  After successful deleted item we set the statuses as Listing status - Inactive and Product Status - Product Removed

Order Management

When creating an order, the operator can define his/her payment workflow. According to the selected payment workflow, the logistic order workflow changes.

• The "Pay on Acceptance" workflow corresponds to orders that are debited after the order acceptance. Then, orders receipt can only be confirmed after the payment.

• The "Pay on Delivery" workflow corresponds to orders that are debited later in the workflow. It can be done for example at the delivery time or when the customer collects the order at the store.

  We will be following the "Pay on Acceptance" workflow!

Order status:The we need to get order is as follows: Get Orders cron should download orders according to their mp status in the following way:

SUCCESS FLOW

mp status -  Waiting_Debit_Payment payment status - Pending | | 3 | tool status - Pending mp status -  Payment_Collected payment status - Completed | | 4 | tool status - Ready for Shipping mp status -  Shipping payment status - Completed | | 5 | tool status - Shipped mp status -  Shipped payment status - Completed | | 6 | tool status - Shipped mp status -  Received payment status - Completed |

REFUSE PAYMENT FLOW

mp status -  Waiting_Debit_Payment payment status - Pending | | 3 | tool status - Cancelled mp status -  Canceled payment status - Error OR  tool status - Cancel mp status -  Refused payment status - Error |

SUCCESS FLOW WITH REFUND

mp status -  Waiting_Debit_Payment payment status - Pending | | 3 | tool status - Pending mp status -  Payment_Collected payment status - Completed | | 4 | tool status - Ready for Shipping mp status -  Shipping payment status - Completed OR tool status - Shipped mp status -  Shipped payment status - Completed OR tool status - Shipped mp status -  Received payment status - Completed | | 5 | tool status - Shipped/Ready for Shipping mp status -  Refunded payment status - Completed refund status - pending | | 6 | tool status - Cancelled mp status -  Closed payment status - Completed refund status - Completed |

SUCCESS FLOW WITH CANCEL

mp status -  Waiting_Debit_Payment payment status - Pending | | 3 | tool status - Cancelled mp status -  Canceled payment status - Completed |

Other Possible Statuses

tool status - Ready for Shipping mp status -  To_Collect payment status - Completed

1. Get orders -

   To accept or reject your orders by API:

   • use API OR11 to list orders
   • use API OR21 to accept or reject the order

   GET ORDERS should create and new record in order_read table and every next run of the cron to get order 30mins before the latest record. If no records are available we get all available orders for the last 3 months!

   We need to have two cron one which will get/update orders and one which will accept orders once downloaded in WAP. Important things we have to download for each order are: order_line_id - Item Order Line ID (order item)" order_id - Order Id offer_sku - SKU (order item) product_sku - Channel Item ID (order item) order_line_state - Status (order item)

   By default we do accept all new orders

2. Get Modified Orders -

   We need to have a cron which will update the orders according to their MP status. We have to call each order in the last 30 days which are with statuses different from Closed and Cancelled.  Get orders will get all new orders from the last 30 min before the last record in last date run and they will be with Waiting Acceptance status.  Then we will accept the order and Get Modified Orders will update the status of the order as Debit In Progress. Then Get Modified will update to the following status which is Shipping and also will have to download the delivery and payment data. "

3. Ship orders -

   In order to ship an order it must be accepted and have cleared payment.

   OR23Update carrier tracking information for a specific order. You want to provide carrier information for each order of an order to process.OR24Validate the shipment of an order in the "SHIPPING" status. You want to confirm the shipment of an order.

   Also for MIRAKL we have a specific carries we can use in the attached Json

   If we shipping with other carriers we have to push empty carrier code with only carrier name and tracking num

4. Cancel/Refund orders -

   Cancelling or rejecting an order are irreversible actions. You cannot start again the order process for cancelled and rejected orders.

   If you need to assess and validate orders before they are sent to your sellers, we recommend that you use the scoring workflow.

   The following tables show which actions are possible on a Mirakl order according to:

   • the order workflow
   • the order status
   • the user role

   For order workflows, refunds can be opened from the same stages:

   • SHIPPING
   • SHIPPED

   • RECEIVED

     OR28 Request refunds on order lines. You want to create a refund on an order line.

     In order to refund an order we have to specify a reason the reasons which we can use are as follows:

     "reasons":[

     {

     "code": "14",

     "label": "Stockout"

     },

     {

     "code": "15",

     "label": "Lost"

     },

     {

     "code": "16",

     "label": "Cancelled by the client prior to shipping"

     },

     {

     "code": "17",

     "label": "Voluntary Return"

     },

     {

     "code": "18",

     "label": "Involuntary Return"

     }

     ]

     Payload for refund an order looks as follows: { "refunds": [{ "amount": 10, "currency_iso_code": "EUR", "order_line_id": ${ORDER_LINE_ID}, "quantity": 1, "reason_code": "14", "shipping_amount": 1, "shipping_taxes": [], "taxes": [] }] }

     Amount - Item Price  order_line_id - Item Order Line ID: quantity - Quantity reason_code - It will be good to have a option to select reasons if not use 14. shipping_amount - Item Shipping Cost:

carriers.json

Taxonomy flows - specifics

In order to download the taxonomy we need to use: (H11) api/hierarchies (GET)

Which returns all the available categories for Debenhams. We have to get that data and save it in MARKETPLACE CATEGORY table in WAP with the relevant Marketplace.

Once we have all categories we have to get all the required attributes for each category with (PM11) /api/products/attributes (GET)

Which returns all available attribute per category for Debenhams. We have to get that data and save it in MARKETPLACE CATEGORY PROPERTY table in WAP with the relevant information.

Then the final step is to get all available values for each attribute if applicable with: (VL11)/api/values_lists (GET)

Which returns all available values per attribute for Debenhams. We have to get that data and save it in MARKETPLACE PROPERTY VALUE table in WAP with the relevant information. Once we have save the taxonomy in WAP if we would like to update it the process should be delete the old one and get the new one.