Flipkart Marketplace Seller APIs¶

The Flipkart Marketplace Seller APIs allow a seller’s applications to programmatically access and exchange data with the Flipkart Marketplace. They help automate business processes associated with selling on the Marketplace. A seller can use these APIs to search orders, print shipping labels and invoices, and manage orders at different stages of the order life cycle.

Seller Registration¶

To start working with seller APIs, first register as a seller with the Marketplace at https://seller.flipkart.com.

Note

The username and password provided during the registration process on seller dashboard does not provide API access

API Application Setup¶

As a registered seller you can log into the Seller Dashboard > Manage Profile > Developer Access to create self access applications and to manage 3rd party API application access.

Important

Testing the application integration in the sandbox setup is prerequisite to implementing it in a live (production) setup. Both setups use the OAuth framework.
All seller APIs must be HTTPS requests. HTTP requests are not supported.
Do not hard-code the Access Token value in the Authorization header as the token expires after some time - usually, 60days. If an expired Access Token is used, API requests would fail with 401 HTTP status code. You must regenerate the access token in such a scenario and use the new one in subsequent requests. Refer Generating Access Tokens for details.

Sandbox Environment¶

The sandbox is a staging setup where you can design, program, and test applications in a controlled environment before implementing them in the production environment. Products listed in this environment are not real; however, changing the base URL to that of the production environment enables the applications to go live with real products and users.

Production Environment¶

The production environment is the live Flipkart platform. Products listed in this environment are available to real Flipkart users. The information provided for this environment is governed by the Flipkart Marketplace terms of usage (TOU).

Application Registration¶

Self Access Application - For Sellers own use

Steps to set-up Self Access Application:

Log into the Seller Dashboard portal.

Go to Manage Profile > Developer Access

Click Create New Access

Provide following details

Application Name - Any text identifier name for your application

Application Description - Text to describe the use of Seller APIs

Click Submit. The new application is now added to your applications list and a unique Application ID (<appid>) and Application Secret (<app-secret>) pair is assigned.

Kindly refer to Client Credentials Flow(for Self Access Application) Flow to understand access token generations

Sandbox: Raise a ticket through the seller or partner portal under API GA node to get your credentials to log into Sandbox environment

Important note: Do not share the self access application details with any 3rd party partner(s) / aggregator. It is meant strictly for self seller use. Violations will lead to seller account deactivation.

Third Party Access Application - For Partners / Aggregator

Steps to set-up Third Party Access Application:

Register yourself on Partner Dashboard portal.

While registering, select Yes to the question on whether you’re an API Partner

Once registered, Flipkart team will reach out to verify your details within 72 hours.

Once your profile is verified, you will be allowed to create a Third party Client

To create a Third Party Application Go to Profile > Manage API Access

Click on Create Application

Provide following details:

Application Name: The name of your third-party application.

Application Description: Relevant description for your application.

Redirect URL: The URL to which Flipkart will redirect the browser after authorization has been granted by the seller. Please note that the redirection link has to be strictly a valid https link.

Click Create Application. The new application is now added to your applications list and a unique Application ID (<appid>) and Application Secret (<app-secret>) pair is assigned.

Kindly refer to Authorization Code Flow (For Third Party Application) to understand seller onboarding on the application created

Sandbox: Raise a ticket through the seller or partner portal under API GA node to get your credentials to log into Sandbox environment

Please note: Partner / Aggregator are strictly to use Third party Application. Any volition will lead to permanent ban on Flipkart.

Note

Application ID (appid) mentioned above and client_id used in the below mentioned OAuth APIs refers to the same thing.

Generating Access Tokens¶

Once your application is registered, you need to generate an access token to be able to call the APIs. Flipkart API Authorization framework supports two grant types to generate access tokens namely, the Client Credentials (for Self access application) and Authorization Code (for third party application) flows.

Notes

Only an authorized user once approved by Flipkart has access to use tokens. Below are the following grant_type:
   * authorization_code,
   * client_credentials,
   * implicit,
   * password,
   * refresh_token

Client Credentials Flow(for Self Access Application)¶

This flow should be used if you are a registered seller on Flipkart Marketplace and want to integrate with the APIs for your own orders and listings management.

