Colizey - Return & Refund Management

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 document is to detailed describe the process of how we can initiate a refund on Colizey.

From the documentation seems Colizey support full and partially refunds.

If there is a refund, we will receive refund information into the response of Get Order Details. The information into the payload will be regarding the return (date & time, id, etc) and the items which need to be returned (id, sku, quantity). More detailed information regarding the downloading refunds in Hemi is described in Colizey - Download Orders

The buyer is able to cancel the order only after he pay the order, i.e. when the status of order is “PAID“. If there is a cancellation/refunds initiated by the buyer on this status of the order, we will receive the info for cancelled items (or the whole order) within the Get Order List response and we need to create a refund row respectively.

Basically we are able to initiate a full or partial refund on Colizey. There are no differences between pre & post-shipment creation of the refund. We can create full or partial refund based on the parameters we specify. We are not able to refund an order which is not accepted by us (i.e. orders on Colizey status “New-0“ & “Paid - 1“, respectively Hemi statuses “Incomplete“ & “Pending“.

API Call: POST https://api.colizey.fr/merchant/orders/{orderId}/refund

API Docs: https://apidoc.colizey.fr/#refund-an-order

Query parameters:

Body Parameters:

[
    {"sku": "sku_5", "quantity": 0},
    {"sku": "sku_6", "quantity":0 }
]

To refund an order, we should push the order ID which we have stored in Orders > Marketplace Order ID.

Case 1: Full order cancellation (all items + shipping)

To perform such operation we should push refundedShipping=null and no lines provided, i.e. lines[]

• If no line is provided AND refundedShipping is null, then all the order will be refund

[]

Response example:

{
    "id": "c5b59ba1-784e-4e56-85c2-f91b2428ec01",
    "date": "2022-09-05T10:39:08+00:00",
    "lineReturns": [
        {
            "id": "4a8e447c-71e7-4928-9d78-8113f6f3bdef",
            "sku": "sku_6",
            "quantity": 20
        },
        {
            "id": "5b466f4d-f131-4b3e-b04d-3a63edda2eb2",
            "sku": "sku_5",
            "quantity": 5
        },
        {
            "id": "bd94ec67-5635-4753-9147-f696c7fab2c0",
            "sku": "sku_4",
            "quantity": 2
        }
    ],
    "refundedShipping": 0,
    "reason": null,
    "amount": 85000
}

Mapping:

• If no quantity is provided for an sku, then all the quantity for this sku will be refund, i.e. if we push quantity =0 into the payload, all quantities will be refunded:

[
    {"sku": "sku_5", "quantity": 0},
    {"sku": "sku_6", "quantity":0 }
]

We cannot cancel full order if is not accepted. If we try to cancel it, error message should appear “The order is not accepted“, and to store the error in Order Error table.

Case2: Partial order cancellation(refund)

To perform partial order cancellation we should specify the sku we would want to refund + the quantity.

For example:

[
    {"sku": "sku_5", "quantity": 1},
    {"sku": "sku_6", "quantity": 5}
]

This means for sku_5 we want to refund 1 qty, but for sku_6 we want to refund 5 qty. After success, we will receive the exact calculation of returned items and need to store them in refund row.

Response example: ( with order number CLZ2208942662)

{
    "id": "e10040a8-185f-4c58-9519-1f4e458deaa5",
    "date": "2022-09-05T10:32:47+00:00",
    "lineReturns": [
        {
            "id": "c5cb7c05-f2ec-49c4-a467-369ee65d2e67",
            "sku": "sku_5",
            "quantity": 5
        }
    ],
    "refundedShipping": 0,
    "reason": null,
    "amount": 15000
}

When refundedShipping is null, then :

• if all items are refunded, the shipping will be refunded as well ;
• if at least one item is not refunded, then the shipping will not be refunded.
• When refundedShipping is false, then you should at least provide one line to refund.
• When refundedShipping is true, then there should be something to refund, either the shipping itself, or you provided one item to refund, or both.
• We can refund shipping only if you do not provide lines and set refundedShipping` ` totrue``.

*Important:** Bear in mid that we are not allow to perform only partial shipping refund, i.e. we need to make sure when we initiating a refund, the shipping whole shipping will be refunded.

Error cases:

• If the quantity is set and above the current quantity - Error message: “Invalid quantity“
• If an sku is not found - Error message: “Invalid SKU“
• The call refunds nothing - i.e. if we try to refund already fully refunded order - Error message: “Order was already cancelled “

Edge cases:

1. If we try to refund an order which is not accepted, then the error message will be returned, i.e. we are not allowed to refund an order which is not accepted! We should store the respective error in Order error table and to specify the error message “Orders which are not accepted cannot be refunded“

{
    "error": "unknown"
}

Note: Seems now they are returning unknow error, will be clarified with CLZ

2. If we send a refund to a order, with wrong qty to one of the skus:

500Internal Server Error

{
    "error": "unknown"
}

Useful docs: Refunds send general logic