Logistics Extension API Guide
Scheme Creation Steps
Scheme API
- Scheme: A Delivery Partner (DP) 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 need to be created and can be updated to the 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 the seller about the features supported by the scheme of the DP:
| Fields | type | Required | Description |
|---|---|---|---|
| delivery_type | String | Yes | Delivery type, that is 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, that is 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 DP 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 up the returned product. Send true if the DP supports the doorstep 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 immediate returns or exchanges if any issues are detected. |
| doorstep_return | Boolean | No | Send this key as true if the DP 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 DP 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 DP 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 the 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 DP provides/supports once delivery attempt to the 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 DP shares the QR code to accept payment from the customer at the delivery point. |
| restricted_goods | Boolean | No | Items 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 DP 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 pin codes 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/pin codes that particular scheme can provide their pickup and delivery services. Serviceability data needs to be provided to platform system. Therefore, it is up to the 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 the 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 the DP’s side capability or provision.
- In case you want to upload serviceability at the 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 DP.
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
- It indicates the time to deliver a shipment in regions/pin codes. This TAT data will be used to provide an indicative delivery date when customers go through the storefront journey across PDP, Cart, and check-out pages. TAT data needs to be provided to the platform system. Therefore, it is up to the extension’s owner to choose whether 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 | Echeme 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
- 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 the 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
- Cancel: application/courier-partner/cancel/v1
Shipment Status Update
- https://partners.fynd.com/help/docs/sdk/latest/platform/company/order#updateShipmentStatus
- The DP extension needs to provide shipment tracking updates in real time.
- If DP is unable to provide it on real time basis, need to convey the updates in interval time of status updates.
- The 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 the shipment, it can be send under shipment meta
- products: If the information is related to items/products of shipment, it can be send under products meta
- DP extension needs to send the 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
}
}