Custom Development / Puma UAE / OMSPro / OMSPro Create Cancellation

OMSPro Create Cancellation

Date Version Name Applied changes
25/07/2024 1.0 Hristiyan First Publish
26/09/2024 1.1 Milen changed order_line_no field
11/04/2024 1.2 Milen Added a trigger
17/12/2024 1.3 Milen include discount in the refund_amount

OMSPro also allows us to send cancellation for orders that have been cancelled for one reason or another. The purpose of the document is to give understanding on how the create cancel will work, what triggers etc.

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

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

Just like the create return, we want to have different triggers so we don’t want to use any abstraction. 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 cancellation are :

Product In Order > Fulfillment Status = ‘’

<v1.2> Orders > Acknowledgement Status <> ‘Rejected’ </v1.2>

Order Payment > Connector ID = ‘’

Orders > Refunded = Yes

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

Example request :

{
     "order_no": "204-0073114-4436789_351Y164R47123",
     "reason_code": "C99",
     "reason_name": "C99-Marketplace Cancel",
     "cancel_comments": "",
     "shipping_fee": 0,
     "cancel_date": "2023-07-30 15:19:23",
     "application_id": "Amazon",
     "cancel_order_details": [
       {
         "reason_code": "C99",
         "reason_name": "C99-Marketplace Cancel",
         "order_line_no": "5901",
         "product_id" : "4063697032521",
         "quantity": 1,
         "shipping_fee": 0
       }
     ],
     "created_by": "",
     "refund_transaction_id": "",
     "refund_amount": 139.98,
     "refund_authorization_no": "",
     "refund_date": "2023-07-30 15:19:23"
   }

Request mapping :

OMSPro Field Hemi Field Required Notes
order_no Orders > Marketplace Order ID Yes
reason_code Yes Hardcoded as “C99”
reason_name Yes Hardcoded as “C99-Marketplace Cancel”
cancel_comments N/A No
shipping_fee Orders > Shipping Service Cost No Note! If there is no shipping fee stored in Hemi, we need to send 0 as a value in this field
cancel_date Order Payment Details > Initially Created Date Yes Note! This is for Order Payment Details > Type = Refund
Needs to be in format “YYYY-MM-DD HH:MM:SS”
application_id Account > Marketplace Yes
cancel_order_details
reason_code Yes Hardcoded as “C99”
reason_name Yes Hardcoded as “C99-Marketplace Cancel”
order_line_no <v1.1>Product In Order > Item Order Line ID </v1.1> Yes
product_id Product In Order > EAN Yes
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.
shipping_fee Product In Order > Item Shipping Cost No Note! If there is no shipping fee stored in Hemi, we need to send 0 as a value in this field. We also need to calculate the shipping fee for the quantity that we are refunding as we keep the shipping fee for the whole line in Hemi.
created_by Yes Hardcoded as “HEMI”
refund_transaction_id N/A No
refund_amount <1.3>Order Payment > Total Amount + Orders > Discount Amount </v1.3> Yes
refund_authorization_no N/A No
refund_date Order Payment Details > Initially Created Date Yes Note! This is for Order Payment Details > Type = Refund
Needs to be in format “YYYY-MM-DD HH:MM:SS”

Example response :

