Catch Technical Scope

The purpose of this document is to give good understanding of MIRAKL integration type. We can use most of the code we already have for GoSport and the basic logic. However the additional tables, enumerations and fields need to be created and SQLs to be updated in the code.

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)

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

postman.json

Authentication

https://marketplace.catch.com.au/help/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://marketplace.catch.com.au/api API KEY - a0183ed2-7dfa-4de8-85a0-0f187fd89c51

Product flows

In MIRAKL the product flow is first we have to create the product, then create the offer. Offer is live listings on the marketplace and we can send offer updates (Stock/Price) or delete it.

1. Product Creation - Every time we send products for creation we have to do internal check if all required attributes are part of the the product as Item Specifics according to their taxonomy which we download and store on the instance. If our validation is successful and the product is send for creation we set our status as Product status - Inactive and Listing Status - Product created and Revise Item - Pending. 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 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. 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 Product status - Inactive and Listing Status - Product created and Revise Item - Pending Once we create the offer successfully we set the statuses as Product status - Active and Listing 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 Update Item Error again if no result is returned 404 this means the offer is created successfully.

   

3. Offer Full UpdateUpdate everything possible. The call we use is OF01 with "update_delete": "update". Only if Product status - Inactive and Listing Status - Product Created 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 Product status - Active and Listing Status - Product Published and Update Item - Not Needed We also send offer update when we have Product status - Active and Listing 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 Product status - Inactive and Listing Status - Product Created 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 Product status - Active and Listing Status - Product Published and Update Price - Not Needed and Update Quantity - Not Needed.  We also send offer update when we have Product status - Active and Listing 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 - End Item send 0 stock to the offer only if the statuses are Product status - Active and Listing Status - Product Published and End Item - Yes then after successful update we set Product status - Inactive and Listing 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 Product status - Active and Listing Status - Product Published and End Listing = Yes. After successful deleted item we set the statuses as Product status - Inactive and Listing Status - Product Removed

Taxonomy flows - specifics

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

Which returns all the available categories for Catch. 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 Catch. 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 Catch. 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.  We should be able to generate category mapping files used for mapping in MIRAKL.

TBA

Orders flows

At stage 1 we will add only download orders, accept orders and ship orders. 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 at the acceptance time. 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!

   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 B" -

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 Canceled.  Get orders will get all new orders from the last 30 min 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 -

   Canceling or rejecting an order are irreversible actions. You cannot start again the order process for canceled 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

   <v1.1>

   PUT OR29 - Cancel an order not yet debited from the customer

   API Call: /api/orders/{order_id}/cancel

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

   We have to specify in the URL our Orders > Marketplace Order Id

   Cancel an order not yet debited from the customer. All accepted but NOT shipped orders are treated as “Not Yet Debited” which means that if a cancellation has to happen, we need to use the OR29 call instead of OR30. Please note only full order cancellations for non debited orders are allowed and we would like to add internal validation and return internal error if not full cancellation is done.

   Example call:

   PUT https://mirakl.marketplace.laredoute.com/api/orders/12341231-A/cancel

   Example Response: 204: No Content

   Please note since there is no content in the response we wont have a transaction id for the refund so we need to make a OR11 - List Orders call for the specific order that we have cancelled and store the transaction ID.

   This needs to be done after each 204: No Content response for the specific order that we are cancelling.

   We have developed all possible scenarios:

   • If we have can_cancel = true and customer_debited_date = null and can_refund = false We need to use the OR29 to cancel the order
   • If we have can_cancel = true and customer_debited_date = date (in a 2023-12-04T12:26:07.043Z format) and can_refund = false we need to use the OR30 to cancel
   • If we have for some reason can_refund = true and can_cancel = true we need to use the OR30 to cancel (this is not an expected behavior anyways, if for some reason it happens for whatever reason we want to have it covered)
   • If we have can_cancel = false and customer_debited_date = null and can_refund = true We need to use the OR28 to refund the order (this is not an expected behavior anyways, if for some reason it happens for whatever reason we want to have it covered)

   • If we have can_cancel = false and customer_debited_date = date (in a 2023-12-04T12:26:07.043Z format) and can_refund = true We need to use the OR28 to refund the order

     </v1.1>

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

   • SHIPPING
   • SHIPPED

   • RECEIVED

     OR28Request 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

Additional

Product Created: Listing status - Inactive Product status- Product created

Offer Created Listing status - Active Product status- Product Published

Default Listing status - Inactive Product status- Awaiting Creation

End Item Listing status - Inactive Product status - Product Removed

Offer Update - Listing status - Inactive Product status- Product Removed + Listing status - Active Product status - Product Published

At the moment we do not send any logistic classes which are set in each MIRAKL account and by default are applied on every listing but we are not able to control them in our current MIRAKL integration.

However we are able to download all logistic clases from MIRAKL using SH31 - List all logistic classes and store them as enumerations in a new dropdown field in Item Account Catch. Every product can have only one logistic class and we have to push the correct values returned in SH31.

Example Response of SH31:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<body>
    <logistic_classes>
        <logistic_class>
            <code>S</code>
            <description>Small</description>
            <label>Small</label>
        </logistic_class>
        <logistic_class>
            <code>M</code>
            <description>Medium</description>
            <label>Medium</label>
        </logistic_class>
        <logistic_class>
            <code>L</code>
            <description>Large</description>
            <label>Large</label>
        </logistic_class>
        <logistic_class>
            <code>OV1</code>
            <description>Oversize 1</description>
            <label>Oversize 1</label>
        </logistic_class>
        <logistic_class>
            <code>OV2</code>
            <description>Oversize 2</description>
            <label>Oversize 2</label>
        </logistic_class>
        <logistic_class>
            <code>FREE</code>
            <description>Free Shipping</description>
            <label>Free Shipping</label>
        </logistic_class>
    </logistic_classes>
</body>

Once we have downloaded all logistic clases and we have select the relevant logistic class in item account catch for the product we have to push it with offer create or offer update like:

Please note this is recommended field so its not required.

Also we need to be able to send the correct state (condition) to MIRAKL based on the Item > ConditionId

value - 1000 = New (11) value - 2000 = Manufacturer refurbished (13) value - 3000 = Used (Pre-owned, Like new) (14)

And in MIRAKL New (or 11) Refurbished - Grade A (or 13) Refurbished - Grade B (or 14)

We will need to add additional field in item_account_catch > Keywords where we need to be able to import the product keywords and push them to Mirakl with Product Create Cron.

The field requirements are: "Words or phrases best describing your product for better search on the Catch site limited to 100 characters. The "|" character is to be used as the separator. E.g. For "Blue|White|Red", the separator is "|" (A "space" value will not be accepted)."

Here is an example how we shall add it in the XML:

We need to push this node only if we have populated the keywords in item_account_catch > Keywords