Inno Refund Order

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 purpose of this page is to describe in details the refund flow on MIRAKL.

The refund/cancellation request on MIRAKL is per item line id and we can include each separate item as additional “refund“ or “cancellation“ node. To process the refund/cancellation , we have to specify a reason which need to be added in the Refund UI for Inno Marketplace. In order to obtain the reasons, we should use GET RE01 - List reasons call and then, to make a refund/cancellation , we should use PUT OR28 - Request a refund or OR30 - Request cancelations on order lines

• GET RE01 - List reasons

API Call:/api/reasons

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

Please note we need to store only the reasons which are with type = “REFUND“ and type = “CANCELATION“

Example response:

{
    "reasons": [
                {
            "code": "16",
            "is_shop_right": true,
            "label": "Cancelled by the client prior to shipping",
            "type": "REFUND"
        },
        {
            "code": "17",
            "is_shop_right": true,
            "label": "Product returned",
            "type": "REFUND"
        },
        {
            "code": "18",
            "is_shop_right": true,
            "label": "Product not received",
            "type": "REFUND"
        },
        {
            "code": "15",
            "is_shop_right": true,
            "label": "Product out of stock ",
            "type": "REFUND"
        },
        {
            "code": "14",
            "is_shop_right": false,
            "label": "No response from the seller",
            "type": "REFUND"
        },
        {
            "code": "19",
            "is_shop_right": true,
            "label": "Agreement found with the seller",
            "type": "REFUND"
        },
        {
            "code": "34",
            "is_shop_right": true,
            "label": "Cancelled by the client prior to shipping",
            "type": "CANCELATION"
        },
        {
            "code": "35",
            "is_shop_right": true,
            "label": "Out of stock product",
            "type": "CANCELATION"
        },
        {
            "code": "SYSTEM_LATE_SHIPMENT_CANCELATION",
            "is_shop_right": false,
            "label": "Canceled due to late shipment",
            "type": "CANCELATION"
        },
        {
            "code": "CANCELATION_order delivery-problem",
            "is_shop_right": true,
            "label": "Problem with order delivery",
            "type": "CANCELATION"
        },
        {
            "code": "SYSTEM_CANCELATION_DEBIT_FAILED",
            "is_shop_right": false,
            "label": "Debit failed",
            "type": "CANCELATION"
        },
        {
            "code": "36",
            "is_shop_right": true,
            "label": "Wrong selling price encoding",
            "type": "CANCELATION"
        },
        {
            "code": "SYSTEM_CANCELATION_DEBIT_TIMEOUT",
            "is_shop_right": false,
            "label": "Debit timed out",
            "type": "CANCELATION"
        },
        {
            "code": "37",
            "is_shop_right": true,
            "label": "Wrong product size conversion",
            "type": "CANCELATION"
        }
    ],
    "total_count": 14
}

Bear in mind we need to display the label into the UI but to send the code. Because in our UI we cannot distinguish the refund from the cancellation we need to add in the label what type is the reason is for the refund or for cancellation. E.G. [REFUND] - Product returned or [CANCELATION] - Out of stock product

• PUT OR28 - Request a refund

API Call: /api/orders/refund

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

*Note:** Each payment row (type=refund) will need to be send as a separate request. If even one of the refunds failed it will fail the whole feed. Thus we have agreed to push them per payment row. Which means we will have one request with all of the refund row nodes.

Example call: (one item in order)

{
  "refunds": [
    {
      "amount": 10.00,
      "currency_iso_code": "GBP",
      "order_line_id": "Order_25082022-6-A-1",
      "quantity": 1,
      "reason_code": "15",
      "excluded_from_shipment": false,
      "shipping_amount": 2.00
    }
  ]
}

Example call: (two items in order)

{
  "refunds": [
    {
      "amount": 10.00,
      "currency_iso_code": "GBP",
      "order_line_id": "Order_25082022-6-A-1",
      "quantity": 1,
      "reason_code": "15",
      "excluded_from_shipment": false,
      "shipping_amount": 0
    },
    {
      "amount": 10.00,
      "currency_iso_code": "GBP",
      "order_line_id": "Order_25082022-6-A-2",
      "quantity": 1,
      "reason_code": "15",
      "excluded_from_shipment": false,
      "shipping_amount": 0
    }
  ]
}

MIRAKL allows us to refund:

• Partially items;
• Shipping
• Orders

So the only validation we will need is to make sure we are not refunding more than we can for particular order item line!

Mapping:

