BestBuy Get 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)
| Version | Date | Name | Applied changes |
|---|---|---|---|
| v1.0 | 29.05.2025 | Bogomil | First publish |
The specific for MIRAKL type of integrations in regards to orders flow is that we need to have a single cron which download the orders in Hemi the and also update the statuses and all related orders information to already stored orders.
| Sales Tax Group | Marketplace VAT Group | Internal VAT Group |
|---|---|---|
| Orders >Total Sales Tax | Orders > Total Marketplace VAT | Orders > Total VAT |
| Orders >Total Shipping Sales Tax | Orders > Total Shipping Marketplace VAT | Orders > Total Shipping VAT |
| Product In Order > Item Sales Tax Price | Product in Order > Marketplace VAT Item Price | Product In Order > Vat Item Price |
| Product In Order > Sales Tax Percent | Product in Order > Marketplace VAT Percent | Product In Order > Vat Percent |
| Product In Order > Item Shipping Cost Sales Tax | Product in Order > Marketplace VAT Item Shipping Cost | Product In Order > Vat Item Shipping Cost |
- Get New Orders
To download orders, we will use GET OR11 - List orders. The first run will check for new orders in the last 90 days and afterwards we need to get the date from last_date_run table and filter orders using parameter:
start_date: {last_date_run - 1 hours} date format: 2022-03-25T11:02:04Z
API Call: GET OR11 - List orders
Docs: https://help.mirakl.net/help/api-doc/seller/mmp.html#OR11
{
"orders": [
{
"acceptance_decision_date": "2024-03-25T13:22:10Z",
"can_cancel": false,
"can_shop_ship": false,
"channel": null,
"commercial_id": "252884385",
"created_date": "2024-03-23T17:47:54Z",
"currency_iso_code": "CAD",
"customer": {
"billing_address": {
"city": "Terrebonne",
"civility": "",
"company": "",
"company_2": null,
"country": "Canada",
"country_iso_code": null,
"firstname": "Vivian",
"lastname": "Gagnon",
"phone": "438-865-6322",
"phone_secondary": "",
"state": "QC",
"street_1": "212-1525 Rue Yves-Blais",
"street_2": "",
"zip_code": "J6V0J2"
},
"civility": "",
"customer_id": "834DF3F3-730A-47E2-9041-0D84FB123A62",
"firstname": "Vivian",
"lastname": "Gagnon",
"locale": "en_CA",
"shipping_address": {
"additional_info": "",
"city": "Terrebonne",
"civility": "",
"company": "",
"company_2": null,
"country": "Canada",
"country_iso_code": null,
"firstname": "Vivian",
"lastname": "Gagnon",
"phone": "438-865-6322",
"phone_secondary": "",
"state": "QC",
"street_1": "212-1525 Rue Yves-Blais",
"street_2": "",
"zip_code": "J6V0J2"
}
},
"customer_debited_date": "2024-03-25T13:32:29.430Z",
"customer_directly_pays_seller": false,
"customer_notification_email": "rlt24fnbe6a.f1d31jcq9@us.notification.mirakl.net",
"delivery_date": null,
"fulfillment": {
"center": {
"code": "DEFAULT"
}
},
"fully_refunded": false,
"has_customer_message": true,
"has_incident": false,
"has_invoice": false,
"last_updated_date": "2025-04-10T23:00:37Z",
"leadtime_to_ship": 9,
"order_additional_fields": [
],
"order_id": "252884385-A",
"order_lines": [
{
"can_refund": false,
"cancelations": [
],
"category_code": "CAT_1003",
"category_label": "Desktop Computers",
"commission_fee": 49.68,
"commission_rate_vat": 13.0000,
"commission_taxes": [
{
"amount": 6.46,
"code": "ON_HST",
"rate": 13.0000
}
],
"commission_vat": 6.46,
"created_date": "2024-03-23T17:47:54Z",
"debited_date": "2024-03-25T13:32:29Z",
"description": null,
"fees": [
],
"last_updated_date": "2025-04-10T23:00:37Z",
"offer_id": 123227006,
"offer_sku": "S517965",
"offer_state_code": "11",
"order_line_additional_fields": [
{
"code": "language",
"type": "STRING",
"value": "EN"
}
],
"order_line_id": "104612195",
"order_line_index": 1,
"order_line_state": "CLOSED",
"order_line_state_reason_code": "AUTO_CLOSED",
"order_line_state_reason_label": "Closed automatically",
"price": 584.99,
"price_additional_info": null,
"price_amount_breakdown": {
"parts": [
{
"amount": 584.99,
"commissionable": true,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"price_unit": 584.99,
"product_medias": [
{
"media_url": "/media/product/image/74b286af-5024-4694-90b7-929c7ec33b7d",
"mime_type": "PNG",
"type": "SMALL"
},
{
"media_url": "/media/product/image/aecc464c-6fbd-4caf-b0ea-c60de17848d3",
"mime_type": "PNG",
"type": "MEDIUM"
},
{
"media_url": "/media/product/image/be1884b8-8785-4b52-b80c-f86b5efc85dc",
"mime_type": "PNG",
"type": "LARGE"
}
],
"product_shop_sku": "I5-650-8G-1T",
"product_sku": "17540080",
"product_title": "ViprTech Entry Level Gaming PC Desktop Computer - Intel Core i5 3.40GHz, GeForce GTX 650, 8GB RAM, 1TB HDD, WiFi, RGB Lighting, Windows 10 Pro, Warranty, Black",
"promotions": [
],
"quantity": 1,
"received_date": "2024-04-10T19:15:34Z",
"refunds": [
],
"shipped_date": "2024-03-26T16:29:39Z",
"shipping_price": 36.00,
"shipping_price_additional_unit": null,
"shipping_price_amount_breakdown": {
"parts": [
{
"amount": 36.00,
"commissionable": true,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"shipping_price_unit": null,
"shipping_taxes": [
{
"amount": 0.00,
"amount_breakdown": {
"parts": [
{
"amount": 0.00,
"commissionable": false,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"code": "GST",
"tax_calculation_rule": "NONE"
},
{
"amount": 0.00,
"amount_breakdown": {
"parts": [
{
"amount": 0.00,
"commissionable": false,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"code": "QST",
"tax_calculation_rule": "NONE"
}
],
"taxes": [
{
"amount": 0.00,
"amount_breakdown": {
"parts": [
{
"amount": 0.00,
"commissionable": false,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"code": "GST",
"tax_calculation_rule": "NONE"
},
{
"amount": 0.00,
"amount_breakdown": {
"parts": [
{
"amount": 0.00,
"commissionable": false,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"code": "QST",
"tax_calculation_rule": "NONE"
}
],
"total_commission": 56.14,
"total_price": 620.99
},
{
"can_refund": false,
"cancelations": [
],
"category_code": "CAT_1003",
"category_label": "Desktop Computers",
"commission_fee": 57.44,
"commission_rate_vat": 13.0000,
"commission_taxes": [
{
"amount": 7.47,
"code": "ON_HST",
"rate": 13.0000
}
],
"commission_vat": 7.47,
"created_date": "2024-03-23T17:47:54Z",
"debited_date": "2024-03-25T13:32:29Z",
"description": null,
"fees": [
],
"last_updated_date": "2025-04-10T23:00:37Z",
"offer_id": 123227008,
"offer_sku": "S517967",
"offer_state_code": "11",
"order_line_additional_fields": [
{
"code": "language",
"type": "STRING",
"value": "EN"
}
],
"order_line_id": "104612196",
"order_line_index": 2,
"order_line_state": "CLOSED",
"order_line_state_reason_code": "AUTO_CLOSED",
"order_line_state_reason_label": "Closed automatically",
"price": 699.99,
"price_additional_info": null,
"price_amount_breakdown": {
"parts": [
{
"amount": 699.99,
"commissionable": true,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"price_unit": 699.99,
"product_medias": [
{
"media_url": "/media/product/image/16416dd7-de77-429b-904d-f83d132533d9",
"mime_type": "PNG",
"type": "MEDIUM"
},
{
"media_url": "/media/product/image/d93cb3e6-a1c0-470e-bcb8-4eb9ac4c8938",
"mime_type": "PNG",
"type": "SMALL"
},
{
"media_url": "/media/product/image/eb53f77f-78af-450c-b119-b5e014f654fe",
"mime_type": "PNG",
"type": "LARGE"
}
],
"product_shop_sku": "R5-VEGA-16G-128G-1T",
"product_sku": "17540078",
"product_title": "ViprTech Whiteout Gaming PC Desktop Computer - AMD Ryzen 5 5600G (12-LCore 4.4Ghz), AMD RX Vega 7 Graphics, 16GB DDR4, 128GB NVMe SSD, 1TB HDD, WiFi, RGB, Win 11, Warranty, White",
"promotions": [
],
"quantity": 1,
"received_date": "2024-04-10T19:15:34Z",
"refunds": [
],
"shipped_date": "2024-03-26T16:29:39Z",
"shipping_price": 18.00,
"shipping_price_additional_unit": null,
"shipping_price_amount_breakdown": {
"parts": [
{
"amount": 18.00,
"commissionable": true,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"shipping_price_unit": null,
"shipping_taxes": [
{
"amount": 0.00,
"amount_breakdown": {
"parts": [
{
"amount": 0.00,
"commissionable": false,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"code": "GST",
"tax_calculation_rule": "NONE"
},
{
"amount": 0.00,
"amount_breakdown": {
"parts": [
{
"amount": 0.00,
"commissionable": false,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"code": "QST",
"tax_calculation_rule": "NONE"
}
],
"taxes": [
{
"amount": 0.00,
"amount_breakdown": {
"parts": [
{
"amount": 0.00,
"commissionable": false,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"code": "GST",
"tax_calculation_rule": "NONE"
},
{
"amount": 0.00,
"amount_breakdown": {
"parts": [
{
"amount": 0.00,
"commissionable": false,
"debitable_from_customer": true,
"payable_to_shop": true
}
]
},
"code": "QST",
"tax_calculation_rule": "NONE"
}
],
"total_commission": 64.91,
"total_price": 717.99
}
],
"order_refunds": null,
"order_state": "CLOSED",
"order_state_reason_code": "AUTO_CLOSED",
"order_state_reason_label": "Closed automatically",
"order_tax_mode": "TAX_EXCLUDED",
"order_taxes": null,
"paymentType": "",
"payment_type": "",
"payment_workflow": "PAY_ON_ACCEPTANCE",
"price": 1284.98,
"promotions": {
"applied_promotions": [
],
"total_deduced_amount": 0
},
"quote_id": null,
"references": {
"order_reference_for_customer": "QC"
},
"shipping_carrier_code": "PRLA",
"shipping_carrier_standard_code": "purolator",
"shipping_company": "Purolator",
"shipping_deadline": "2024-04-01T06:59:59.999Z",
"shipping_price": 54.00,
"shipping_pudo_id": null,
"shipping_tracking": "FSY000001842",
"shipping_tracking_url": "http://www.purolator.com/purolator/ship-track/tracking-details.page?pin=FSY000001842",
"shipping_type_code": "M",
"shipping_type_label": "Ground Regular",
"shipping_type_standard_code": "CU_ADD-STD",
"shipping_zone_code": "QCLocal",
"shipping_zone_label": "Quebec Local",
"total_commission": 121.05,
"total_price": 1338.98
}
],
"total_count": 1
}
Mapping:
| MIRAKL Field | MIRAKL Notes | Hemi Field | Comment | |||||||
|---|---|---|---|---|---|---|---|---|---|---|
orders |
List of orders | |||||||||
acceptance_decision_date |
The date where the shop decided to accept or refuse the order. Null when the order was automatically refused or accepted. | |||||||||
| date-time | N/A | |||||||||
can_cancel |
Indicate if the order can be cancelled. | |||||||||
| boolean | N/A | |||||||||
can_shop_ship |
Indicates if shops can or cannot ship orders | |||||||||
| boolean | N/A | |||||||||
channel |
The channel of the commercial's order | |||||||||
code |
Channel code | N/A | ||||||||
label |
Channel label | N/A | ||||||||
commercial_id |
Commercial order's identifier | N/A | ||||||||
created_date |
Order's creation date | |||||||||
| 2022-08-25T11:06:29Z | Order > Order Created Time | |||||||||
currency_iso_code |
Shop's currency (ISO format) | |||||||||
| One of: AED, ARS, AUD, BGN, BHD, BRL, CAD, CHF, CLP, CNY, COP, CZK, DKK, EGP, EUR, GBP, HKD, HRK, HUF, ILS, INR, JOD, JPY, KES, KRW, KWD, LKR, MXN, MYR, NGN, NOK, NZD, OMR, PEN, PHP, PKR, PLN, RON, RSD, RUB, SAR, SEK, SGD, TND, TRY, THB, TWD, UAH, USD, UYU, VND, ZAR | Order > Order Currency | |||||||||
customer |
Information of the customer who ordered | |||||||||
billing_address |
Customer’s billing address | |||||||||
city |
Address city | Orders > Billing City Name | ||||||||
company |
Company of the person associated with the address | Orders >Billing Details > Company Name | ||||||||
country |
Address country | Orders > Billing Country Name | ||||||||
country_iso_code |
Orders > Billing Country Code | If we are receiving the ISO code we want to convert the 3 letter code into 2 letter code as per our standards. |
If the ISO code is missing we want to use and map the country and get the country code. |
| | | | firstname | | | | | First name of the person associated with the address | Orders > Billing Name | Concatenate with “lastname” with a single space between them |
| | | | lastname | | | | | Last name of the person associated with the address | Orders > Billing Name | Concatenate with “firstname” with a single space between them |
| | | | phone | | | | | Phone number of the person | Orders > Billing Phone | |
| | | | company | | | | | Company name | Orders > Company Name | billing_company_name under Billing Tab |
| | | | state | | | | | Address state | Orders > Billing State Province | |
| | | | street_1 | | | | | First information line of the address street | Orders > Billing Street 1 | |
| | | | street_2 | | | | | Second information line of the address street | Orders > Billing Street 2 | |
| | | | zip_code | | | | | Address zip code | Orders > Billing Postal Code | |
| | | civility | | | | | | Civility of the person associated with the address | N/A | |
| | | customer_id | | | | | | Customer's identifier | Order > Buyer User ID | |
| | | firstname | | | | | | Customer contact's firstname | N/A | |
| | | lastname | | | | | | Customer contact's lastname | N/A | |
| | | locale | | | | | | Customer contact's locale | N/A | |
| | | shipping_address | | | | | | Customer's Shipping address | | |
| | | | city | | | | | Address city | Orders > Shipping City | |
| | | | company | | | | | Company of the person associated with the address | | |
| | | | country | | | | | Address country | Orders > Shipping Country Name | |
| | | | country_iso_code | | | | | | Orders > Shipping Country Code | If we are receiving the ISO code we want to convert the 3 letter code into 2 letter code as per our standards.
If the ISO code is missing we want to use and map the country and get the country code. |
firstname |
First name of the person associated with the address | Orders > Shipping Buyer Name | Concatenate with “lastname” with a single space between them | lastname |
Last name of the person associated with the address | Orders > Shipping Buyer Name | Concatenate with “firstname” with a single space between them | phone |
Phone number of the person | Orders > Shipping Phone | company |
Company name | Orders > Company Name | billing_company_name under Shipping Tab | state |
Address state | Orders > Shipping State Province | street_1 |
First information line of the address street | Orders > Shipping Street 1 | street_2 |
Second information line of the address street | Orders > Shipping Street 2 | zip_code |
Address zip code | Orders > Shipping Postal Code | additional_info |
N/A | customer_debited_date |
The payment's date of the order by the customer | Orders > Order Paid Time | We will store UNIX format in Hemi but we need to display Human readable format into the UI | customer_directly_pays_seller |
customer_notification_email |
Anonymized customer email usable for notifications that do not expect an answer | Order > Buyer mail | delivery_date |
earliest |
latest |
Expected order delivery date | Orders > Delivery By Date | fulfillment |
N/A | center |
N/A | code |
N/A | fully_refunded |
Refund information | N/A | has_customer_message |
Indicate if the customer has sent a message related to this order | N/A | has_incident |
Indicate if order has incident on at least one order line | N/A | has_invoice |
Is an invoice available for this order | N/A | last_updated_date |
Order's last updated date | N/A | leadtime_to_ship |
Order's lead time to ship, in calendar days. Deprecated | N/A | order_additional_fields |
Order's additional fields | N/A | order_id |
Order's identifier | Order >Marketplace Order ID | order_lines |
Order lines | can_refund |
Indicate whether the order line full amount can be refunded | N/A | cancelations |
List of the cancellations | amount |
Refund's amount | Order Refund row > Amount | This applies for the row with type “item“ | amount_breakdown |
N/A | parts |
N/A | amount |
N/A | commissionable |
N/A | debitable_from_customer |
N/A | payable_to_shop |
N/A | commission_amount |
Refund's commission amount | N/A | commission_taxes |
N/A | commission_total_amount |
N/A | created_date |
Refund's creation date | Order Refund row > Payment Date | fees | N/A | id |
Refund's id | Order Payment > Transaction ID | When we are sending cancellation we group the ids into a single refund row but when we are downloading them every id will be a separate payment row type refund. We need to have the same logic also when we are downloading refund from MIRAKL and compare it to the transaction id. e.g: Transaction id = 2346-3563-1563 This means there are 3 refunds on the order and we store then in one payment row with 3 refund rows however the transaction id is constructed with all MIRAKL refund ids for the order “2346“, “3563“, “1563“ so when we are downloading the order we need to compare all refund ids. | quantity |
The quantity of products canceled (This quantity is informative only) | N/A | Based on the details added in the refund row. | reason_code |
Reason's code of the refund | Order Payment > Reason | Based on the ID we need to store the relevant reason | shipping_amount |
Refund's shipping amount | Order Refund Row > Amount | This applies for the row with type “shipping“ | shipping_amount_breakdown |
N/A | parts |
N/A | amount |
commissionable |
N/A | debitable_from_customer |
N/A | payable_to_shop |
N/A | shipping_taxes |
The taxes on the shipping price | amount |
Tax amount | Product In Order > Marketplace VAT Item Price | amount_breakdown |
N/A | parts |
N/A | amount |
N/A | commissionable |
N/A | debitable_from_customer |
N/A | payable_to_shop |
N/A | code |
N/A | taxes |
amount |
Product In Order >Marketplace VAT Item Shipping Cost **** | This amount is per single quantity so we just want to store it. | amount_breakdown |
N/A | parts |
N/A | amount |
N/A | commissionable |
N/A | debitable_from_customer |
N/A | payable_to_shop |
N/A | code |
N/A | category_code |
Category code of the product associated with the order line | N/A | category_label |
Category label of the product associated with the order line | N/A | commission_fee |
Order line's commission fee | Orders > Marketplace Fee | We need to sum all order line commissions and store them on order level | commission_rate_vat |
Order line's commission rate vat | Orders > Marketplace VAT | commission_taxes |
Commission taxes | N/A | amount |
N/A | code |
N/A | rate |
N/A | commission_vat |
created_date |
Order line's creation date | N/A | debited_date |
Order line's debited date | N/A | description |
Order line's description | N/A | last_updated_date |
Order line's last updated date | N/A | offer_id |
Associated offer's id | Product in Order > Channel Item ID | offer_sku |
Associated offer sku (this is the sku of the offer defined by the shop) | Product in Order > SKU | offer_state_code |
State of the offer associated with the order line | N/A | order_line_additional_fields |
List of additional fields | N/A | code |
N/A | type |
N/A | value |
N/A | order_line_id |
Order line's identifier | Product in Order > Item Order Line ID | order_line_index |
Order line's index in the order | N/A | order_line_state |
Order line's state STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED, INCIDENT_OPEN, REFUNDED, | Product in Order > Status | order_line_state_reason_code |
Reason's code of the order line's state | N/A | order_line_state_reason_label |
Reason's label of the order line's state | N/A | price |
Order line's price without shipping price | Product in Order > Item Price | Product in Order > Item Price / Product In Order > Quantity | price_additional_info |
Price's additional information of the offer | N/A | price_amount_breakdown |
price_unit |
Unit price for the offer associated with the order line | N/A | origin_unit_price |
N/A | product_medias |
Media URL | N/A | product_shop_sku |
Sku of the product associated with the order line | N/A | product_title |
Title of the product associated with the order line | Product in Order > Item Title | promotions |
List of promotions | N/A | quantity |
Product's quantity for the order line | Product in Order > Quantity | received_date |
Product's date of receipt | N/A | refunds |
List of the refunds | Order Payment with type 'Refund” if there are details in the refund node we will need to create a new refund row. | amount |
Refund's amount | Order Refund row > Amount | This applies for the row with type “Item“ | amount_breakdown |
N/A | parts |
N/A | amount |
N/A | commissionable |
N/A | debitable_from_customer |
N/A | payable_to_shop |
N/A | commission_amount |
Refund's commission amount | N/A | commission_tax_amount |
Refund's commission taxes | N/A | commission_taxes |
N/A | amount |
N/A | code |
N/A | commission_total_amount |
N/A | created_date |
Refund's creation date | Order Refund row > Payment Date | id |
Refund's id | Order Payment > Transaction ID | When we are sending refund we group the ids into a single payment row type refund but when we are downloading them every id will be a separate payment row type refund. We need to have the same logic also when we are downloading refund from MIRAKL and compare it to the transaction id. e.g: Transaction id = 2346-3563-1563 This means there are 3 refunds on the order and we store then in one payment row with 3 refund rows however the transaction id is constructed with all MIRAKL refund ids for the order “2346“, “3563“, “1563“ so when we are downloading the order we need to compare all refund ids. | quantity |
The quantity of products canceled (This quantity is informative only) | N/A | Based on the details added in the refund row. | reason_code |
Reason's code of the refund | Order Payment > Reason | Please refer to the list of reasons below | shipping_amount |
Refund's shipping amount | Order Refund Row > Amount | This applies for the row with type “shipping“ | shipping_taxes |
The taxes on the shipping price | amount |
Tax amount | Order Refund Row > Refund VAT | This applies for the row with type “shipping“ | code |
N/A | purchase_tax |
N/A | purchase_amount |
N/A | purchase_rate |
N/A | rate |
N/A | state |
Refund's state WAITING_REFUND, WAITING_REFUND_PAYMENT, REFUNDED | N/A | taxes |
amount |
Order Refund Row > Refund VAT | This applies for the row with type “item“ | code |
N/A | rate |
N/A | shipped_date |
Orders > Shipping Shipped Date | shipping_price |
Total price of the order line's shipping price | Product in Order > Item Shipping Cost | shipping_price_additional_unit | N/A | shipping_price_amount_breakdown | N/A | parts | amount | N/A | commissionable | N/A | payable_to_shop | N/A | debitable_from_customer | N/A | shipping_price_unit | N/A | shipping_taxes |
N/A | amount |
Product in Order > Marketplace VAT Item Shipping Cost | We sum all order item VAT Amounts and store them in Orders > Total Shipping Marketplace VAT | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
code |
N/A | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
purchase_tax |
N/A | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
purchase_amount |
N/A | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rate |
N/A | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
taxes |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amount |
Product in Order > Marketplace VAT Item Price |
The item tax is the total VAT so we will have to divide it based on the order item quantity
We want to multiply the vat based on the quantity for each order item then to sum all order item VAT Amounts and store them in Orders > Total Marketplace VAT |
| | | | origin_unit_amount | | | | | | N/A | |
| | | | code | | | | | | N/A | |
| | | | rate | | | | | | Product in Order > Marketplace VAT Percent | |
| | | | tax_calculation_rule | | | | | | N/A | |
| | | total_commission | | | | | | | N/A | |
| | | total_price | | | | | | | N/A | |
| | order_refunds | | | | | | | | | |
| | order_state | | | | | | | Order's state
STAGING, WAITING_ACCEPTANCE, WAITING_DEBIT, WAITING_DEBIT_PAYMENT, SHIPPING, SHIPPED, TO_COLLECT, RECEIVED, CLOSED, REFUSED, CANCELED, INCIDENT_OPEN, REFUNDED, | Order > Order Status | Note: You can find more detailed explanations & mapped MP statuses to Hemi statuses under “mapping” table. |
| | order_state_reason_code | | | | | | | Reason's code of the order state | N/A | |
| | order_state_reason_label | | | | | | | Reason's label of the order state | N/A | |
| | order_tax_mode | | | | | | | Please note: In case there is no tax, the prices will show the same amount in TAX_EXCLUDED and TAX_INCLUDED mode. The tax mode is only useful if taxes are specified in the order.
Possible values:
• TAX_EXCLUDED: the price fields (price, unit price, shipping price, cancellation amount, refund amount and order total prices) are expressed without tax (taxes should be added to these prices in order to get the full amount including taxes).
• TAX_INCLUDED: the price fields include the tax amount. | N/A | |
| | order_taxes | | | | | | | | N/A | |
| | paymentType | | | | | | | | N/A | |
| | payment_type | | | | | | | The payment's type used by the customer to pay this order | Order > Order Payment Method | |
| | payment_workflow | | | | | | | The payment workflow followed by the order
PAY_ON_ACCEPTANCE, PAY_ON_DELIVERY, PAY_ON_DUE_DATE, PAY_ON_SHIPMENT, NO_CUSTOMER_PAYMENT_CONFIRMATION | N/A | |
| | price | | | | | | | Order's price (sum of order line's price) | Order > Оrder Subtotal Аmount | This is the total amount without shipping cost |
| | promotions | | | | | | | | | |
| | | applied_promotions | | | | | | The promotions applied on this order | Order > Discount Type | |
| | | total_deduced_amount | | | | | | The total amount deduced on this order thanks to the promotions | Order > Discount | |
| | quote_id | | | | | | | Quote's id from which the order has been placed, or null if it was not from a quote | N/A | |
| | references | | | | | | | | N/A | |
| | | order_reference_for_customer | | | | | | | N/A | |
| | | order_reference_for_seller | | | | | | | N/A | |
| | shipping_carrier_code | | | | | | | Shipping carrier code (associated with the Shipping company label) | N/A | |
| | shipping_company | | | | | | | Shipping company | Orders > Carrier
AND
Order Shipment > Courier | |
| | shipping_deadline | | | | | | | Order's shipping deadline | N/A | |
| | shipping_price | | | | | | | Order's shipping price (sum of order line's shipping price) | Orders > Shipping Service Cost | |
| | shipping_pudo_id | | | | | | | PickUp DropOff (PUDO) point identifier | N/A | |
| | shipping_tracking | | | | | | | Shipping tracking | Orders> Shipping Track Number
AND
Order Shipment > Track Number | |
| | shipping_tracking_url | | | | | | | Shipping tracking url | Orders > Shipping Tracking URL
AND
Order Shipment > Tracking URL | |
| | shipping_type_code | | | | | | | Code of shipping's type | N/A | |
| | shipping_type_label | | | | | | | Label of shipping's type | Order > Shipping Service | |
| | shipping_zone_code | | | | | | | Code of shipping's zone | N/A | |
| | shipping_zone_label | | | | | | | Label of shipping's zone | N/A | |
| | total_commission | | | | | | | Order's total commission (sum of the order line's total commission) | Order> Total Fee | |
| | total_price | | | | | | | Total order's price (sum of the order's price and the order's shipping price). | Order > Оrder Тotal Аmount | |
Get Orders cron should download orders according to their marketplace status:
| MP Status | Hemi Status |
|---|---|
| STAGING | Pending |
| WAITING_ACCEPTANCE | Awaiting Acknowledge |
| WAITING_DEBIT | Pending |
| WAITING_DEBIT_PAYMENT | Pending |
| SHIPPING | Ready for Shipping |
| SHIPPED | Shipped |
| TO_COLLECT | Ready for Shipping |
| RECEIVED | Shipped |
| CLOSED | N/A (We do nothing just update MP Status). |
There is only one edge case and this is when we have Orders > Status = Ready For Shipping and for some reason we received Orders > Marketplace Status = Closed. In this case Closed will be last MIRAKL status and we wont know if the order is actually shipped or cancelled thus we have to check the if all order items are refunded to treat it as Orders > Status = Cancelled else Orders > Status = Shipped
The other case is when we download an order directly on Closed status then we have to check again the cancelations and refunds on the order items
In order to check if there is a cancellation or refund we can use the following nodes:
order_lines > cancelations & order_lines >refunds
There we can check for each order item what refunds or cancellations we have. |
| REFUSED | Cancelled |
| CANCELED | Cancelled |
| INCIDENT_OPEN | Operators and customers can open an incident on an order whenever the order status allows an incident to be opened:
• Shipping in Progress,
• Shipped,
• Received.
So we will need to make sure we update the Order Item Marketplace Status because the incidents are per order line.
If the order is not yet paid if the buyer opens an incident then the seller wont get paid.
• If we download an order for the first time with INCIDENT_OPEN status we ??? |
| REFUNDED | Cancelled |
Depend on which status we will receive the order we will need to follow different steps below is described the success flow however we might have cases where we are receiving order directly on Shipping status or even Shipped, thus we need to make sure depends on the status we are receiving the correct actions are performed. For example we are now incorporating the Order Acknowledge flag for MIRAKLs and if we download an order which is already accepted we need to update it as “Completed” otherwise by default each new order is downloaded with “Pending” statuses
If we have a new order which is already shipped we need to store all the relevant details like the order shipments, shipping info and the right statuses. If we have an order which is already stored in Hemi but is not shipped yet and we receive order updated we are updating the order with status shipped we still need to check if the order shipment is created, the shipping information is populated and the statuses are updated. If we have an order which is already stored in Hemi but is not shipped yet however we have added the order shipment and the shipping information and we receive order updated we are updating the order with status shipped without updating any other information in the shipping details
Success Flow:
- MP status = WAITING_ACCEPTANCE; Tool status = Pending and there wont be payment row yet;
- MP status = WAITING_DEBIT; Tool status = Pending and we create a payment row with status Pending;
- MP status = WAITING_DEBIT_PAYMENT; Tool status = Pending and we create a payment row with status Pending;
- MP status = SHIPPING; Tool status = Ready For Shipping and the payment row status is Completed;
- MP status = SHIPPED; Tool status = Shipped and the payment row status is Completed;
- MP status = RECEIVED; Tool status = Shipped and the payment row status is Completed;
| Hemi Status | Transition | Comment |
|---|---|---|
| Pending | From “Pending“ we can move to any other Hemi Status | Pending status is indicating that something need to happen on the order like clear debit, waiting acceptance etc. |
| Incomplete | From “Incomplete” we can move to | |
| ”Ready For Shipping”, “Shipped“, “Cancelled“ | Incomplete status is used when we have something missing on the order, like address, items etc. | |
| Ready For Shipping | From ”Ready For Shipping” we can move to “Shipped“ or “Cancelled“ only | Ready For Shipping indicates the order can be shipped successfully have all required information stored and payment cleared |
| Shipped | From “Shipped“ we can move to “Cancelled“ | Shipped indicating that the order has been dispatched. |
| Cancelled | “Cancelled“ is our final status. | Cancelled is the Hemi final status and we cannot revert back or move forward. |
Payment Reasons: For first time we have Return Reasons which is the actual Refund and Refund is the actual Cancel.
| reasons__code | reasons__label | reasons__type |
|---|---|---|
| 17 | Item returned - Damaged/defective/wrong | REFUND (Cancel) |
| 44 | Item returned - Buyer changed mind | REFUND (Cancel) |
| 18 | Item not received | REFUND (Cancel) |
| 15 | Out of stock | REFUND (Cancel) |
| 16 | Cancelled by client prior to shipping | REFUND (Cancel) |
| 45 | Shipping fee refund | REFUND (Cancel) |
| 35 | Tax refund | REFUND (Cancel) |
| 19 | Product price discount (customer keeps product) | REFUND (Cancel) |
| 55 | Pricing Error | REFUND (Cancel) |
| 41 | Operator request to cancel due to fraud suspicion | REFUND (Cancel) |
| 34 | Chargeback | REFUND (Cancel) |
| 14 | No response from shop | REFUND (Cancel) |
| 51 | Cannot ship due to PO Box address provided | REFUND (Cancel) |
| SYSTEM_REFUND_EDI | Refunded through EDI integration | REFUND (Cancel) |
| RETURN_BROKEN_ITEM | Broken item | RETURN (Refund) |
| RETURN_CHANGED_MIND | Changed my mind | RETURN(Refund) |
| RETURN_COUNTERFEIT_ITEM | Counterfeit item | RETURN(Refund) |
| RETURN_DAMAGED_PACKAGING | Damaged packaging | RETURN(Refund) |
| RETURN_DEFECTIVE_ITEM | Defective item | RETURN(Refund) |
| RETURN_DELIVERED_PRODUCT_DIFFERENT | Delivered product different from ordered product | RETURN(Refund) |
| RETURN_MISSING_ITEM | Missing item | RETURN(Refund) |
| RETURN_CM_DONT_WANT | Don''t want the product anymore | RETURN(Refund) |
| RETURN_CM_DONT_LIKE | Don''t like the product | RETURN(Refund) |
| RETURN_CM_QUALITY | Quality not as expected | RETURN(Refund) |
| RETURN_DPD_WRONG_SIZE | Wrong size | RETURN(Refund) |
| RETURN_DPD_WRONG_COLOR | Wrong color | RETURN(Refund) |
| RETURN_DEFECTIVE_ON_ARRIVAL | Defective on arrival | RETURN(Refund) |
| RETURN_PRODUCT_DOES_NOT_FIT | Product does not fit | RETURN(Refund) |
| RETURN_PDNT_TOO_BIG | Product too big | RETURN(Refund) |
| RETURN_PDNT_TOO_SMALL | Product too small | RETURN(Refund) |
| RETURN_OTHER | Other reason | RETURN(Refund) |