{
    "success": true,
    "message": "Insert Hemi Cancel Order success",
    "error_code": 0,
    "data": {
        "cancel_order": {
            "application_id": "Amazon",
            "b_city": "Al Seyouh",
            "b_country": "AE",
            "b_first_name": "Firstname2",
            "b_last_name": "LastName2",
            "b_phone": "08725189611",
            "cancel_amount": 239.98,
            "cancel_comments": "",
            "cancel_date": "2023-08-02T15:19:23",
            "cancel_quantity": 2,
            "cancel_status": "CANCELLED",
            "capture_amount": 239.98,
            "capture_status": "CAPTURE_SUCCESS",
            "cma_no": "206-6784434-4444189_35JSK8627234_TEST3C01",
            "country_id": "AE",
            "created_by": "",
            "created_date": "2024-08-02T13:17:43.347",
            "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_TEST3",
            "order_quantity": 2,
            "order_status": "CANCELLED",
            "payment_amount": 239.98,
            "payment_date": "2024-07-29T11:13:50",
            "payment_method": "Standard",
            "payment_status": "CAPTURE_SUCCESS",
            "reason_code": "C99",
            "reason_name": "C99-Marketplace Cancel",
            "ref_no": "5002",
            "return_order_comments": [
                {
                    "_id": "F0202BA0-863F-4553-9FF2-4AF2F4323D0B",
                    "cma_no": "206-6784434-4444189_35JSK8627234_TEST3C01",
                    "comment": "Cancel Order is created!",
                    "created_by": "HEMI",
                    "created_date": "2024-08-02T13:17:43.347",
                    "user_name": "HEMI"
                }
            ],
            "return_order_details": [
                {
                    "_id": "AA2913B5-8A89-491C-A3D6-8BD76DB2C152",
                    "cancel_line_no": "5903",
                    "cancel_line_status": "CANCELLED",
                    "cma_no": "206-6784434-4444189_35JSK8627234_TEST3C01",
                    "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_TEST3",
                    "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": 2,
                    "reason_code": "C99",
                    "reason_name": "C99-Marketplace Cancel",
                    "return_quantity": 0,
                    "shipping_fee": 0
                }
            ],
            "return_order_status_details": [
                {
                    "_id": "8043F91D-B110-4D82-BD1B-442E3E731BD6",
                    "cancel_line_no": "5903",
                    "cma_no": "206-6784434-4444189_35JSK8627234_TEST3C01",
                    "date": "2024-08-02T13:17:43.347",
                    "from_status": "",
                    "to_status": "CANCELLED"
                },
                {
                    "_id": "9B17F106-ADCF-4A8C-BD84-7D3DD748C469",
                    "cancel_line_no": "",
                    "cma_no": "206-6784434-4444189_35JSK8627234_TEST3C01",
                    "date": "2024-08-02T13:17:43.347",
                    "from_status": "",
                    "to_status": "CANCELLED"
                }
            ],
            "return_quantity": 0,
            "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",
            "shipping_carrier": "AMAZON",
            "shipping_fee": 0,
            "shipping_method": "prime",
            "shipping_status": "NOT_SHIPPED",
            "shipping_tracking_no": "35JSK8627215",
            "site_id": "UAE",
            "total_shipping_fee": 0
        }
    }
}

Response mapping :

OMSPro Field Hemi Field Notes
success N/A
message N/A
error_code N/A
data N/A
cancel_order
application_id N/A
b_city N/A
b_country N/A
b_first_name N/A
b_last_name N/A
b_phone N/A
cancel_amount Orders > External Trans Payment Or Refund
cancel_comments N/A
cancel_date Orders > External Trans Time
cancel_quantity N/A
cancel_status N/A
capture_amount N/A
capture_status N/A
cma_no Order Payment > Connector ID New field!
country_id N/A
created_by N/A
created_date N/A
currency_id N/A
customer_name N/A
customer_type N/A
delivery_date N/A
email N/A
import_vat_fee N/A
order_amount N/A
order_date N/A
order_no N/A
order_quantity N/A
order_status N/A
payment_amount N/A
payment_date N/A
payment_method N/A
payment_status N/A
reason_code N/A
reason_name N/A
ref_no N/A
return_order_comments
_id N/A
cma_no N/A
comment N/A
created_by N/A
created_date N/A
user_name N/A
return_order_details
_id N/A
cancel_line_no N/A
cancel_line_status N/A
cma_no N/A
description N/A
description_2 N/A
mark_down N/A
order_line_no N/A
order_no N/A
order_quantity N/A
original_price N/A
price N/A
product_color N/A
product_id N/A
product_ref1 N/A
product_ref2 N/A
product_ref3 N/A
product_size N/A
product_uom N/A
quantity N/A
reason_code N/A
reason_name N/A
return_quantity N/A
shipping_fee N/A
return_order_status_details
_id N/A
cancel_line_no N/A
cma_no N/A
date N/A
from_status N/A
to_status N/A
_id N/A
cancel_line_no N/A
cma_no N/A
date N/A
from_status N/A
to_status N/A
return_quantity N/A
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
shipping_carrier N/A
shipping_fee N/A
shipping_method N/A
shipping_status N/A
shipping_tracking_no N/A
site_id N/A
total_shipping_fee N/A

After successful response we want to store the information in the 3 fields mentioned in the mapping above.

Example error response :

{
    "success": false,
    "message": "Not allow to create cancel order while order status is not NEW or PROCESSING",
    "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

We need to have in mind that we need to create a ‘cancel_order_details’ node per product and pick only the Order Refund Row → Type = ‘Item’ rows when creating those.

Is this article helpful?
0 0 0