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.