To generate access tokens using the client_credentials flow, below API should be used. You can write code in language of your choice to make a REST call or use curl to get the access tokens.

GET /oauth-service/oauth/token?grant_type=client_credentials&scope=Seller_Api,Default

This API is authenticated using Basic Access Authentication mechanism and so the required Authorization header is expected. credentials to be used in header is base64 encoding of your appId and appSecret separated by a colon (:).

e.g. if your registered application appId is my-appId-1 and appSecret is my-app-secret-1, the credential to be used for Basic authentication would be the base64 encoding of my-appId-1:my-app-secret-1

Examples

Postman

Using Postman is one of the easiest way to generate an access token and manually test and get a hang of the APIs. This screenshot of Postman can be referred to for building the request. As can be seen here, the appId and appSecret can directly be used as the Username and Password after selecting Basic Auth as the Authorization Type. Postman will take care of doing the base64 encoding and setting appropriate headers.

Java

If you are using Java, you can use the access token generation code which is bundled with the API client provided by us. Refer to API Integration section below for more details.

Alternatively, here is a sample Java code which you can embed in your application to generate access tokens.

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

Note

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)

C#

using System;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;
using RestSharp;

namespace fk_api_client_dotnet
{
    class Program
    {
        static string clientId = "__CLIENT_ID__";           // Replace with your application id or client id
        static string clientSecret = "__CLIENT_SECRET__";   // Replace with your application secret or client secret
        static string credentials = Base64Encode(clientId + ":" + clientSecret);

        static void Main(string[] args)
        {

            var client = new RestClient("https://sandbox-api.flipkart.net/oauth-service/oauth/token?grant_type=client_credentials&scope=Seller_Api");
            var request = new RestRequest(Method.GET);
            request.AddHeader("Authorization", "Basic " + credentials);
            IRestResponse response = client.Execute(request);

            var _snakeSettings = new JsonSerializerSettings()
            {
                ContractResolver = new UnderscorePropertyNamesContractResolver()
            };

            var accessTokenResponse = JsonConvert.DeserializeObject<AccessTokenResponse>(response.Content, _snakeSettings);
            Console.WriteLine("Your access token is : " + accessTokenResponse.accessToken);
        }

        public class UnderscorePropertyNamesContractResolver : DefaultContractResolver
        {
            public UnderscorePropertyNamesContractResolver()
            {
                NamingStrategy = new SnakeCaseNamingStrategy();
            }
        }

        private static string Base64Encode(string plainText) {
            var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText);
            return System.Convert.ToBase64String(plainTextBytes);
        }

        public class AccessTokenResponse
        {
            public string accessToken { get; set;}
        }
    }
}

Note

You need to add a dependency on RestSharp package for the above code to run. Kindly refer to RestSharp documentation for more info.

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

Authorization Code Flow (For Third Party Application)¶

This flow should be used if you are a an partner/aggregator or a vendor and is going to manage API on behalf of other sellers registered on Flipkart Marketplace.

Note

If you are a registered seller on Flipkart Marketplace and want to integrate with APIs for your own orders and listings management, kindly refer to Client Credentials Flow(for Self Access Application)

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: Your application’s Client ID. You can find this value in Seller APIs - Developer Admin portal

redirect-uri: The URL to which Flipkart will redirect the browser after authorization has been granted by the seller. The Authorization Code will be available in the code URL parameter. This URL must be specified as a valid callback URL while creating application in Seller APIs - Developer Admin portal.

state: An opaque value (random text field) which your application should add to the initial request and that Flipkart also includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks. For more information, see authorization request .

Seller must login to the Flipkart Permission Registration page that appears using his/her login credentials.

Flipkart Permission Registration page

After successful login, seller would be presented with a Request for Authorization dialog. Upon clicking the Allow button, seller would be redirected to the redirect_uri, with authorization code and state as URL parameters.

Request for Authorization page

Exchange the Authorization Code for an Access Token

Now that you have an Authorization Code, you must exchange it for an Access Token that can be used to call the Flipkart Orders and Listing APIs. Using the Authorization Code (code) from the previous step, you will need to send it to the Token URL.

