All Collections
Advanced Help
Integrations
EvolutionX Order Processing - App Store Integration
EvolutionX Order Processing - App Store Integration

Send orders to your ERP Endpoint easily with auto-configured event webhook app integrated with our best-practice order handling included.

João Estima avatar
Written by João Estima
Updated over a week ago

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.

Did this answer your question?