Logistics Extension API Guide

Scheme creation steps

Scheme API

Scheme - A delivery partner would have multiple services they would like to offer. Those services can be one or more. These services are known as schemes. These are unique for every extension. These schemes needs to be created and can be updated to platform system.
Create scheme and Update Scheme
The below table indicates the various keys used while creating a scheme. These are to indicate to the platform, along with seller about the features supported by the scheme of the delivery partner
Fields, Description and Required

Fields	type	Required	Description
delivery_type	String	yes	Delivery type i.e standard, hyperlocal, sdd, ndd
extension_id	String	yes	extension api key
feature	Object	yes	feature supported for the scheme
name	String	yes	name of the service/scheme offered
payment_mode	Array	yes	payment accepted i.e prepaid/cod or both
region	String	yes	inter-city, inter-state, inter-country, intra-city
scheme_id	String	yes	unique id for the scheme
stage	String	yes	scheme status i.e enabled/disabled
transport_type	String	yes	surface/air/waterways
volumetric_weight	Object	yes	acceptable volumetric weight for service/scheme
weight	Object	yes	acceptable dead weight for service/scheme

Fields	type	Required	Description
gt	Number	No	greater than example : `gt 5`, it means `greater than 5`. So, 6, 7, and 8 are all greater than 5
gte	Number	No	greater than or equal to example: `gte 5`, it means `greater than or equal to 5`. So, 5, 6, and 7 all fit this condition.
lt	Number	No	less than example: `lt 5`, it means `less than 5`. So, 4, 3, and 2 are all less than 5.
lte	Number	No	less than or equal to example: `lte 5`, it means `less than or equal to 5`. So, 5, 4, and 3 all fit this condition.

Send the followings keys as true if the delivery partner supports the capability mentioned

Fields	type	Required	Description
cold_storage_goods	Boolean	No	Goods that need to be kept at low temperatures to stay fresh or safe. Examples include perishable food items, pharmaceuticals, and certain chemicals
dangerous_goods	Boolean	No	Items that pose risks to health, safety, property, or the environment. Examples include flammable liquids, explosives, and toxic substances.
doorstep_exchange	Boolean	No	A service where items are exchanged at the customer's doorstep. For instance, a customer might exchange a faulty product for a new one without leaving their home.
doorstep_qc	Boolean	No	Performing a quality check of products at the customer’s doorstep before picking the returned product. Send true if the delivery partner supports the door step QC capability Doorstep Quality Check (QC) is a service where the quality of the to-be-picked up items is verified at the customer's doorstep before accepting the return. This ensures that the products meet the expected standards and allows for immediate returns or exchanges if any issues are detected.
doorstep_return	Boolean	No	Send this key as true if the delivery partner support door step return while delivering the forward shipment to the customer Doorstep return refers to the process where, upon delivering a shipment, the customer rejects it on the spot, and the delivery partner immediately accepts the return. This service streamlines the return process by handling it directly during the delivery attempt, ensuring a smooth and efficient experience for the customer.
ewaybill	Boolean	No	Send this true if delivery partner supports EWB or >50k shipments An e-way bill is required during the transportation of goods valued above ₹50,000 in India, either interstate or intrastate, to ensure compliance with GST regulations. It helps prevent tax evasion by providing a digital record of goods being transported, thus facilitating easier tracking and verification by authorities.
fragile_goods	Boolean	No	Items that can easily break or get damaged, such as glassware, electronics, and ceramics.
mps	Boolean	No	A Multi-Piece Shipment (MPS) involves multiple packages being shipped together under a single tracking number, ensuring that all packages in the shipment are processed and delivered together. This method is often used for large orders that are split into several parcels but are meant to be delivered to the same destination at the same time under same shipment id or parent AWB
multi_pick_multi_drop	Boolean	No	A logistics process where goods are picked up from multiple locations and delivered to multiple destinations
multi_pick_single_drop	Boolean	No	A process where goods are picked up from multiple locations and delivered to a single destination
ndr_attempts	Number	No	Number of re-attempts the delivery partner provides/supports once delivery attempt to customer has failed the first time
openbox_delivery	Boolean	No	A delivery method where the package is opened in front of the customer to check for damage or verify contents before completing the delivery
product_installation	Boolean	No	The service of setting up and installing a product at the customer's location after delivery
qr	Boolean	No	The QR code is shared by the delivery partner to accept payment from the customer at the delivery point.
restricted_goods	Boolean	No	tems that have limitations or are regulated for shipping due to safety, legal, or other concerns. Examples include firearms, certain chemicals, and live animals
single_pick_multi_drop	Boolean	No	A process where goods are picked up from a single location and delivered to multiple destinations
status_updates	Boolean	No	The delivery partner shares status updates of the manifested shipment in real-time via push notifications or by using a pull method through the polling track API.

