Delivery Estimate Rest API-V2

80% of the shoppers make buying decisions based on ship cost and delivery speed during pre-purchase. Fenix Delivery Experience Platform enables the 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: Retailer should provide the current Carriers, the services opted, carrier account information, or rate cards ( any specific). In the case of fulfillment location-specific carrier accounts, kindly configure the carrier account information 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
1. Lead Time (Time required to pick/pack/ship) for each fulfillment location after the order gets allocated
2. Shipment Pick-up times for each carrier or by carrier service.
3. Cut-off Time for the location
4. Holidays for the location
Inventory and Product: Various channels to share the inventory and product information to 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, CART Rest API endpoints will be provided by the Fenix team.

Integration Architecture

Request & Response formats

All the request and response formats are accepted in application/JSON

Delivery Estimates Request

API	/fenixdelest/api/v2/deliveryestimates
Method	POST
Request Headers	tenantId : mdnf79df0n89na1f2ce434b8861c0fab14fb813 Content-Type: application/json x-api-key: mdnf79df0n89na1f2ce434b8861c0fab14fb813
Request body sample	{ "buyerZipCode": "string", "sessionTrackId": "string", "orderId": "string", "cartId": "string", "pageType": "string", "monetaryValue": 0, "responseFormat": "string", "additionalProcessing": true, "customerTags": [ "string" ], "shippingInfo": { "carrier": "string", "service": { "method": "string", "name": "string" }, "shippingDate": "string", "trackId": "string" }, "skus": [{ "sku": "string", "category": "string", "digitalProduct": true, "itemType": "FREE", "leadTime": 0, "nonShip": true, "productName": "string", "quantity": 0, "dimensions": { "girth": 0, "height": 0, "length": 0, "thickness": 0, "units": "CM/IN", "width": 0 }, "skuInventories": [{ "locationId": "string", "quantity": 0 }], "weight": { "units": "LB", "value": 0 } }], "buyerAddress": { "name": "string", "state": "string", "zipcode": "string", "address1": "string", "address2": "string", "city": "string", "country": "string", "dealerAddress": true, "details": { "apoFpoAddress": true, "dealer": true, "dealerId": "string", "poAddress": true } } }

Request Body Attribute Definitions

Attribute

Description

sessionTrackId

mandatory

"sessionTrackId":"123123-2323-1231-23123"

Unique session track id generated on per session basis on client side

orderId

"orderId": "123123123"

Order Id generated by the retailer system

cartId

"cartId": "123123123"

A Cart Id generated by the retailer system

buyerZipCode

mandatory

"buyerZipCode" : "95129"

The zip of the item's buyer.

pageType

mandatory

"pageType": "cop"

Rules are tied to page type value.

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

Item price in PDP or the total cart in cart or total checkout value at checkout

responseFormat

mandatory

"responseFormat" : "json"

The attribute provides the desired delivery estimate response format. Allowed formats are “Json” and “binary.” The default response format is JSON.

additionalProcessing

"additionalProcessing": true

True if a particular item required additional processing time than normal SKU

customerTags

"customerTags": [

"USA",

"Dealer"

]

This is applicable for only Shopify retailers to send Customer specific tags

shippingInfo

"shippingInfo": {

"carrier": "string",

"service": {

"name": "string"

"method": "string",

},

"shippingDate": "string",

"trackId": "Z12372y312923182u3821"

}

In case of subscriptions/recurring orders in your business, if you want to provide EDD after pick-pack-ship

carrier : The carrier name
name : The service name of the carrier
method : The shipping service method name
shippingDate: The expected/planned ship date of any order
trackId: The tracking number generated as part of label creation

skus

mandatory

"skus": [{

"sku": "SKU-001",

"category": "Mens|topwear",

"digitalProduct": false,

"itemType": "FREE",

"leadTime": 0 ,

"nonShip": false,

"productName": "Red T-shirt",

"quantity": 1,

"dimensions": {

"girth": 3,

"height": 3,

"length": 3,

"width": 0,

"thickness": 6,

"units": "CM/IN"

},

"skuInventories": [{

"locationId": "Dc-01",

"quantity": 1

}],

"weight": {

"units": "LB",

"value": 0

}

}]