Token URL
https://sandbox-api.flipkart.net/oauth-service/oauth/token?
redirect_uri=<redirect-uri>&
grant_type=authorization_code&
state=<state>&
code=<code>
Sample Code

For sample code in Java, Python and C#, kindly refer to the Examples in Client Credentials Flow(for Self Access Application) . You just need to replace the URL in the code with the Token URL.

curl
curl -u <appid>:<app-secret> https://sandbox-api.flipkart.net/oauth-service/oauth/token?redirect_uri=<redirect-uri>&grant_type=authorization_code&state=<state>&code=<code>
Sample response
{
  "access_token": "f638949ac9794172b33c23311a168647",
  "token_type": "bearer",
  "refresh_token": "860e03dad58a49889149-a4a7f365bba1",
  "expires_in": 5183999,
  "scope": "Seller_Api"
}

Generating Access Tokens using Refresh Token¶

Sellers are also able to generate an access token by refresh token. Validity for access token is 60 days and for refresh token it is 180 days.
The grant_type should be refresh_token and only Flipkart approved sellers can use the access token.
When the validity of the refresh token expires, the sellers have to request to generate the access token again. After that, sellers get a new access token and a refresh token.
☰ SHOW | HIDE
1. Call the authentication API. You can write code in any language to make a REST call or use curl to get the access tokens.
  
  oauth/token?grant_type=refresh_token&refresh_token=<refresh_token>
2. Set your Application ID and Application Secret in the header for Basic Authentication.
  
  Sample header for production
  
  curl -u <appid>:<app-secret> https://api.flipkart.net/oauth-service/oauth/token?grant_type=refresh_token&refresh_token=<refresh_token>
  
  Sample response
  
  {"access_token":"<token>","token_type":"bearer","refresh_token":"<refresh_token>","expires_in":3330779,"scope":Seller_Api"}

API Integration¶

Once the Access Token has been obtained it can be used to make calls to the API by passing it as a Bearer Token in the Authorization header of the HTTP request. To integrate with the Flipkart Marketplace Seller APIs provided in this documentation, you could go through this API documentation and create your own application.

However, the recommended way to integrate is to use auto-generated client code by using the Swagger spec. To ease the process, we are providing a sample java application which you can refer and start integration using the api client included in it. If you are using any other language, you can use swagger-codegen to auto generate the client code for that language. Steps to install swagger-codegen can be followed from the official documentation page.

Code Generation¶

Python

swagger-codegen generate -i https://sandbox-api.flipkart.net/swagger/swagger.json -l python -o flipkart-seller-api-client-python

C#

swagger-codegen generate -i https://sandbox-api.flipkart.net/swagger/swagger.json -l csharp -o flipkart-seller-api-client-csharp

Sample API Call¶

This is a sample code in Java which can be used to fetch the details of a shipment. This code is also provided in the above linked sample Java application.

package com.flipkart.api.seller;

import com.flipkart.api.seller.v3client.api.ShipmentV3Api;
import com.flipkart.api.seller.v3client.model.ShipmentResponse;

public class MyFlipkartOrdersApplication {

  public static void main(String[] args) {
    String accessToken = AccessTokenGenerator.getClientCredentialsAccessToken();  // You need to write custom code for token generation if you are using your own auto-generated client code.
    ApiClient apiClient = new ApiClient();
    apiClient.setAccessToken(accessToken);
    ShipmentV3Api shipmentV3Api = new ShipmentV3Api(apiClient);
    String shipmentId = "__SHIPMENT_ID__";

    try {
      ShipmentResponse shipmentResponse = shipmentV3Api
          .getShipmentDetailsByInternalId(shipmentId, null, null);
      System.out.println("Order Id for shipment is " + shipmentResponse.getShipments().get(0).getOrderItems().get(0).getOrderId());
    } catch (ApiException e) {
      e.printStackTrace();
    }

  }
}

If you are creating your own custom application, you can refer to below curl command. The following sample calls the Filter Shipments API in the sandbox environment on providing a valid <token> value. You can change the URL to https://api.flipkart.net/sellers/orders/search to call the API in production.

curl -H"Authorization:Bearer <token>"-H"Content-Type: application/json" -d '{"filter" :{}}' https://sandbox-api.flipkart.net/sellers/v3/shipments/filter