Serviceability

Logistics service providers often maintain data about the areas they serve and the features they can offer at different pincodes or regions. This data is commonly referred to as Serviceability.
Serviceability data is crucial for our platforms, as it plays a central role in determining the promises or commitments our platform can make to end customers regarding the delivery of goods or services. Failing to provide the data would miss out assigning orders to that particular scheme/account
Serviceability indicates the set of regions/pincodes that particular scheme can provide their pickup and delivery services. Serviceability data needs to be provided to platform system. Therefore its upto extension’s owner choice of they want to update the data and the frequency of the data.
Once a Scheme is created it is essential to provide serviceability data to be stored against a scheme.
Get countries data to get the hierarchy data of the country for which you want to upload the data.
Based on the required country’s sample file, send the country’s name and hierarchy at which you want to upload the data.
For example, for India you can upload data against pincode or state or city based on delivery partner’s side capability or provision
In case you want to upload serviceability at pincode level, use name=India and region=pincode
Download sample serviceability file with type as “serviceability”
Upload the file. Refer to File Upload process on Fynd Commerce
You can get the status of the file uploaded using Status method
You can get history of files uploaded as well
The below table indicates the various keys used while creating a scheme. These are to indicate to the platform, along with seller about the features supported by the scheme of the delivery partner
Fields, Description and Required

Following table describes keys of serviceability file upload against an scheme id

Fields	type	Required	Description
extensionId	String	yes	extensions API key
schemeId	String	yes	scheme id
body	Object	yes	Body Object

Body Object

Fields	type	Required	Description
file_path	String		cdn url of the file uploaded
country	String	yes	country of the data uploaded
action	String	yes	import or export
region	String	yes

TAT

TAT indicates the time taken to delivery for given pair of regions/pincodes, this TAT data will be used for providing indicative promise of delivery date when customers go through store-front journey across PDP, Cart and check out pages. TAT data needs to be provided to platform system. Therefore its upto extension’s owner choice of they want to update the data and the frequency of the data.
Once a Scheme is created it is essential to provide TAT data to be stored against a scheme.
Get countries data to get the countries data and hierarchy data of those countries.
Based on the required country’s sample file, send the country’s name and hierarchy at which you want to upload the data.
For example, for India you can upload data against pincode or state or city based on delivery partner’s side capability or provision
In case you want to upload TAT at pincode level, use name=India and region=pincode
Download sample serviceability file with type as “TAT”
Upload the file. Refer to File Upload process on Fynd Commerce
You can get the status of the file uploaded using Status method
You can get history of files uploaded as well
The below table indicates the various keys used while creating a scheme. These are to indicate to the platform, along with seller about the features supported by the scheme of the delivery partner
Fields, Description and Required

Following table describes keys of TAT file upload against an scheme id

Fields	type	Required	Description
extensionId	String	yes	extensions API key
schemeId	String	yes	scheme id
body	Object	yes	Body Object

Body Object

Fields	type	Required	Description
file_path	String		cdn url of the file uploaded
country	String	yes	country of the data uploaded
action	String	yes	import or export
region	String	yes

File Upload process

Partner can use the below SDK method to upload file data/buffer and in return will get public accessible URL
Steps to generate CDN URL
- call Start Upload to generate CDN URL
- put data in the CDN URL
- call Complete Upload to complete the upload
Further those links can be used to upload serviceability and TAT file.
As part of logistics extensions there will be use cases wherein partner will have to provide the following files as part of the operations, some examples are
- QC Images: In return journey when delivery partner does QC and takes images while check the quality of the return. Those images needs to be sent to Fynd Commerce OMS during shipment status update
- POD Images: Once delivery is done to customer some delivery partners take signature from customer as proof. Those images can also be sent through same methodology
- Shipping Label PDF
- Export Invoice PDF

Account creation steps

Account API

