Flipkart Integration with Eshopbox
- Yashika Saini (Unlicensed)
- The Flipkart Marketplace Seller Platform allows sellers to register their businesses, sell products, and manage various aspects related to products and orders. This document will familiarize you with the key business process and system concepts in the marketplace.
Overview
Business Process | Details | System Concepts |
|---|---|---|
Registration | The first step for a seller is to join the Marketplace. The seller goes through a process of collection, verification, and approval of the business and the products up for sale. | Registered Seller A registered seller in the Marketplace is identified by a unique seller ID. |
Location Onboarding | Sellers need to provide information on all the different locations from where they need their products to be picked up or dispatched. Also, additional information will be required like a registered address, GSTIN details, etc. corresponding to each location. | Registered Locations An on-boarded location will be identified in the system by a unique location ID. Every location ID will have a pickup/dispatch address and a registered address. |
Listing Management | A seller can create a new product listing with the required attributes or identify an existing product from the product catalog in the Marketplace, to start selling. Sellers must manage their stock count, price, and dispatch SLA of products using the listing management system in the Marketplace | Product A product is defined under a Flipkart sub-category (example: T-shirt or Mobile) using a predefined set of attributes such as brand, model, color, and so on. It is identified by a Flipkart Serial Number (FSN). Listing A listing is the complete information of a product that buyers view before placing an order. It contains details such as stock, price, delivery period, and so on. It is identified by a listing ID, which is mapped to the seller’s SKU ID. |
Order Fulfillment | Order Fulfilment requires sellers to get visibility on new orders, pack them (get shipping labels, invoices & logistics forms), mark them ready for dispatch, handover to logistics partners. Self Ship Fulfilment will require sellers to provide additional updates like delivery confirmation, service completion, etc. | Order An order represents all the products that a customer has ordered in a checkout session. This can be across different sellers in the marketplace. Order Item An order item represents a particular product in a given order. An order item can have multiple quantities in it. Shipment A shipment is a group of order items that the seller needs to pick, pack, dispatch, and handover together to logistics partner. In the case of self-ship fulfillment, the seller needs to update delivery confirmation, service completion at a shipment level. |
Payment Management | A seller manages the settlement transactions, payments, and invoices using the accounting solutions in the Marketplace. | Transaction A transaction provides the order settlement and payment details at the order item level. Settlement A settlement is a periodic payment made to the seller by Flipkart. |
Return Management | Sellers get visibility of returns and can take respective actions associated with them depending on the state of the return and type of order fulfillment process. Returns can lead to refunds, replacements, or return cancellation as per Flipkart policies or seller actions. In the case of self-ship returns, the seller needs to approve or reject a return, acknowledge courier returns, confirm reverse pickups. | Return Flipkart Marketplace creates a return when a buyer wants to return/exchange a product or if there is an issue with the product itself. Every return is represented by a returnID and corresponds to one quantity of an order item. |
Steps to build the Flipkart Integration with Eshopbox
Step 1: App Registration and Environment Setup
To start working with seller APIs, first register as a seller with the Marketplace at https://seller.flipkart.com.
After the registration, the seller API will fetch a token for authorization purposes. Note: Do not hard code the authorization header because the token expires usually in 60 days. If a hard-coded token is used, then the API call will fail with a 401 HTTP status code.
For Staging and Production Environment, a third-party tool should be used such as Sandbox. Get the credentials by emailing seller-api-queries@flipkart.com to use the Sandbox environment.
Step 2: Generating Access Tokens
Once the application is registered, a fresh token is used to make API calls. Flipkart API Authorization framework supports two grant types to generate access tokens namely, the Client Credentials, and Authorization Code flows.
To generate access tokens using the Client Credentials flow, use the below-mentioned API either by programming or use curl statement to get the access tokens.
GET /oauth-service/oauth/token?grant_type=client_credentials&scope=Seller_Api,DefaultThe API is authenticated using Basic Access Authentication mechanism and the Authorization header is expected.
- e.g. if your registered application appId is
my-appId-1and appSecret ismy-app-secret-1, the credential to be used for Basic authentication would be the base64 encoding ofmy-appId-1:my-app-secret-1
Examples
Postman: Postman is the easiest way to generate an access token and manually test to understand the working of the API. As seen in the below diagram, the appID and appSecret can be directly used as the Username and Password after selecting Basic Auth as the Authorization type.
Java: Another way of generating tokens would be to use Java as seen below. Once the below code is used to generate the access token, it can be used to make API calls by passing it as Bearer Token in the
Authorizationheader of the HTTP request. However, the recommended way to integrate is to use auto-generated client code by using the Swagger spec. If you are using any other language, you can useswagger-codegento auto-generate the client code for that language. Steps to installswagger-codegencan be followed from the official documentation page.
import java.util.Base64;
import kong.unirest.Unirest;
import kong.unirest.json.JSONException;
import kong.unirest.json.JSONObject;
public final class MyFkApp {
private static final String CLIENT_ID = "__CLIENT_ID__"; // Replace with your application id or client id
private static final String CLIENT_SECRET = "__CLIENT_SECRET__"; // Replace with your application secret or client secret
private MyFkApp() {
}
public static void main(String[] args) {
String base64EncodedString = Base64.getEncoder().encodeToString((CLIENT_ID + ":" + CLIENT_SECRET).getBytes());
JSONObject respoJsonObject = Unirest.get("https://sandbox-api.flipkart.net/oauth-service/oauth/token?grant_type=client_credentials&scope=Seller_Api")
.header("Authorization", "Basic " + base64EncodedString)
.asJson()
.getBody()
.getObject();
String accessToken = "";
String error = "";
try {
accessToken = respoJsonObject.getString("access_token");
System.out.println("Access Token : " + accessToken);
} catch (JSONException jse) {
error = respoJsonObject.getString("error_description");
System.out.println("Error occurred ! Error description : " + error);
}
}
}You need to add a dependency on unirest-java for the above code to run. Kindly refer to unirest-java documentation for more info.
Python:
import requests import base64 url = "https://sandbox-api.flipkart.net/oauth-service/oauth/token" querystring = {"grant_type": "client_credentials", "scope": "Seller_Api"} client_id = "__CLIENT_ID__" # Replace with your application id or client id client_secret = "__CLIENT_SECRET__" # Replace with your application secret or client secret headers = { 'Authorization': "Basic " + base64.b64encode(client_id + ":" + client_secret) } response_json = requests.request("GET", url, headers=headers, params=querystring).json() access_token = response_json["access_token"] print("Your access token is : " + access_token)Curl:
curl -u <appid>:<app-secret> https://api.flipkart.net/oauth-service/oauth/token?grant_type=client_credentials&scope=Seller_Api
Sample Response
- { "access_token": "<token>", "token_type": "bearer", "expires_in": 3330779, "scope": "Seller_Api" }
Step 3: Authorization Code Flow
This flow should be used If you are an Aggregator or a Vendor and is going to manage orders and listings on behalf of other sellers registered on Flipkart Marketplace
Get the Seller’s Authorization: To begin an Authorization code flow, your web application should first send the seller to the Authorization URL.
Authorization URL
https://sandbox-api.flipkart.net/oauth-service/oauth/authorize?
client_id=<client-id>&
redirect_uri=<redirect-uri>&
response_type=code&
scope=Seller_Api&
state=<state>Where,
client-id: Application’s Client ID located at Seller APIs - Developer Admin portalredirect-url: The URL to which Flipkart will redirect the browser after authorization has been granted by the seller.state:
……………………………………………………………………………………………………………………………………………………………………………
Step 6: Flipkart Event Ready to Dispatch
API URL: https://api.flipkart.net/sellers/v3/shipments/{shipmentIds}
Refer to the table below Request Header Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
Refer to the table below Response Header Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Refer to the Example below “Ready_to_Dispatch” Event
{
"eventType": "shipment_ready_to_dispatch",
"source": "flipkart",
"version": "v3",
"timestamp": "2017-03-30T14:45:25+05:30",
"attributes": {
"status": "READY_TO_DISPATCH"
},
"shipmentId": "870cbeb2-33f4-4ba8-a3de-5bc2f90625d3"
}Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Step 7: Download Manifest
API URL: https://api.flipkart.net/sellers/v3/shipments/manifest
Refer to the table below for Request Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Refer to the example below for Downloading the Manifest in PDF format
{
"params": {
"pickupDate": {
"after": "2020-09-18T12:38:36.881Z",
"before": "2020-09-18T12:38:36.881Z"
},
"locationId": "string",
"is_mps": true,
"vendorGroupCode": "string"
}
}Step 8: Flipkart Shipped and Delivered
SHIPPING API URL: https://api.flipkart.net/sellers/v3/shipments/{shipmentIds}
Refer to the table below for Request Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
Refer to the table below for Response Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| externalChannelID |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Refer to the below example for the Shipped Event and Delivered Event.
{
"shipments": [
{
"orderId": "string",
"subShipments": [
{
"shipmentDimensions": {
"breadth": 0,
"length": 0,
"weight": 0,
"height": 0
},
"subShipmentId": "string",
"courierDetails": {
"pickupDetails": {
"vendorName": "string",
"trackingId": "string"
},
"deliveryDetails": {
"vendorName": "string",
"trackingId": "string"
}
}
}
],
"returnAddress": {
"city": "string",
"contactNumber": "string",
"firstName": "string",
"lastName": "string",
"pinCode": "string",
"state": "string",
"addressLine2": "string",
"stateCode": "string",
"addressLine1": "string",
"landmark": "string"
},
"buyerDetails": {
"lastName": "string",
"firstName": "string"
},
"shipmentId": "string",
"locationId": "string",
"billingAddress": {
"city": "string",
"contactNumber": "string",
"firstName": "string",
"lastName": "string",
"pinCode": "string",
"state": "string",
"addressLine2": "string",
"stateCode": "string",
"addressLine1": "string",
"landmark": "string"
},
"deliveryAddress": {
"city": "string",
"contactNumber": "string",
"firstName": "string",
"lastName": "string",
"pinCode": "string",
"state": "string",
"addressLine2": "string",
"stateCode": "string",
"addressLine1": "string",
"landmark": "string"
},
"sellerAddress": {
"city": "string",
"sellerName": "string",
"pinCode": "string",
"state": "string",
"addressLine2": "string",
"stateCode": "string",
"addressLine1": "string",
"landmark": "string"
},
"orderItems": [
{
"large": true,
"dangerous": true,
"fragile": true,
"id": "string"
}
]
}
]
}Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
…………………………………………………………………………………………….
Request to Generate Shipping Labels and Invoices
API URL: https://api.flipkart.net/sellers/v3/shipments/labels
Refer to the below table for Request Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Refer to the below table for Response Body Parameters/Attributes
Flipkart Attributes | Eshopbox Attributes |
|---|---|
|
|
|
|
|
|
|
|
Refer to the Example below for Generating Shipping Labels and Invoices
{
"shipments": [
{
"subShipments": [
{
"dimensions": {
"breadth": 0,
"length": 0,
"weight": 0,
"height": 0
},
"subShipmentId": "string"
}
],
"taxItems": [
{
"taxRate": 0,
"orderItemId": "string",
"quantity": 0
}
],
"invoices": [
{
"orderId": "string",
"invoiceNumber": "string",
"invoiceDate": "2020-09-18"
}
],
"serialNumbers": [
{
"serialNumbers": [
[
"string"
]
],
"orderItemId": "string"
}
],
"locationId": "string",
"shipmentId": "string"
}
]
}
Note: Once the Shipping Labels and Invoices are downloaded by making a POST API call to the URL: https://api.flipkart.net/sellers/v3/shipments/labels then the order status moves to “PACKING_IN_PROCESS“.
……………………..
Request to Generate Shipping Labels and Invoices
API URL: https://api.flipkart.net/sellers/v3/shipments/labels
Refer to the below table for Request Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Refer to the below table for Response Body Parameters/Attributes
Flipkart Attributes | Eshopbox Attributes |
|---|---|
|
|
|
|
|
|
|
|
Refer to the Example below for Generating Shipping Labels and Invoices
{
"shipments": [
{
"subShipments": [
{
"dimensions": {
"breadth": 0,
"length": 0,
"weight": 0,
"height": 0
},
"subShipmentId": "string"
}
],
"taxItems": [
{
"taxRate": 0,
"orderItemId": "string",
"quantity": 0
}
],
"invoices": [
{
"orderId": "string",
"invoiceNumber": "string",
"invoiceDate": "2020-09-18"
}
],
"serialNumbers": [
{
"serialNumbers": [
[
"string"
]
],
"orderItemId": "string"
}
],
"locationId": "string",
"shipmentId": "string"
}
]
}
Note: Once the Shipping Labels and Invoices are downloaded by making a POST API call to the URL: https://api.flipkart.net/sellers/v3/shipments/labels then the order status moves to “PACKING_IN_PROCESS“.
…………………
Step 3: Packed Notification
API URL: https://api.flipkart.net/sellers/v3/shipments/{shipmentIds}
Refer to the below Request Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
Refer to the below Response Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Refer to the below example for Packed Notification Event
{
"eventType": "shipment_packed",
"source": "flipkart",
"version": "v3",
"timestamp": "2017-03-30T14:45:25+05:30",
"attributes": {
"status": "PACKED"
},
"shipmentId": "870cbeb2-33f4-4ba8-a3de-5bc2f90625d3"
}Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Download Shipping Labels and Invoices
GET API URL: https://api.flipkart.net/sellers/v3/shipments/{shipmentIds}/labels
Refer to the below Request Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
Mark Order Ready to Dispatch
URL: https://api.flipkart.net/sellers/v3/shipments/dispatch
Refer to the below Request Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
Refer to the below Response Body Parameters/Attributes
Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
|
|
|
|
Refer to the Example below for “READY_TO_DISPATCH“
{
"locationId": "string",
"shipmentIds": [
"string"
]
}Flipkart Attribute | Eshopbox Attribute |
|---|---|
|
|
|
|
WHEN ORDER IS CANCELLED ON FLIPKART - CANCEL ORDER IN ESHOPBOX
Flipkart Cancel Order API URL: https://api.flipkart.net/sellers/v3/shipments/{shipmentIds}
Eshopbox Cancel Order API URL: https://wms.eshopbox.com/api/cancel-order
Flipkart Event Structure:
Canceling a Shipment on Flipkart
{
"shipmentId": "",
"eventType": "shipment_cancelled",
"locationId": "",
"source": "",
"timestamp": ISO time string,
"attributes": {
"status": "CANCELLED",
"orderItems": [{
"orderItemId": "",
"quantity": ,
"reason": "",
"subReason": ""
}]
}
}
Eshopbox Event Structure: Request Body Parameters/Attributes
curl -X POST http://wms.eshopbox.com/api/cancel-order \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"externalChannelID":"TATA CLIQ VELOCY KAPAS KRAFT",
"customerOrderNumber":"41007212",
"reason":"Cancelled By Customer",
"cancellationTime": "2018-07-08 22:00:05",
"items":
[
{
"lineItemSequenceNumber": 2331,
"itemID": "5050406281126",
"quantity": 1,
"productName": "Chinley Walk",
"remark" :"cancelled by customer"
}
]
}Eshopbox Event Structure: Response Body Parameters/Attributes
{
"status": "SUCCESS",
"result": {
"customerOrderNumber": "41007212",
"reason": "Cancelled By Customer",
"cancellationTime": "2018-07-08 22:00:05",
"items": [
{
"lineItemSequenceNumber": 2331,
"itemID": "5050406281126",
"quantity": 1,
"productName": "Chinley Walk",
"remark": "cancelled by customer"
}
]
}
}Below is an example of Shipment Cancelled on Flipkart
{
"eventType": "shipment_cancelled",
"source": "flipkart",
"version": "v3",
"timestamp": "2017-04-12T12:12:15+05:30",
"locationId" : "LOC1234",
"attributes": {
"status": "CANCELLED",
"orderItems": [{
"orderItemId": "6452425382623300",
"quantity": 1,
"reason": "seller_cancellation",
"subReason": "not_enough_inventory"
}]
},
"shipmentId": "6ddce370-20d3-426a-a095-431e840afe9b"
}……………………..
Request Body Parameters/Attributes
Flipkart Attributes | Eshopbox Attributes |
|---|---|
|
|
Response Body Parameters/Attributes
Flipkart Attributes | Eshopbox Attributes |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
https://api.flipkart.net/sellers/v3/shipments?orderItemIds={}