In House Orders APIs Integration

Suggest Edits

DigitalGenius (DG) platform can easily integrate with your in house APIs to fetch order information and/or perform actions such as cancelling an order, issuing a refund / replacement, etc.

Overall Architecture Overview

Let us first cover how DG platform works behind the scenes. Any incoming messages from a user are routed to one of the DG Flows which then drives the conversations with the user.

Flows and Actions

A Flow is a sequence of actions with conditions, where some conditions are rules based and some are driven by the AI. Outputs of one action can be used as inputs into another action, or as conditions for branching in the Flow. Here is a sample Flow that uses AI action to determine what user's message is about and then branches based on the detected intent.

Data Flow

Now let's zoom into what happens in this flow when the AI detects the WISMO (Where is My Order) intent. As you can see the next step is a Find Order Sub-Flow (Sub-Flows are Flows inside other Flows).

Inside that subflow we would call your APIs to look for customer's order details, process the API response and then return the order information in a business friendly fields such as Order Status, Order Date, Tracking Number so that a non technical user can use those fields in the rest of the Flow for either branching or for passing that as inputs into other actions.

Find Order Sub-Flow

Here is an example of how the Find Order sub-flow might look like.

  • As you can see the first action will be making an API call to your API to fetch a list of orders for a given customer's email address.
  • Then there is a branch on successful response from the API, and then an action to extract some data from the API response JSON body.
  • That data is then mapped to business user friendly fields such as Order Status, Tracking Number, Order Date, Region, etc.
  • This flow could have multiple actions calling your APIs, processing the responses, and doing various business logic, filtering of orders, etc.

Integration Model - DigitalGenius consumes your APIs

As the above example illustrates, you don't need to expose the API endpoints in any specific format, you also don't need to make any API calls to our webhooks, instead DG will simply consume the API endpoints you already have available. DG will call your existing APIs and then process the response from your API whatever format you use.

We easily integrate with REST, SOAP, GraphQL endpoints and the data returned can be in JSON, XML, or other formats. The only technical requirement we have is for your API to be publicly accessible over internet network, however you can whitelist the IPs from which DG will be making calls to your API.

Authentication

We would expect some authentication layer to access your API. A common approach is to have at least a Basic token; however we support refresh tokens, OAuth2, and any other security protocol you might use. For advanced security frameworks we can handle the authentication in the code of a custom DG action that would be calling your APIs so there is no restriction on what sort of authentication we can support.

In summary DG does not require you to use one or another authentication method, DG can work with whatever you already have available or prefer to implement.

Common Order Data Points and Actions to Expose

Generally speaking the data you would need to expose highly depends on your business process and how you handle orders, refunds, etc. So it's more important to align with the customer service team to make sure that the API exposes all the data necessary to successfully resolve customer service issues for a given use case. However below we have collected a rich set of data points that can give you guidance on what's usually useful to have exposed.

For WISMO, Cancel/Change Order, Change Delivery Address, Return Label and other intents where we will search for an order, we often see the following data to be useful:

  • Order Number
  • Customer Email
  • Customer Name
  • Shipping Address
  • Order Creation Date
  • Order Amount
  • Order Status (per order line if shipped separately)
  • Delivery Carrier Name
  • Tracking Number (per order line/shipment if order items can be shipped separately)
  • List of order items/lines (including name, SKU, quantity, product image URL, if available)
  • Return Tracking number (if available)
  • Return/Refund Warehouse Status

Some more advanced data might include:

  • Shipping date (if available)
  • Expected shipping date (if available)
  • Expected delivery date (if available)
  • Order type (if there are multiple)

General Requirements:

  • We should be able to search for orders by order number and by email
  • If necessary you can whitelist IP addresses from where DigitalGenius will be making API calls:
    US: 35.167.19.246
    EU: 18.197.240.87
    For testing and implementation purposes, you will need also to whitelist our test API:
    109.70.151.103

📘

DigitalGenius already has many e-commerce integrations pre-built

DG already directly connects to the carriers (Fedex, UPS, DHL, etc) in order to get detailed tracking history, generate return labels and launch investigations. Also we have integrations with e-commerce platforms such as Shopify, Salesforce CommerceCloud, Magento, as well payment systems such as Adyen and Stripe. Thus you don't need to develop APIs to cover use cases where we can already use one of the pre-built integrations.

Updated 5 months ago