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

  1. 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

  2. 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

  3. 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

  4. 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

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