OMSPro Create Orders
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)
| Date | Version | Name | Applied changes |
|---|---|---|---|
| 25/07/2024 | 1.0 | Milen | First Publish |
| 13/09/2024 | 1.1 | Milen | Added fields/hardcoded values |
| 18/09/2024 | 1.2 | Milen | Hardcoded field change |
| 26/09/2024 | 1.3 | Milen | Allow sending ‘Awaiting Acknowledgement’ orders + mapping changes |
| 17/12/2024 | 1.4 | Milen | add discounts to product/total amount |
| 25/12/2024 | 1.5 | Milen | Hardcode discounts to be ‘0’ |
| 22/04/2025 | 1.6 | Milen | Trendyol Changes |
| 20/06/2025 | 1.7 | Milen | Hardcoding b_phone for trendyol |
The purpose of this document is to detail the custom API call that we will be using to create orders in Puma’s OMSPro order management system.
API Live Endpoint: POST https://pumaglobal.omspro.com:8443/HEMI/SalesOrder
API Test Endpoint: POST https://puma-test.openoms.net:8084/HEMI/SalesOrder
We want to be picking orders on :
Orders > Status = ‘Ready for Shipping’, <v1.3> ‘Awaiting Acknowledgement’ </v1.3> AND ‘Shipped’
Orders > Connector Order ID = ‘’
Orders > Connector Error = ‘’
Product On Order > Connector Exported = No
Product On Order > Connector ID = ‘’
Example payload:
{
"order_no": "240617956MJB36",
"order_date": "2024-06-17 17:13:50",
"order_status": "",
"doc_id": "",
"seq_no": 0,
"site_id": "",
"sales_channel_id": "Amazon",
"sales_channel_name": "Amazon",
"country_id": "UAE",
"application_id": "",
"ref_no": "240617956MJB36",
"customer_name": "MXXXXXXn",
"customer_id": "",
"customer_type": "Registered",
"email": "",
"currency_id": "AED",
"order_amount": 0,
"order_quantity": 0,
"created_date": "",
"created_by": "Hemi",
"updated_date": "",
"updated_by": "",
"payment_transaction_id": "",
"payment_gateway": "",
"payment_type": "",
"payment_status": "CAPTURE_SUCCESS",
"payment_method": "Noon",
"payment_date": "",
"payment_amount": 1822,
"capture_transaction_id": "",
"capture_authorization_no": "",
"capture_amount": 1822,
"capture_date": "",
"capture_status": "",
"refund_transaction_id": "",
"refund_authorization_no": "",
"refund_status": "",
"refund_date": "",
"refund_amount": 0,
"reverse_transaction_id": "",
"reverse_authorization_no": "",
"reverse_amount": 0,
"reverse_date": "",
"reverse_status": "",
"shipping_fee": 0,
"shipping_tracking_no": "SPEPH047515487696",
"shipping_carrier": "XXXXXXXXXX",
"shipping_method": "XXXXXXXXX",
"shipping_status": "NOT_SHIPPED",
"shipping_label_url": "",
"b_first_name": "Mn",
"b_last_name": "",
"b_address_1": "",
"b_address_2": "",
"b_address_3": "",
"b_city": "Laguna",
"b_zip_code": "4009",
"b_state": "South Luzon",
"b_country": "AE",
"b_suite": " ",
"b_phone": "******11",
"b_email_address": "xxx@x.com",
"s_first_name": "Mn",
"s_last_name": "",
"s_address_1": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"s_address_2": "",
"s_address_3": "",
"s_city": "xxxxxx",
"s_zip_code": "xxxxxx",
"s_state": "xxxxxxxxxxx",
"s_country": "AE",
"s_suite": " ",
"s_phone": "******11",
"s_email_address": "xxx@x.com",
"invoice_no": "XXXXXXXXXX",
"delivery_date": " ",
"discount_amount": 0,
"total_weight": 0,
"total_volume": 0,
"total_packages": 0,
"shipping_package_no": "",
"shipping_package_type": "",
"shipping_package_length": "",
"shipping_package_width": "",
"shipping_package_height": "",
"shipping_package_weight": "",
"shipping_package_value": "",
"shipping_instruction": "",
"sap_export": false,
"sales_order_details": [
{
"order_no": "240617956MJB36",
"order_line_no": "48712423194-1",
"order_line_status": "NEW",
"product_id": "4063699708806",
"product_size": "UK:6",
"product_color": "PUMA Black-Rose Gold",
"product_uom": "",
"product_ref1": "",
"product_ref2": "GED2429595-16",
"product_ref3": "",
"description": "PUMA Unisex Aviator Running Shoes",
"quantity": 1,
"price": 4500,
"line_discount_amount": 2678,
"line_discount_amount_platform": 0,
"original_price": 149,
"shipping_fee": 0,
"cancel_quantity": 0,
"return_quantity": 0,
"sub_total": 1822,
"header_discount": 0,
"created_by": "",
"updated_by": ""
}
],
"sales_order_comments": null,
"discount_details": null
}
Mapping :
Please note N/A means we exclude the field from the payload. We also want to exclude any field from the payload instead of sending it empty (for example if we have mapping for it but the field is empty in Hemi).
| OMSPro field | Hemi field | Integration required | Notes | ||
|---|---|---|---|---|---|
order_no |
Orders > Marketplace Order Id |
Yes | |||
order_date |
Orders > Order Created Time |
Yes | Needs to be in format ‘YYYY-MM-DD HH:MM:SS’ | ||
order_status |
Orders > Tool Status |
Yes | <v1.3> We need to map ‘dispatched’ status to ‘SHIPPED’ and ‘waiting_for_delivery’ and ‘awaiting_acknowledgement’ statuses to ‘NEW’ </v1.3> | ||
doc_id |
N/A | No | |||
seq_no |
No | Hardcoded as ‘0’ | |||
site_id |
N/A | No | |||
sales_channel_id |
Account OMSPro > Sales Channel |
Yes | |||
sales_channel_name |
Account OMSPro > Sales Channel |
Yes | |||
country_id |
Orders > Shipping Country Code |
Yes | We need to have mapping : |
If we have Shipping Country Code = AE , we send “UAE”
If we have Shipping Country Code = SA , we send “KSA”
If we have any other code, we send it as it is. | |
| application_id | | | No | Hardcoded as ‘HEMI’ | |
| ref_no | | Orders > ID | Yes | | |
| customer_code | | Orders > Buyer Mai | Yes | | |
| customer_name | | Orders > Shipping Buyer Name | Yes | | |
| customer_id | | N/A | No | | |
| customer_type | | | Yes | Hardcoded as ‘Registered’ | |
| email | | | Yes | | |
| currency_id | | Orders > Order Currency | Yes | | |
| order_amount | | <v1.4>Orders > Order Total Amount + Orders > Discount Value </v1.4> | No | | |
| order_quantity | | N/A | No | | |
| created_date | | N/A | No | | |
| created_by | | N/A | No | | |
| updated_date | | N/A | No | | |
| updated_by | | N/A | No | | |
| payment_transaction_id | | N/A | No | | |
| payment_gateway | | N/A | No | | |
| payment_type | | N/A | No | | |
| payment_status | | | Yes | Hardcoded as ‘CAPTURE_SUCCESS’ | |
| payment_method | | Account > Marketplace | Yes | Example : Amazon, Noon | |
| payment_amount | | <v1.4>Orders > Order Total Amount + Orders > Discount Value </v1.4> | Yes | | |
| capture_transaction_id | | N/A | No | | |
| capture_authorization_no | | N/A | No | | |
| capture_amount | | <v1.4>Orders > Order Total Amount + Orders > Discount Value </v1.4> | No | | |
| capture_date | | N/A | No | | |
| capture_status | | N/A | No | | |
| refund_transaction_id | | N/A | No | | |
| refund_authorization_no | | N/A | No | | |
| refund_status | | N/A | No | | |
| refund_date | | N/A | No | | |
| refund_amount | | N/A | No | | |
| reverse_transaction_id | | N/A | No | | |
| reverse_authorization_no | | N/A | No | | |
| reverse_status | | N/A | No | | |
| reverse_date | | N/A | No | | |
| reverse_amount | | N/A | No | | |
| shipping_fee | | Orders > Shipping Service Cost | No | | |
| shipping_tracking_no | | Orders Amazon > Smart Connect Shipment ID
OR
Orders > Shipping Track Num | Yes | We need to create a logic :
for disitinct marketplace = Amazon we send
Orders Amazon > Smart Connect Shipment ID
for distinct marketplace Noon we send Orders > Shipping Track Num
<v1.6> for distinct marketplace Trendyol we send Orders > ID </v1.6> | |
| shipping_carrier | | Orders > Shipping Carrier | Yes | Hardcoded as ‘AMAZON’ for distinct marketplace = Amazon
OR Orders > Shipping Carrier for distinct marketplace = Noon
<v1.6> Hardcoed as ‘Trendyol’ for marketplace Trendyol </v1.6> | |
| shipping_method | | | Yes | Hardcoded as ‘prime’ for marketplace Amazon and ‘FBN’ for marketplace Noon
<v1.6> Hardcoed as ‘Standard’ for marketplace Trendyol </v1.6> | |
| shipping_status | | Orders > Order Status | No | <v1.3> We need to map and send : ‘NOT_SHIPPED’ for Order Status = waiting_for_delivery OR awaiting_acknowledgement </v1.3>
OR ‘SHIPPED’ for Order Status = dispatched | |
| shipping_label_url | | N/A | No | | |
| b_first_name | | Orders > Billing Name | No | We need only the first name and we get everything before the first space character
Trim leading white spaces if any
We want to create a logic if billing info is not present, we take it from shipping. | |
| b_last_name | | Orders > Billing Name | No | We get everything after the first space character
Trim leading white spaces if any
We want to create a logic if billing info is not present, we take it from shipping. | |
| b_address_1 | | Orders > Billing Street 1 | No | We want to create a logic if billing info is not present, we take it from shipping. | |
| b_address_2 | | Orders > Billing Street 2 | No | We want to create a logic if billing info is not present, we take it from shipping. | |
| b_address_3 | | N/A | No | | |
| b_city | | Orders > Billing City | No | We want to create a logic if billing info is not present, we take it from shipping. | |
| b_zip_code | | Orders > Billing Postal Code | No | We want to create a logic if billing info is not present, we take it from shipping. | |
| b_state | | Orders > Billing State Province | No | We want to create a logic if billing info is not present, we take it from shipping. | |
| b_country | | Orders > Billing Country Code | No | We want to create a logic if billing info is not present, we take it from shipping. | |
| b_suite | | N/A | No | | |
| b_phone | | Orders > Billing Phone | No | We want to create a logic if billing info is not present, we take it from shipping.
<v1.7> For Trendyol, we hardcode +971 (50) 123-45-67 if the field is empty </v1.7> | |
| b_email_address | | Orders > Buyer Mail | No | | |
| s_first_name | | Orders > Shipping Buyer Name | No | We need only the first name and we get everything before the first space character
Trim leading white spaces if any | |
| s_last_name | | Orders > Shipping Buyer Name | Yes | We get everything after the first space character
Trim leading white spaces if any | |
| s_address_1 | | Orders > Shipping Street 1 | Yes | | |
| s_address_2 | | Orders > Shipping Street 2 | No | | |
| s_address_3 | | N/A | No | | |
| s_city | | Orders > Shipping City | Yes | | |
| s_zip_code | | Orders > Shipping Postal Code | No | <v1.1> No longer mandatory field </v1.1> | |
| s_state | | Orders > Shipping State Province | No | <v1.1> No longer mandatory field </v1.1> | |
| s_country | | Orders > Shipping Country Code | Yes | | |
| s_suite | | N/A | No | | |
| s_phone | | Orders > Shipping Phone | Yes | <v1.6> For marketplace Trendyol, if the field is empty, we hardcode +971 (50) 123-45-67 </v1.6> | |
| s_email_address | | Orders > Buyer Mail | Yes | | |
| invoice_no | | N/A | No | | |
| delivery_date | | Orders > Ship by Date
OR
Orders > Delivery by Date | Yes | Needs to be in format ‘YYYY-MM-DD HH:MM:SS’
<v1.6> Send Orders > Delivery by Date for marketplace Trendyol, for this MP don’t look at Ship by Date</v1.6> | |
| discount_amount | | N/A | No | <v1.5> Hardcoded as ‘0’ </v1.5> | |
| total_weight | | N/A | No | | |
| total_volume | | N/A | No | | |
| total_packages | | N/A | No | | |
| shipping_package_no | | N/A | No | | |
| shipping_package_type | | N/A | No | | |
| shipping_package_length | | N/A | No | | |
| shipping_package_width | | N/A | No | | |
| shipping_package_height | | N/A | No | | |
| shipping_package_weight | | N/A | No | | |
| shipping_package_value | | N/A | No | | |
| shipping_instruction | | N/A | No | | |
| sap_export | | N/A | No | | |
| sales_order_details | | | Yes | | |
| | order_no | Orders > Marketplace Order ID | Yes | | |
| | order_line_no | Product In Order > Item Order Line ID | Yes | <v1.3> switched fields with product_ref3 </v1.3> | |
| | order_line_status | Orders > Order Status | Yes | <v1.3><v1.2>We need to map and send : ‘NEW’ for Order Status = waiting_for_delivery OR awaiting_acknowledgement </v1.2></v1.3>
OR ‘SHIPPED’ for Order Status = dispatched | |
| | product_id | Product In Order > EAN | Yes | | |
| | product_size | N/A | No | | |
| | product_color | N/A | No | | |
| | product_uom | N/A | No | | |
| | product_ref1 | N/A | No | | |
| | product_ref2 | N/A | No | | |
| | product_ref3 | Product In Order > ID | No | <v1.3> switched fields with order_line_no </v1.3> | |
| | desctiption | Product In Order > Item Title | Yes | | |
| | quantity | Product In Order > Quantity | Yes | | |
| | price | <v1.4>Product In Order > Item Price + Product In Order > Discount Amount</v1.4V | Yes | | |
| | line_discount_amount | N/A | No | <v1.5> Hardcoded as ‘0’ </v1.5> | |
| | line_discount_amount_platform | N/A | No | | |
| | original_price | Product In Order > Item Original Price | Yes | | |
| | shipping_fee | Product In Order > Item Shipping Cost | No | | |
| | cancel_quantity | N/A | No | | |
| | return_quantity | N/A | No | | |
| | sub_total | | Yes | Needs to be calculated.
<v1.4>(Order Item > Item Price + Product In Order > Discount Amount)*Order Item > Item Quantity </v1.4> | |
| | header_discount | N/A | No | | |
| | created_by | N/A | No | | |
| | updated_by | N/A | No | | |
| sales_order_comments | | N/A | No | | |
| discount_details | | N/A | No | | |
Example successful response :
{
"success": true,
"message": "Insert Hemi Sales Order success",
"error_code": 0,
"data": {
"cancel_order": {},
"sales_order": {
"b_city": "Al Seyouh",
"b_country": "AE",
"b_first_name": "Firstname2",
"b_last_name": "LastName2",
"b_phone": "08725189611",
"cancel_quantity": 0,
"capture_amount": 239.98,
"capture_status": "CAPTURE_SUCCESS",
"country_id": "AE",
"created_by": "HEMI",
"created_date": "2024-07-30T18:38:46.180",
"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,
"line_discount_amount": 0,
"order_amount": 239.98,
"order_date": "2024-07-29T11:13:50",
"order_no": "206-6784434-4444189_35JSK8627234_TEST2",
"order_quantity": 2,
"order_status": "NEW",
"payment_amount": 239.98,
"payment_date": "2024-07-29T11:13:50",
"payment_method": "Standard",
"payment_status": "CAPTURE_SUCCESS",
"ref_no": "5002",
"refund_amount": 0,
"return_quantity": 0,
"reverse_amount": 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",
"sales_order_details": [
{
"_id": "E89AA91B-6322-42BE-9EB6-CA0189365FE8",
"cancel_quantity": 0,
"description": "Test Product trainer shoes",
"description_2": "Magnify Nitro Men's Running Shoes",
"mark_down": 0,
"order_line_no": "5903",
"order_line_status": "NEW",
"order_no": "206-6784434-4444189_35JSK8627234_TEST2",
"original_price": "209.99",
"price": 119.99,
"product_color": "",
"product_id": "4063699705256",
"product_ref1": "",
"product_ref2": "",
"product_ref3": "",
"product_size": "",
"product_uom": "",
"quantity": 2,
"return_quantity": 0,
"shipped_quantity": 0,
"shipping_fee": 0,
"sub_total": 239.98
}
],
"sales_order_status": [
{
"_id": "0777A9C9-A831-439F-8572-4E0DC62F20C5",
"date": "2024-07-30T18:38:46.177",
"from_status": "",
"order_line_no": "",
"order_no": "206-6784434-4444189_35JSK8627234_TEST2",
"to_status": "NEW"
},
{
"_id": "3C4F0D1A-6B6D-4262-A271-BB1028CFD208",
"date": "2024-07-30T18:38:46.177",
"from_status": "",
"order_line_no": "5903",
"order_no": "206-6784434-4444189_35JSK8627234_TEST2",
"to_status": "NEW"
}
],
"sap_export": false,
"seq_no": 40342,
"shipping_carrier": "AMAZON",
"shipping_fee": 0,
"shipping_method": "prime",
"shipping_status": "NOT_SHIPPED",
"shipping_tracking_no": "35JSK8627215",
"site_id": "UAE",
"total_shipping_fee": 0,
"updated_by": "HEMI",
"updated_date": "2024-07-30T18:38:46.180"
}
}
}Mapping : We dont want to map anything apart from data > sales_order > ref_no to be stored into Orders > Connector Order ID AND Product In Order > Connecter ID (note that this would be our internal Hemi ID as we would have passed it when creating the order. We want to store it as the communication with OMSpro will be happening based on our Hemi internal order ID)
After successful order creation we will need to update also Product In Order > Connector Exported = Yes
Example error response :
{
"success": false,
"message": "Decode ERROR - invalid character 'q' after object key:value pair",
"error_code": 0,
"data": null
}Error response Mapping:
| OMSPro Field | Hemi Field | Notes |
|---|---|---|
success |
We should look for false value of this field |
|
message |
Orders > Connector Error |
|
error_code |
N/A | |
data |
N/A |