Skip to main content

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
FieldstypeRequiredDescription
delivery_typeStringyesDelivery type i.e standard, hyperlocal, sdd, ndd
extension_idStringyesextension api key
featureObjectyesfeature supported for the scheme
nameStringyesname of the service/scheme offered
payment_modeArrayyespayment accepted i.e prepaid/cod or both
regionStringyesinter-city, inter-state, inter-country, intra-city
scheme_idStringyesunique id for the scheme
stageStringyesscheme status i.e enabled/disabled
transport_typeStringyessurface/air/waterways
volumetric_weightObjectyesacceptable volumetric weight for service/scheme
weightObjectyesacceptable dead weight for service/scheme
FieldstypeRequiredDescription
gtNumberNogreater than
example : gt 5, it means greater than 5. So, 6, 7, and 8 are all greater than 5
gteNumberNogreater than or equal to
example: gte 5, it means greater than or equal to 5. So, 5, 6, and 7 all fit this condition.
ltNumberNoless than
example: lt 5, it means less than 5. So, 4, 3, and 2 are all less than 5.
lteNumberNoless 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

FieldstypeRequiredDescription
cold_storage_goodsBooleanNoGoods that need to be kept at low temperatures to stay fresh or safe. Examples include perishable food items, pharmaceuticals, and certain chemicals
dangerous_goodsBooleanNoItems that pose risks to health, safety, property, or the environment. Examples include flammable liquids, explosives, and toxic substances.
doorstep_exchangeBooleanNoA 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_qcBooleanNoPerforming 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_returnBooleanNoSend 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.
ewaybillBooleanNoSend 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_goodsBooleanNoItems that can easily break or get damaged, such as glassware, electronics, and ceramics.
mpsBooleanNoA 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_dropBooleanNoA logistics process where goods are picked up from multiple locations and delivered to multiple destinations
multi_pick_single_dropBooleanNoA process where goods are picked up from multiple locations and delivered to a single destination
ndr_attemptsNumberNoNumber of re-attempts the delivery partner provides/supports once delivery attempt to customer has failed the first time
openbox_deliveryBooleanNoA delivery method where the package is opened in front of the customer to check for damage or verify contents before completing the delivery
product_installationBooleanNoThe service of setting up and installing a product at the customer's location after delivery
qrBooleanNoThe QR code is shared by the delivery partner to accept payment from the customer at the delivery point.
restricted_goodsBooleanNotems 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_dropBooleanNoA process where goods are picked up from a single location and delivered to multiple destinations
status_updatesBooleanNoThe 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

FieldstypeRequiredDescription
extensionIdStringyesextensions API key
schemeIdStringyesscheme id
bodyObjectyesBody Object

Body Object

FieldstypeRequiredDescription
file_pathStringcdn url of the file uploaded
countryStringyescountry of the data uploaded
actionStringyesimport or export
regionStringyes

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

FieldstypeRequiredDescription
extensionIdStringyesextensions API key
schemeIdStringyesscheme id
bodyObjectyesBody Object

Body Object

FieldstypeRequiredDescription
file_pathStringcdn url of the file uploaded
countryStringyescountry of the data uploaded
actionStringyesimport or export
regionStringyes

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
  • 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
FieldstypeDescriptionRequired
extension_idstringextensions API keyyes
account_idstringunique account idyes
scheme_idstringscheme idyes
stagestringenabled or disabledyes
is_self_shipbooleanfalse - defaultyes
is_own_accountbooleanSend 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

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

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
}
}


Was this section helpful?