The EvolutionX Order Processing App is a turnkey solution for sending web orders to an endpoint. It automatically includes all of the best practice recommendations for order processing and reduces the work of the receiving system to mapping the attributes to the receiving ERP.
Contents
Use Case
Using the App EvolutionX Order Processing App is similar to using the webhook events system to subscribe to the order created and order updated events except that the app provides all of our recommended order processing steps done for you. We've improved on the event driven webhook system by including the following best practice actions:
Prevent Duplicate Sending: In a scaleable system duplicate sending is possible but we prevent the same order being sent multiple times through a process that allows only one to succeed. This avoids multiple calls to your endpoint without the need for you to track the event ID.
Status update: The EvolutionX order status is set to "In Progress" when the order is successfully sent to the ERP Endpoint or set to "On Hold" if it fails.
Error email notification: If there is any HTTP error response or a timeout, EvolutionX sends an error notification email to the provided email address with details.
External order ID: If the field is set on the App Store and found in the response body, EvolutionX will map the ERP order id to the EvolutionX Order Seller Reference field. This makes it possible to use the ERP order ID to find the order on the EvolutionX API.
Timeline message: The EvolutionX order timeline is a history of events visible to staff using the store admin. The EvolutionX App will update it with a success event or the error message returned by the ERP.
Logging of Events and Requests: Each attempt to send the order is logged for 15 days using the Event and Request logging system for visibility in the EvolutionX Admin.
Reprocess an Order: Staff can reprocess an order that has failed by simply adjust the order "On Hold" status to "New Order" in the EvolutionX admin.
Order Processing
Once installed the app will process orders as follows:
Order events are processed and sent to the target endpoint when all the following are true:
Order is created or updated by any user except an API user AND
Order status is "New Order".
The response from the target endpoint is processed based on the HTTP status:
2xx HTTP Status will result in
EvolutionX Order status is set to "In Progress" and the Order Timeline is updated AND
ERP Order ID is saved in the EvolutionX Order Seller Reference field if found in the response (see install instructions below).
Timeout or other HTTP Status will result in
EvolutionX Order status is set to "On Hold" AND
If the app finds the error message in the response body (see install instructions below) it's used when updating the EvolutionX Order Timeline and sending the Email notification message to staff.
Staff can opt to resubmit the order for processing by changing the EvolutionX order status to "New Order".
Install from the App Store
Authentication Type: The authentication type allows multiple authentication processes, the standard key & token and the OAuth2.0 that uses the OAuth2.0 App Store.
Key & Token: Both fields are use in the header of the request. Key being the key name and the Token being the value of the key. With these fields we can have a safe and trusted connection with your endpoint (Webhook URL).
Example:
If you have a Bearer Token authentication then your key will be "Authorization" and the value "Bearer xxxxxxx".
Webhook URL: This is the endpoint that you would like the POST request to be sent to when the webhook fires.
Error notification e-mail Sender: SES E-mail address to be used as sender (FROM) for emails sent when an integration error occurs.
Error notification e-mail Receiver: E-mail address to receive (TO) information when an integration error occurs.
Wrapper for the request: (optional) Adds a key wrapper for the request (D365 requirement).
Order ID and Status Message and ShipTo ID: Both fields are paths to a variable on the response, every json key most be separated with a dot (".").
The Order ID will save as a seller reference, the message will be used on the order timeline and the ShipTo ID is used for the seller reference on the shipping address.
Note: There's an example in the Order Example.
Order Example
After an user finish the checkout process the webhook will be triggered. The follow example is the data we send after the described processe.
Request Example:
{
"event_id": "evt_30cf72c5bfc1e6b77fcc9de9178e2a0dfac4030db26970bd0aa2051dbc4fc0f9",
"event_type": "order.created",
"event_at": 1684492367,
"event_object_id": "1007090",
"event_object_type": "order",
"event_retry_count": 0,
"source_user_id": "1251506",
"source_user_type": "storefront",
"data": {
"event_data": {
"related_to": {
"cart": "1015259",
"customer": "1797466",
"user": "1251506"
}
},
"previous_attributes": [],
"object": {
"id": 1007090,
"customer": {
"id": 1797466,
"user_id": 1251506,
"customer_seller_reference": null,
"user_seller_reference": null,
"name": "Customer Name",
"company": "Company",
"account_number": "000001",
"phone": null,
"fax": null,
"cell": null,
"email": "000001@email.com",
"username": null,
"guest": false
},
"billing_address": {
"id": null,
"code": null,
"name": "Billing Name",
"company": "Company",
"phone": null,
"title": null,
"line_1": "Address",
"line_2": null,
"line_3": null,
"city": "Aveiro",
"state": "Aveiro",
"zip": "3750",
"country": "PT",
"note": null,
"seller_reference": null
},
"shipping_address": {
"id": 1680796,
"code": null,
"name": "Shipping Name",
"company": "Company",
"phone": null,
"title": null,
"line_1": "Address",
"line_2": null,
"line_3": null,
"city": "Aveiro",
"state": "Aveiro",
"zip": "3750",
"country": "PT",
"note": null,
"seller_reference": null
},
"branch": { "id": 253, "code": "MAIN" },
"currency": "USD",
"note": null,
"po_reference": null,
"alternative_po": null,
"shipping_amount": 0,
"subtotal": 58,
"subtotal_with_discount": 58,
"discount": 0,
"coupon_discount": 0,
"coupon_codes": [],
"tax": 0,
"total": 58,
"points_added": 0,
"points_redeemed": 0,
"status_id": 1,
"status": "New Order",
"seller_reference": null,
"shipping": {
"data": [
{
"id": 6917,
"title": "Free",
"label": "Free",
"supplier_id": null,
"items_count": 1,
"weight": 0,
"subtotal": 0,
"tax": 0,
"total": 0,
"tracking_code": null,
"tracking_link": null,
"created_at": 1684492367,
"updated_at": 1684492367
}
],
"items_count": 3,
"weight": 0,
"subtotal": 0,
"tax": 0,
"total": 0
},
"payment": {
"data": [
{
"id": 6825,
"method_id": 1606,
"title": "Braintree Credit Card",
"gateway": {
"name": "braintree",
"customer": "...",
"token": "...",
"authorization": "...",
"card_owner": null,
"card_type": "Visa",
"card_last4": "1111",
"card_exp_month": 4,
"card_exp_year": 2024
},
"surcharge": 0,
"subtotal": 58,
"total": 58,
"capture": true,
"status_id": 7,
"status": "Paid",
"created_at": 1684492367,
"updated_at": 1684492367
}
],
"total": 0
},
"items": {
"data": [
{
"line_id": 23218,
"id": 1003004,
"sku": "BR19907",
"title": "Berol Handwriting Black Pen S0378680",
"catalog_id": 1010,
"supplier_id": 1001,
"item_weight": 0.12,
"list_price": 13.91,
"item_price": 13.91,
"coupon_discount": 0,
"pack_size": 12,
"per_pack": 0,
"per_order_qty": 0,
"price_per": 0,
"item_price_raw": 13.91,
"pack_include": "12",
"uom": "12",
"taxable": true,
"item_tax": 0,
"item_tax_rate": 0,
"tax_class_id": null,
"quantity": 1,
"weight": 0.12,
"cost_center_id": null,
"cost_center_code": null,
"department_id": null,
"department_code": null,
"notes": null,
"subtotal": 13.91,
"savings": 0,
"tax": 0,
"total": 13.91,
"seller_reference": null,
"customise_id": "0",
"options": [],
"third_party_data": [],
"type_id": 0
},
{
...
}
],
"weight": 0,
"count": 3
},
"ip": "172.21.0.1",
"source": 0,
"is_pickup": false,
"api_managed": false,
"created_at": 1684492367,
"updated_at": 1684492367
}
}
}
You can add the "Seller Reference" or update the order timeline by returning a response to the webhook request. For this example to work you have to set values in Order ID and Status Message on the App Store.
Response Example:
{
"status": "success",
"message": "Response was a success.",
"object": {
"order_id": "O-42512",
"ship_to_id": "5441",
}
}On the App Store the Order ID Field will have the value of "object.order_id", the Status Message Field will be "message" and the ShipTo ID Field will be "object.ship_to_id".
Request Example with wrapper:
{
"object": {
"event_id": "evt_30cf72c5bfc1e6b77fcc9de9178e2a0dfac4030db26970bd0aa2051dbc4fc0f9",
"event_type": "order.created",
...
}
}On this example we put an "object" as a Wrapper for the request Field, adding a wrapper on the request. This is an optional feature that can be needed on d365 projects.