Account - When an extension is installed by a seller and enables / configures a particular scheme, the seller x scheme = accounts. Accounts are unique for every seller against a scheme they choose or opt for. For a given account, extension owner can/needs to take input of the account credentials from seller through UI of the extension they build to verify and keep record/track of the contracts, charges and usage of the services by a seller.
Create Account, Update Account, List of accounts by a company / seller and Fetching status of an account of a company
The below table indicates the various keys used while creating a scheme. These are to indicate to the platform, along with seller about the features supported by the scheme of the delivery partner
Fields, Description and Required

Fields	type	Description	Required
extension_id	string	extensions API key	yes
account_id	string	unique account id	yes
scheme_id	string	scheme id	yes
stage	string	enabled or disabled	yes
is_self_ship	boolean	false - default	yes
is_own_account	boolean	Send FALSE only if cluster's [Fynd] Administrator managed credentials or else send TRUE by default [which mostly the case of Seller own managed / created credentials]	yes

Webhook subscription process

This link will provide detailed process of webhook

Assign shipment event

Payload - https://partners.fynd.com/help/docs/webhooks/latest/application#courier-partner
Assign - application/courier-partner/assign/v1

Few Use-cases explanation

MPS
- A Multi-Piece Shipment (MPS) involves multiple packages being shipped together under a single tracking number, ensuring that all packages in the shipment are processed and delivered together. This method is often used for large orders that are split into several parcels but are meant to be delivered to the same destination at the same time under same shipment id or parent AWB
Doorstep QC
- Doorstep Quality Check (QC) is a service where the quality of the to-be-picked up items is verified at the customer's doorstep before accepting the return. This ensures that the products meet the expected standards and allows for immediate returns or exchanges if any issues are detected.
COD
- Indicates that the shipment is a COD order and needs to collect payment amount from customer while delivering the shipment
EWay Bill
- An e-way bill is required during the transportation of goods valued above ₹50,000 in India, either interstate or intrastate, to ensure compliance with GST regulations. It helps prevent tax evasion by providing a digital record of goods being transported, thus facilitating easier tracking and verification by authorities.
QR
- A QR code on an invoice is required for businesses with an annual turnover above ₹500 crores in India, as per GST regulations. It ensures the easy digital verification of the invoice, enhances transparency, and speeds up processing for compliance and audit purposes.

Cancel shipment event

Payload - https://partners.fynd.com/help/docs/webhooks/latest/application#courier-partner
Cancel - application/courier-partner/cancel/v1

Shipment status update

https://partners.fynd.com/help/docs/sdk/latest/platform/company/order#updateShipmentStatus
The delivery partner extension needs to provide shipment tracking updates on real time.
- If delivery partner is unable to provide it on real time basis, need to convey the updates in interval time of status updates
- Courier partner need to update the updated shipment status in the conveyed interval time to Fynd
Courier partner can send the extra information in meta fields under entities and products.
- Entities: If the information is related to shipment, can be send under shipment meta
- products: If the information is related to items/products of shipment, can be send under products meta
Delivery partner extension needs to send below details in meta

{
    "meta": {
        "qc_images": [], // list of images url
        "pod": {
            "delivery_pod": [], // list of image url
            "rev_pod": []
        },
        "qr_code": {
            "qr_url": "", // url
            "qr_data": "" // qr data
        },
        "label":"", // url
        "export_invoice":"", // url
        "ewaybill_info": {
            "forward": {
            "ewayBillNo": 331003419231,
            "ewayBillDate": "29/08/2023 08:51:00 AM",
            "validUpto": null,
            "success": true
            },
            "reverse": {
            "ewayBillNo": 331003419231,
            "ewayBillDate": "29/08/2023 08:51:00 AM",
            "validUpto": null,
            "success": true
            }
        },
        "estimated_delivery_time": "", // date and time
        "rider_details": {
            "name": "",
            "phone": "",
            "image": ""
        },
        "otp_details":{
            "drop":"",
            "pick":""
        },
        "location": {
            "latitude": "",
            "longitude": ""
        },
        "waybills":[{"awb_number":"", "seller_identifier":""}],
        "is_own_account": true/false
        "QC": true/false
    }
}

Scheme creation steps​

Serviceability​

TAT​

File Upload process​

Account creation steps​

Webhook subscription process​

Assign shipment event​

Cancel shipment event​

Shipment status update​