• If we are doing partial line refund we specify the quantity as 0. • If we are doing full line refund (the full quantity) we specify the actual quantity we have for the item e.g. 1, 2, 3 etc. Note: For each full like we are having quantity = 1 For each partial like we will have quantity = 0 | | | reason_code | | | Order Payment > Reason | We need to use the reason code. | | | excluded_from_shipment | | | N/A | | | | shipping_amount | | | Refund Row > Amount | Refund rows with type “shipping “ |

Example Response: (one item in order)

{
    "order_tax_mode": "TAX_INCLUDED",
    "refunds": [
        {
            "amount": 10.00,
            "amount_breakdown": {
                "parts": [
                    {
                        "amount": 10.00,
                        "commissionable": true,
                        "debitable_from_customer": true,
                        "payable_to_shop": true
                    }
                ]
            },
            "currency_iso_code": "GBP",
            "excluded_from_shipment": false,
            "order_line_id": "Order_25082022-6-A-1",
            "quantity": 1,
            "reason_code": "15",
            "refund_id": "1109",
            "shipping_amount": 2.00,
            "shipping_amount_breakdown": {
                "parts": [
                    {
                        "amount": 2.00,
                        "commissionable": true,
                        "debitable_from_customer": true,
                        "payable_to_shop": true
                    }
                ]
            },
            "shipping_taxes": [],
            "taxes": []
        }
    ]
}

Response Mapping:

• PUT OR30 - Request cancelations on order lines

API Call: /api/orders/cancel

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

*Note:** Each payment row (type=refund) will need to be send as a separate request.

Example call: (one item in order)

{
  "cancelations": [
    {
      "amount": 1996,
      "currency_iso_code": "GBP",
      "order_line_id": "419244321-PUM-A-1",
      "quantity": 0,
      "reason_code": 34,
      "shipping_amount": 0

    }
  ]
}

Example call: (two items in order)

{
  "cancelations": [
    {
      "amount": 1996,
      "currency_iso_code": "GBP",
      "order_line_id": "419244321-PUM-A-1",
      "quantity": 0,
      "reason_code": 34,
      "shipping_amount": 0

    },
    {
      "amount": 1996,
      "currency_iso_code": "GBP",
      "order_line_id": "419244321-PUM-A-2",
      "quantity": 0,
      "reason_code": 34,
      "shipping_amount": 0
    }
  ]
}

MIRAKL allows us to refund:

• Partially items;
• Shipping
• Orders

So the only validation we will need is to make sure we are not refunding more than we can for particular order item line!

Mapping:

• If we are doing partial line refund we specify the quantity as 0. • If we are doing full line refund (the full quantity) we specify the actual quantity we have for the item e.g. 1, 2, 3 etc. | | | reason_code | | | Order Payment > Reason | We need to use the reason code. | | | shipping_amount | | | Refund Row > Amount | Refund rows with type “shipping “ |

Example Response: (one item in order)

{
    "cancelations": [
        {
            "amount": 2.00,
            "amount_breakdown": {
                "parts": [
                    {
                        "amount": 2.00,
                        "commissionable": true,
                        "debitable_from_customer": true,
                        "payable_to_shop": true
                    }
                ]
            },
            "cancelation_id": "1146",
            "currency_iso_code": "GBP",
            "order_line_id": "419244321-PUM-A-2",
            "quantity": 0,
            "reason_code": "34",
            "shipping_amount": 0.00,
            "shipping_amount_breakdown": {
                "parts": [
                    {
                        "amount": 0.00,
                        "commissionable": true,
                        "debitable_from_customer": true,
                        "payable_to_shop": true
                    }
                ]
            },
            "shipping_taxes": [
            ],
            "taxes": [
            ]
        }
    ],
    "order_tax_mode": "TAX_INCLUDED"
}

Response Mapping:

Specifics:

We will have couple of cases here because we will have one Order Payment row with type = refund but in MIRAKL there might be couple of transaction:

• If all transaction are successfully and we receive the refund_id or the cancellation_id ,we need to mark the Order Payment > Status = "Completed" and Refund Row > Status = "Completed"
• If not all transactions are completed but we have one or more completed we mark the Order Payment > Status = “Partially Completed“, Refund Row > Status = “Completed“ for the successful line and Refund Row > Status = “Error“.

Note: The error message stating which Order Item Line failed is stored in Order Error table.

• If all transactions failed we mark Order Payment > Status = “Error“, Refund Row > Status = “Error“ and store the error in Order Error table.

How to decide when to make a cancellation or refund is stated on the order. There are two flags which we can rely on in the order payload called "can_cancel" and “can_refund“ based on them we will know which is the correct request. If we have a case where both flags are set as true we pick as default the cancellation flow,