sku: The item's SKU (stock keeping unit).
category: The item category name
digitalProduct: The item is digital/downloadable item
itemType: The type of the item e.g. FREE,GIFT,E-GIFT, Bundled etc
leadTime: The time required to prepare the item to ship
nonship: The item is not eligible for shipping to buyer
productName: The name of the product
quantity: The number of items that were chosen to buy.
dimensions: The dimensions and weight of the item along with unit of measurement. Required only when there is no product & inventory sync integration with Fenix Commerce
skuInventories: Inventory location and quantity details of SKU
locationId : The physical location (DC/Store ID) of the item. Required only when there is no product & inventory sync integration with Fenix Commerce
quantity :The total quantity
weight: The total weight of the item

buyerAddress

"buyerAddress": {

"name": "Sharath Chandra",

"address1": "5437",

"address2": "castle",

"city": " San Jose ",

"state": "CA",

"country": "USA",

"zipcode": "95129",

"dealerAddress": true,

"details": {

"dealer": true,

"dealerId": "SFO-SJ-D001",

"apoFpoAddress": true,

"poAddress": true

}

name: Full name of the buyer
address1: The street address of the buyer address.
address2: An optional additional field for the street address of the buyer address.
city: The city, town, or village of the buyer address
state: The state of the buyer address
country: The country code of the buyer address
zipcode: The postal code (zip, postcode, Eircode, …) of the buyer address.
dealerAddress: If true, In case if you’re shipping to your dealer address then the address will dealer address of the buyer address.
dealer: the buyer is a dealer
dealerId: The dealer unique ID
poAddress: The address is pobox address of the buyer address.
apoFpoAddress: The zipcode falls in apo/fpo zipcode List of the buyer address.

Response Attribute Definitions

Delivery Estimates response vary from the type of rule configured in the business console.

Attribute	Description
webId	"webId": "0194NCOS" The item's SKU (stock keeping unit).
hours	"hours": "2"
minutes	"minutes": "1" Total min leftover for to order an item before configured cutoff time
carrier	"carrier": "fedex" The name of the recommended shipping carrier
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 · The formatted response required to paint the Estimated Delivery Date (EDD) on required page types. This format can be changed through Fenix business console
shippingCost	"shippingCost": { "amount": 0.00 , "currency": "USD" } Amount : The shipcost need to pay by buyer Currency: The shipcost currency format
shipperLocId	"shipperLocId": null, The shipping location Id of the retailer’s DC/Store
buyerZipCode	"buyerZipCode": "10001" The zipcode of the customer
shipperZipCode	"shipperZipCode": "10001", The shipping location zipcode of the retailer’s DC/Store
shippingMethod	"shippingMethod": null, The shipping method to choose by retailer
shippingDateTime	"shippingDateTime": "19 May 2021, 19:00", The shipping date time of the shipment by a retailer
actualMethodDesc	"actualMethodDesc": "Fedex Ground" , The actual method description of a shipping method
shippingMethodCode	"shippingMethodCode": "Free Standard Delivery" The shipping method code delivery date to show it to end customer
shippingMethodDesc	"shippingMethodDesc": "Free Standard Delivery" The shipping method description
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, The delivery estimate error responses in case of inventory not found , tenant disabled etc
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 Carrier: The name of the carrier wrapperType: The package or box type need to be used to ship the package shipperLocId: The DC/Store unique Id shipperZipCode: The DC/Store zipcode actualMethodDesc: The actual shipping method description contents: The sku and quantity information in particular package "SKU":quantity
pickUpTimes	"pickUpTimes": { "81": "05-19-2021 19:00", "82": "05-19-2021 19:00" } · The configured pickup time of each shipping service method code "shipping service method code" : "Configured pickup time."

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/v2/deliveryestimates
Request Headers	tenantId : mdnf79df0n89na1f2ce43dfsfds4b8861c0fab14fb813 Content-Type: application/json x-api-key: mdnf79df0n89na1f2ce434b8861ckkndfsdk0fab14fb813
Request Body Sample: { "cartId": null, "orderId": "no-token", "sessionTrackId": "MTYxNzc2MTI0MzE5MS10b21ib3l4LmNvbS02OTQ1Mw==", "internalSessionUUID": "cf500124-a374-4095-abed-d570250174da", "pageType": "PDP", "monetaryValue": 47.99, "buyerZipCode": "10001", "skus": [ { "sku": "ABC_2", "quantity": 1, "leadTime": 0, "weight": null, "category": null, "nonShip": false, "productName": null, "itemType": null, "dimensions": null, "digitalProduct": false, "skuInventories": [ { "locationId": "manual", "quantity": 1 } ] } ], "responseFormat": "json", "buyerAddress": null, "residentialAddress": false, "exceptionalTypes": null, "shopifyRequest": false, "platformType": null, "customerTags": null, "shippingInfo": null, "properties": null, "orderByThresholdTime": 0, "lookupFenixInventory": false, "surePostEnabled": false }
Response Body Sample [ { "webId": "ABC_2", "hours": "8", "minutes": "53", "carrier": "FEDEX", "response": "Order Today, Get it by Monday, Aug 23. Choose Standard shipping at Checkout", "shippingCost": null, "shipperLocId": "manual", "buyerZipCode": "10001", "shipperZipCode": "11216", "shippingMethod": "GND", "shippingDateTime": "20 Aug 2021, 18:00", "actualMethodDesc": "FEDEX_GROUND", "shippingMethodDesc": "Standard", "formattedDeliveryDate": "Monday, Aug 23", "guaranteedDeliveryDate": "Mon, 23 Aug 2021", "errorMessage": null, "packages": [ { "carrier": "FEDEX", "wrapperType": "DEFAULT", "shipperLocId": "manual", "shipperZipCode": "11216", "actualMethodDesc": "FEDEX_GROUND", "contents": { "ABC_2": 1 } } ], "pickUpTimes": { "FEDEX_2_DAY": "08-20-2021 18:00", "STANDARD_OVERNIGHT": "08-20-2021 18:00", "FEDEX_GROUND": "08-20-2021 18:00" }, "prePurchaseShippingInfos": null, "shippingDeliveryDate": "Mon, 23 Aug 2021", "nextDayResponse": false, "code": null } ]

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/v2/deliveryestimates
Request Headers	tenantId : mdnf79df0n89na1f2ce43dfsfds4b8861c0fab14fb813 Content-Type: application/json x-api-key: mdnf79df0n89na1f2ce434b8861ckkndfsdk0fab14fb813
Request Body Sample: { "cartId": null, "orderId": "no-token", "sessionTrackId": "MTYxNzc2MTI0MzE5MS10b21ib3l4LmNvbS02OTQ1Mw==", "internalSessionUUID": "cf500124-a374-4095-abed-d570250174da", "pageType": "CART", "monetaryValue": 47.99, "buyerZipCode": "10001", "skus": [ { "sku": "ABC_2", "quantity": 1, "leadTime": 0, "weight": null, "category": null, "nonShip": false, "productName": null, "itemType": null, "dimensions": null, "digitalProduct": false, "skuInventories": [ { "locationId": "manual", "quantity": 1 } ] }, { "sku": "GSLV90", "quantity": 1, "leadTime": 0, "weight": null, "category": null, "nonShip": false, "productName": null, "itemType": null, "dimensions": null, "digitalProduct": false, "skuInventories": [ { "locationId": "westcost", "quantity": 1 } ] } ], "responseFormat": "json", "buyerAddress": null, "residentialAddress": false, "exceptionalTypes": null, "shopifyRequest": false, "platformType": null, "customerTags": null, "shippingInfo": null, "properties": null, "orderByThresholdTime": 0, "lookupFenixInventory": false, "surePostEnabled": false }
Response Body Sample

Checkout Page Request and Response

API

/fenixdelest/api/v2/deliveryestimates

Method

POST

Request Headers

tenantId : mdnf79df0n89na1f2ce434b8861c0fab14fb813
Content-Type: application/json
x-api-key: mdnf79df0n89na1f2ce434b8861c0fab14fb813

Request Body

Respone Body