Delivery Estimate Rest API - V3.
- Rahul Kumar Sahukar
- Sharath Chandra Parashara
- Srinivas Aluri
80% of the shoppers make buying decisions based on ship cost and delivery speed during pre-purchase. Fenix Delivery Experience Platform enables retailers to offer a personalized delivery experience to their customers through the entire shopping journey from pre-purchase to post-purchase.
Pre-requisites before making API requests to Fenix Delivery Experience Platform
Carrier Information: The retailer should provide the current Carriers, the services opted for, carrier account information, or rate cards ( any specific). Kindly configure the carrier account information for fulfillment location-specific carrier accounts at a fulfillment location to get the most accurate rates. Global Credentials are always on priority.
Fulfillment locations: Configure all the USA Fulfillment locations, including DC/Store, in the Business Console
Lead Time (Time required to pick/pack/ship) for each fulfillment location after the order gets allocated
Shipment Pick-up times for each carrier or by carrier service.
Cut-off Time for the location
Holidays for the location
Inventory and Product: Various channels to share the inventory and product information with Fenix. Fenix's technical team helps you to choose the most appropriate method via SFTP/S3/Rest API.
Integration varies from platform to platform. In the case of Bigcommerce or Shopify Fenix team will install the private app in the checkout, then retailer-specific PDP and CART Rest API endpoints will be provided by the Fenix team.
Integration Architecture
Zipcode Detection API
Fenix recommends zipcode detection on the PDP page load. If an existing API detects the buyer's zipcode using the customer IP address, kindly pass the zipcode as input to the Fenix EDD API. If not, please use fenix recommended zipcode detection API
API : https://ipapi.co/json/?key=<APIKEY>
Note: The API key needs to be purchased from the above vendor.
Session Track id
Session Track ID should be generated on the home page or on the first page that the user loads and should be stored as part of the browser's local storage or cookies.
Session Track ID should be saved till the window or browser gets closed.
A Session Track ID should be regenerated when the bag/cart expires and added to the order as a line item.
Session Track ID must be persisted as part of the order. Kill the session ID saved as part of cookies and generate a new session ID.
Note: In the Case of shopify headless Integration. Fenix can't provide accurate reports without implementing the session track ID.
Implementation Guide: Session Track ID in Fenix Integration
Delivery Estimate Rest API
Request & Response formats
All the request and response formats are accepted in application/JSON
API | /fenixdelest/api/v3/deliveryestimates |
Method | POST |
Request Headers
|
|
Request body sample | {
"buyerZipCode": "string",
"sessionTrackId": "string",
"orderId": "string",
"cartId": "string",
"pageType": "string",
"monetaryValue": 0,
"responseFormat": "string",
"additionalProcessing": true,
"skus": [
{
"sku": "string",
"quantity": 0,
"category": "string",
"productName":"string",
"leadTime": 0,
"dimensions": {
"height": 0,
"length": 0,
"thickness": 0,
"units": "CM/IN",
"width": 0
},
"skuInventories": [
{
"locationId": "string",
"quantity": 0
}
],
"weight": {
"units": "LB",
"value": 0
}
}
],
"shippingInfo": {
"carrier": "string",
"trackId": "string",
"shippingDate": "2021-03-02T08:56:39-06:00",
"service": {
"name": "string",
"method": "string"
}
}
"buyerAddress": {
"name": "string",
"state": "string",
"zipcode": "string",
"address1": "string",
"address2": "string",
"city": "string",
"country": "string"
}
} |
Response body sample | {
"sessionId": null,
"responseTimeInMs": 0,
"eddResponses": [
{
"webId": "string",
"hours": "string",
"minutes": "string",
"response": "string",
"shippingCost": {
"amount": 0,
"currency": "USD"
},
"buyerZipCode": "string",
"deliveryZone": "string",
"shippingDateTime": "string",
"shippingMethodDesc": "string",
"internationalOrder": false,
"formattedDeliveryDate": "string",
"guaranteedDeliveryDate": "string",
"errorMessage": null,
"packages": [
{
"carrier": "string",
"wrapperType": "string",
"shipperLocId": "string",
"deliveryDate": "string",
"shippingDate": "string",
"shipperZipCode": "string",
"shippingMethod": "string",
"actualMethodDesc": "string",
"externalShippingMethod": null,
"contents": null
}
],
"shipCostBreakUp": {
"breakups": [
{
"name": "string",
"charges": {
"amount": 0,
"currency": "USD"
}
}
]
},
"orderRoutingInfo": [
{
"sku": "string",
"location_id": "string"
}
],
"shippingDeliveryDate": "string"
}
]
}
|
Request Body Attribute Definitions
Attribute | Description |
sessionTrackId mandatory | "sessionTrackId":"123123-2323-1231-23123"
|
orderId
| "orderId": "123123123"
|
cartId | "cartId": "123123123"
|
buyerZipCode mandatory | "buyerZipCode" : "95129"
|
pageType mandatory | "pageType": "cop"
E.g., Show fastest EDD on PDP and show all EDD options on COP. PDP - Product Detail Page CART - CART page/shopping Bag page COP - Check out Page MC - Mini Cart CA - Cart Abandonment OC - Order Confirmation SC - Shipping Confirmation Send Values as part of a delivery estimate request |
moneytoryValue mandatory | "monetaryValue": 50.0
|
responseFormat
| "responseFormat" : "json"
|
additionalProcessing | "additionalProcessing": true
|
skus mandatory |
"skus": [
{
"sku": "SKU-001",
"leadTime": 0,
"nonShip": false,
"quantity": 1,
"dimensions": {
"height": 3,
"length": 3,
"width": 0,
"thickness": 6,
"units": "CM/IN"
},
"skuInventories": [
{
"locationId": "Dc-01",
"quantity": 1
}
],
"weight": {
"units": "LB",
"value": 0
}
}
]
|
buyerAddress mandatory |
|
shippingInfo mandatory |
|
Response Attribute Definitions
Delivery Estimates response vary from the type of rule configured in the business console.
Attribute | Description |
eddResponses | This field contains a list of shipping estimates |
webId | "webId": "0194NCOS"
|
hours | "hours": "2" |
minutes | "minutes": "1"
|
carrier | "carrier": "fedex"
|
Response | "response": "Order within <span class=fenix-resp-span-time>2 hrs 1 mins</span><br>Get it by <span class=fenix-resp-span-date>Fri, May 21</span> with <span class=fenix-resp-span-shippingname>Federal Express </span>" E.g. Order within 2 hrs 1 mins Get it by Fri, May 21 with Federal Express ·
|
shippingCost | "shippingCost": {
|
shipperLocId | "shipperLocId": null,
|
buyerZipCode | "buyerZipCode": "10001"
|
shipperZipCode | "shipperZipCode": "10001",
|
shippingMethod | "shippingMethod": null,
|
shippingDateTime | "shippingDateTime": "19 May 2021, 19:00",
|
actualMethodDesc | "actualMethodDesc": "Fedex Ground" ,
|
shippingMethodCode | "shippingMethodCode": "Free Standard Delivery"
|
shippingMethodDesc | "shippingMethodDesc": "Free Standard Delivery"
|
ShippingDeliveryDate | "shippingDeliveryDate": "Wed, 26 May 2021" · The minimum delivery date that item will be delivered. In few cases this will be date range |
formattedDeliveryDate | "formattedDeliveryDate": "Wed, May 26" · The formatted delivery date to show it to end customer on various pages |
guaranteedDeliveryDate | "guaranteedDeliveryDate": "Wed, 26 May 2021" · The guaranteed delivery date provided by Fenix Commerce |
errorMessage | "errorMessage": null,
|
Packages | "packages": [{ "carrier": "DHL", "wrapperType": "DEFAULT", "shipperLocId": "manual", "shipperZipCode": "90058", "actualMethodDesc": "DHL SM Parcel Ground", "contents": { "0194NCOS": 100 } }]
The number of shippable packages information per service response basis
"SKU":quantity |
pickUpTimes
| "pickUpTimes": { · The configured pickup time of each shipping service method code "shipping service method code" : "Configured pickup time." |
pickFromStoreResponse | This field contains a list of pick up responses |
locationsWithIn | This field shows the distance (in miles) within which the fulfillment locations are considered |
storeInfos | This field contains a list of stores the customers can go and pick up their order |
locId | The location Id of the pick up store |
address | The address of the pick up store |
distance | The distance of the store to the buyer |
pickUpCost | This field lets the user know if there is any cost associated with the pick up |
mapsRoute | Shows the Google Maps url |
leadTimeForPickUp | This field tells the customers how soon they can pick the order after it is placed |
lineItems | The products that are included in this pick up |
workingHours | This field tells you the working hours of the store. |
The above request is a Fenix commerce master request with all the attributes the request body will change based on the retailer, such as inventory product feed integration.
PDP Integration Procedure
Precheck
Restrict the delivery estimates to only USA region and for only USA Customers
Don't make a delivery estimate call if the item is out of stock and other exceptional handling cases
Signed User
On page PDP page load, detect buyer Zipcode using the default address
If not available, Detect the buyer’s Zipcode using the IP address of the customer.
Recommend API to use to detect Zipcode: https://ipapi.com/
Provide an input field to enter five digits zip code if the buyer wishes to check the estimates for another location should be enabled only on PDP
Save the latest buyer Zipcode in browser cache to reuse in CART request as well. Clear the Zipcode from the browser cache as soon as the user closes the browser or tab
Guest User
Zipcode detection starts with https://ipapi.com/ , and the rest of the procedure is the same as above
Delivery Estimate Call
Call Fenix delivery estimate API after product images and variants get loaded in the PDP Page
Pass product price, SKU Id, Unique sessionTrackId, and buyer Zipcode to below API. It applies when the buyer selects a different variant on the PDP page as well
Page type should be PDP when the call is initiated from the PDP page
sessionTrackId should generate one per session and pass the same PDP and CART delivery estimate requests. sessionTrackId should live until customers sign out of the website or close the browser/tab
Sample PDP API Integration Details
Show fastest estimates at CART level
API | /fenixdelest/api/v3/deliveryestimates |
Request Headers
|
|
Request Body Sample:
| |
Response Body Sample
| |
CART and Checkout Page Integration Procedure
Precheck
Restrict the delivery estimates to only USA region and for only USA Customers
Don't make a delivery estimate call if the item is out of stock and other exceptional handling cases
CART API Details
Show fastest estimates at CART level
API | /fenixdelest/api/v3/deliveryestimates |
Request Headers
|
|
Request Body Sample:
| |
Response Body Sample
| |
Checkout Page Request and Response
API | /fenixdelest/api/v3/deliveryestimates |
Method | POST |
Request Headers
|
|
Request Body
Respone Body
Exception Use Cases :
Use Case | HTTP Status Code | Response Payload |
|---|---|---|
Invalid Inventory | 400 | { |
Invalid TenantId | 400 | { |
Invalid Zipcode | 400 | { |
Invalid Page Type | 400 | { |
Invalid Product Info | 400 | { |