OMSPro Create Return

The purpose of this document is to give good explanation on how we can send a return to OMSpro.

The idea of this call is if we receive a return from Amazon or Noon, we need to push this return to OMSPro as well.

API Live Endpoint : POST https://pumaglobal.omspro.com:8443/HEMI/ReturnOrder

API Sandbox Endpoint : POST https://puma-test.openoms.net:8084/HEMI/ReturnOrder

Since this will not be a typical return send request i.e we still need to first push it to the marketplace, so essentially we will have a completed refund row, so we don’t want to use any abstraction but rather we want to have different triggers.

We want to check for the Product In Order > Fulfillment Status for the product we are refunding and based on this we could understand if we are doing a return or a cancellation. The triggers for the return are :

Product In Order > Fulfillment Status = Fully Shipped

Order Payment > Connector ID = ‘’

Orders > Refunded = Yes

(Order Payment > Type = Refund AND Order Payment > Status = Completed)

<v1.6>

PLEASE NOTE: We have a new need for this script. It should also pick Claims in specific cases. Claims should be picked only if we have a field called “Send Claim” in Channel OMS selected (new field on the Channel level of the connector). If Claims are to be sent Refunds are NOT to be sent (so it is one or the other). In the case of “Send Claim” the main trigger remain the same:

Product In Order > Fulfillment Status = Fully Shipped

But we also add a “claim” trigger instead of the Refund trigger

Order Claim > Status = Pending

We want to send each received Claim as a separate Return Request to OMS as per the mapping below (mostly the same as before)

If successful we want to store this in a new table Claim Connector where we should store a row when we send the claim, success full or not. We should have 3 fields in there, 1 Connector ID and 2 statuses - one for communications (standard MCP Status - pending, sent, error, normal) and one Connector Status for actual status of the Claim sending - it should have the following options

• Created
• Not Created
• Cancelled

We should pick for sending such claims that don’t have a record OR have a record on Status “pending” and Connector status - Not Created

If we create successfully we should create a record with MCP status “normal” and Connector status “Created” (or update existing one accordingly)

If we don’t manage to create we should create a record with MCP status “error” and Connector status “Not Created” (or we should update existing one accordingly). We should also store the error in Order Error with type Connector .

</v1.6>

Example request :

{
    "order_no": "206-6784434-4444189_35JSK8627234_TEST2",
    "ref_no1": "",
    "invoice_no": "",
    "reason_code": "R99",
    "reason_name": "R99-Marketplace Return",
    "return_comments": "",
    "return_date": "2024-07-30 14:17:48",
    "return_type": "",
    "application_id": "Amazon",
    "created_by": "HEMI",
    "return_tracking_no": "123abvbg",
    "return_order_details": [
      {
        "order_line_no": "5903",
        "reason_code": "R99",
        "reason_name": "R99-Marketplace Return",
        "product_id": 4063699705256,
        "product_ref1": "4064536266596",
        "quantity": 1,
        "shipping_fee": 0,
        "sub_total": 119.99
      }
    ]
}

Request mapping

Order Claim > ID </v1.6> | Yes | <v1.6> Send only for Account that have “Send Claim” = “yes” </v1.6> | | invoice_no | | N/A | No | | | reason_code | | | Yes | Hardcoded as “R99” | | reason_name | | | Yes | Hardcoded as “R99-Marketplace Return” | | shipping_fee | | <v1.4> Order Refund Row > Amount </v1.4> | Yes | <v1.4>We need to sum the shipping costs of all the Order Refund Row → Amount fields with type ‘Shipping’ within the payment row (with type refund) </v1.4>

<v1.6> Hardcode ‘0’ for Trendyol </v1.6> | | return_comments | | N/A | No | | | return_date | | Order Payment Details > Initially Created Date

OR

<v1.6> Order Claim > Marketplace Date </v1.6> | Yes | Note! This is for Order Payment Details > Type = Refund Needs to be in format “YYYY-MM-DD HH:MM:SS”

<v1.6> If “Send Claim” = “yes” we need to send the Claim Marketplace Date </v1.6> | | return_type | | N/A | No | | | application_id | | Account > Marketplace | No | | | created_by | | | No | Hardcoded as “HEMI” | | <v1.1>return_tracking_no | | Order Claim Shipping Info > Tracking number | Conditional | We need this field for Amazon orders, so if we have distinct marketplace = Amazon this is required. If we have distinct marketplace = Noon , we don’t want to include this field in the payload. </v1.1> <v1.6> If we have “Send Claim” = “yes” this info should always be Required </v1.6> | | return_order_details | | | | | | | order_line_no | <v1.3>Product In Order > Item Order Line ID </v1.3> | Yes | <1.6>When Send Claim = yes track this by the Order Claim Rows mapping back to the correct product </v1.6> | | | reason_code | | Yes | Hardcoded as “R99” | | | reason_name | | Yes | Hardcoded as "R99-Marketplace Return” | | | product_id | Product In Order > EAN | Yes | | | | <v1.1>product_ref1 | Product In Order > SKU</v1.1> | No | | | | quantity | | Yes | We need to calculate this since we do not do refunds based on quantity in Hemi. As a suggestion : Based on the price in the Order Refund Row > Amount we could identify the quantity we are refunding. Up to the dev team to decide how/what is best.

<1.6> For “Send Claim” = “yes” we will have exact quantity on the claim following the claim rows and to how many quantity items we’ve connected so we will be able to count it </v1.6> | | | shipping_fee | Order Refund Row > Amount | No | Note! If there is no shipping fee stored in Hemi, we need to send 0 as a value in this field. <v1.4> If there is a shipping fee refunded, it should be picked up from Order refund row → Amount with type shipping for the relevant Product in Order </v1.4>

<v1.6> Hardcode ‘0’ for Trendyol </v1.6> | | | sub_total | <v1.5>Order Refund Row > Amount +Product In Order > Discount Amount </v1.5> | Yes | Note! If we are sending shipping_fee we need to remove the amount of the shiping from the sub_total

<v1.6> We need to track the claim rows to obtain all items quantity for the relevant SKU in the claim (each SKU in the clam is a separate object in the return) and multiply this by the Product in Order > Item Trans Price </v1.6> |

Example response :

{
    "success": true,
    "message": "Insert Hemi Return Order success",
    "error_code": 0,
    "data": {
        "return_order": {
            "application_id": "HEMI",
            "b_city": "Al Seyouh",
            "b_country": "AE",
            "b_first_name": "Firstname2",
            "b_last_name": "LastName2",
            "b_phone": "08725189611",
            "capture_amount": 239.98,
            "capture_status": "CAPTURE_SUCCESS",
            "cod_fee": 0,
            "country_id": "AE",
            "created_by": "HEMI",
            "created_date": "2024-08-01T11:57:45.280",
            "currency_id": "AED",
            "customer_name": "FirstName2 LastName2",
            "customer_type": "Registered",
            "delivery_date": "2024-07-29T11:13:50",
            "email": "testamazonuser2@amazon.com",
            "import_vat_fee": 0,
            "order_amount": 239.98,
            "order_date": "2024-07-29T11:13:50",
            "order_no": "206-6784434-4444189_35JSK8627234_TEST2",
            "order_quantity": 2,
            "order_status": "SHIPPED",
            "payment_amount": 239.98,
            "payment_date": "2024-07-29T11:13:50",
            "payment_method": "Standard",
            "payment_status": "CAPTURE_SUCCESS",
            "reason_code": "R99",
            "reason_name": "R99-Marketplace Return",
            "ref_no": "5002",
            "refund_status": "PENDING",
            "return_comments": "",
            "return_date": "2024-08-01T11:57:45.280",
            "return_order_comments": [
                {
                    "_id": "52E25464-0298-4D28-8F24-22C89EFF0B54",
                    "comment": "Return Order is created!",
                    "created_by": "HEMI",
                    "created_date": "2024-08-01T11:57:45.280",
                    "rma_no": "206-6784434-4444189_35JSK8627234_TEST2R01",
                    "user_name": "HEMI"
                }
            ],
            "return_order_details": [
                {
                    "_id": "2BF57C95-35F2-4444-8B6D-A59B96AE1D73",
                    "a_quantity": 0,
                    "accepted_quantity": 0,
                    "b_quantity": 0,
                    "c_quantity": 0,
                    "cancel_quantity": 0,
                    "description": "Test Product trainer shoes",
                    "description_2": "Magnify Nitro Men's Running Shoes",
                    "mark_down": 0,
                    "order_line_no": "5903",
                    "order_no": "206-6784434-4444189_35JSK8627234_TEST2",
                    "order_quantity": 2,
                    "original_price": "209.99",
                    "price": 119.99,
                    "product_color": "",
                    "product_id": "4063699705256",
                    "product_ref1": "",
                    "product_ref2": "",
                    "product_ref3": "",
                    "product_size": "",
                    "product_uom": "",
                    "quantity": 1,
                    "reason_code": "R99",
                    "reason_name": "R99-Marketplace Return",
                    "rejected_quantity": 0,
                    "return_line_no": "5903",
                    "return_line_status": "RETURNED",
                    "rma_no": "206-6784434-4444189_35JSK8627234_TEST2R01",
                    "shipping_fee": 0
                }
            ],
            "return_order_status_details": [
                {
                    "_id": "525E980A-708B-4905-9FE0-BEC32ACEACA2",
                    "date": "2024-08-01T11:57:45.280",
                    "from_status": "",
                    "return_line_no": "5903",
                    "rma_no": "206-6784434-4444189_35JSK8627234_TEST2R01",
                    "to_status": "RETURNED"
                },
                {
                    "_id": "79AC1CD3-1643-4066-ACBF-534192ECDD23",
                    "date": "2024-08-01T11:57:45.280",
                    "from_status": "",
                    "return_line_no": "",
                    "rma_no": "206-6784434-4444189_35JSK8627234_TEST2R01",
                    "to_status": "RETURNED"
                }
            ],
            "return_quantity": 1,
            "return_status": "RETURNED",
            "rma_no": "206-6784434-4444189_35JSK8627234_TEST2R01",
            "s_address_1": "77, Maleha Road",
            "s_address_2": "AgainNoSuchStreet",
            "s_address_3": "",
            "s_city": "Al Seyouh",
            "s_country": "AE",
            "s_email_address": "testamazonuser2@amazon.com",
            "s_first_name": "FirstName2",
            "s_last_name": "LastName2",
            "s_phone": "087252342511",
            "s_state": "Sharjah Emirate",
            "s_suite": " ",
            "s_zip_code": "0000000",
            "sales_channel_id": "Amazon",
            "sales_channel_name": "Amazon",
            "sap_export": false,
            "seq_no": 10095,
            "shipped_date": "2024-08-01T11:54:48.547",
            "shipping_carrier": "AMAZON",
            "shipping_method": "prime",
            "shipping_status": "SHIPPED",
            "shipping_tracking_no": "35JSK8627215",
            "site_id": "UAE",
            "total_shipping_fee": 0,
            "updated_date": "2024-08-01T12:02:45.280"
        }
    }
}

Response Mapping :

<1.6> Claim Connector > Connector ID </v1.6> | New field! | | | | s_address_1 | | N/A | | | | | s_address_2 | | N/A | | | | | s_address_3 | | N/A | | | | | s_city | | N/A | | | | | s_country | | N/A | | | | | s_email_address | | N/A | | | | | s_first_name | | N/A | | | | | s_last_name | | N/A | | | | | s_phone | | N/A | | | | | s_state | | N/A | | | | | s_suite | | N/A | | | | | s_zip_code | | N/A | | | | | sales_channel_id | | N/A | | | | | sales_channel_name | | N/A | | | | | sap_export | | N/A | | | | | seq_no | | N/A | | | | | shipped_date | | N/A | | | | | shipping_carrier | | N/A | | | | | shipping_method | | N/A | | | | | shipping_status | | N/A | | | | | shipping_tracking_no | | N/A | | | | | site_id | | N/A | | | | | total_shipping_fee | | N/A | | | | | updated_date | | N/A | |

After successful response we want to store the information in the 3 fields mentioned in the mapping above. <v1.4> The total shipping cost refund for Amazon marketplaces should be picked up by the respective Order Refund Row → Amount with type = ‘Shipping’ and sum up all those values.

For example if we have an order with SKU111 x 1 qty and SKU222 x 4 qty with a total shipping cost of 10 and we need to send a return for 1x SKU111 and 2x SKU222, the Amazon ‘get Refunds’ should have created a refund with items + 2 shipping type order refund rows as well - SKU111 with amount 2 and SKU2222 with amount 4, resulting in a total shipping_fee of 6. </v1.4> Sample error response :

{
    "success": false,
    "message": "Not allow to create return order while order status is not SHIPPED or DELIVERED",
    "error_code": -1,
    "data": null
}

From the error response we want to store the message and create a record in Order Error with Type = Connector