Listing Management API Reference For HyperLocal Marketplace¶
The Listing API is used to create and manage product offerings on Flipkart. The Listing API has the following entities:
- Listing: A listing is the fundamental sellable unit in the Flipkart Marketplace.
- Package: A package refers to the physical attributes of the listing.
- Location: Refers to your fulfillment locations. This is not applicable if you are planning to manage inventory via Flipkart.
POST /listings/v3/hyperlocal¶
- Summary:
- Create product listings in Flipkart’s HyperLocal Marketplace.
- Description:
This call creates new hyperlocal listings against the specified SKUs. If the SKU already exists in the system, then this call will overwrite the listing information associated with it. The rules for listing a product in the marketplace are subject to change, so it is recommended to handle errors explicitly. It is also recommended to call upon the validate API (to be announced) prior to making this call.
In addition to the authorization header, which is required for all Flipkart REST API calls, the following table includes additional headers required by this call:
Header Description Required Allowed Values Content-Type The MIME type of the body of the request. Must be JSON. Yes application/json; charset=utf-8 - Input:
- ☰ Toggle
Payload Model
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
{ "<sku>": { "product_id": "<product-id>", "price": { "mrp": 0, "selling_price": 0, "currency": "INR" }, "tax": { "hsn": "<harmonized-system-nomenclature>", "tax_code" : "<tax-code to determine goods>" }, "listing_status": "ACTIVE|INACTIVE", "package": { "name": "<package-identifier>", "dimensions": { "length": 1, "breadth": 1, "height": 1 }, "weight": 1, "description": "", "handling": { "fragile": true }, "notional_value": { "amount": 1, "unit": "PERCENTAGE|<CURRENCY>" } }, "location": { "id": "<location-id>", "status": "ENABLED|DISABLED", "inventory": 0 }, "address_label": { "manufacturer_details": [ "<address_of_manufacturer>" ], "importer_details": [ "<address_of_importer>" ], "packer_details": [ "<address_of_packer>" ], "countries_of_origin": [ "<iso_alpha2_code_of_country_of_origin>" ] }, "dating_label": { "mfg_date": "<Manufacturing date of the product in linux EPOCH (Seconds)>", "shelf_life": "<Shelf life of the product in Seconds>" } } }
Request field descriptions
The payload is a map of SKU identifiers to their corresponding CreateListingRequest. Max batch size allowed is “10”. The fields of the CreateListingRequest are described in the table below.
- Output:
- ☰ Toggle
Response Headers
Header Meaning Content-Type application/json; charset=utf-8 Status Codes
This call may return the HTTP status codes defined in the table below.
Status Interpretation 200 Success. Individual SKUs may have failed. The status
field has to be tested to determine the actual result.400 Bad Request 500 Internal Server Error Payload Model
- 200 OK
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "sku": { "status": "success|failure|warning", "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>" } ], "attribute_errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>", "attribute": "<attribute>", "path": "<path-to-attribute>" } ] } }
- 400 Bad Request
1 2 3 4 5 6 7 8 9 10
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>", "path": "<path-to-failed-json-node>" } ] }
- 500 Bad Request
1 2 3 4 5 6 7 8 9
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>" } ] }
Response field descriptions
The response is a map of SKU identifiers to their corresponding CreateListingResponse objects. The fields of the CreateListingResponse are defined in the table below.
Field Type Occurrence Description status Enumeration Mandatory Indicates the status of the request. errors Array Conditional Indicates errors encountered while processing the request, if any. errors[].severity Enumeration Mandatory The severity of the error. Warnings may require no further action. errors[].code Integer Mandatory The error code. errors[].description String Mandatory The error description. attribute_errors Array Conditional Indicates validation errors tied to a specified request attribute. attribute_errors[].severity Enumeration Mandatory The severity of the error. Warnings may require no further action. attribute_errors[].code Integer Mandatory The error code. attribute_errors[].description String Mandatory The error description. attribute_errors[].path String Mandatory The JSON path to the attribute.
POST /listings/v3/hyperlocal/update¶
- Summary:
- Update product listings in Flipkart’s HyperLocal Marketplace.
- Description:
This call updates listings against the specified SKUs. If the SKU doesn’t exist in the system, then an error will be returned against the SKU. The values that the listing attributes can take can change with time and selling constructs. It is recommended to explicitly handle errors and warnings returned by this API.
In addition to the authorization header, which is required for all Flipkart REST API calls, the following table includes additional headers required by this call:
Header Description Required Allowed Values Content-Type The MIME type of the body of the request. Must be JSON. Yes application/json; charset=utf-8 - Input:
- ☰ Toggle
Payload Model
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
{ "<sku>": { "product_id": "<product-id>", "price": { "mrp": 0, "selling_price": 0, "currency": "INR" }, "tax": { "hsn": "<harmonized-system-nomenclature>", "tax_code" : "<tax-code to determine goods>" }, "listing_status": "ACTIVE|INACTIVE", "package": { "name": "<package-identifier>", "dimensions": { "length": 1, "breadth": 1, "height": 1 }, "weight": 1, "description": "", "handling": { "fragile": true }, "notional_value": { "amount": 1, "unit": "PERCENTAGE|<CURRENCY>" } }, "location": { "id": "<location-id>", "status": "ENABLED|DISABLED", "inventory": 0 }, "address_label": { "manufacturer_details": [ "<address_of_manufacturer>" ], "importer_details": [ "<address_of_importer>" ], "packer_details": [ "<address_of_packer>" ], "countries_of_origin": [ "<iso_alpha2_code_of_country_of_origin>" ] }, "dating_label": { "mfg_date": "<Manufacturing date of the product in linux EPOCH (Seconds)>", "shelf_life": "<Shelf life of the product in Seconds>" } } }
Request field descriptions
The payload is a map of SKU identifiers to their corresponding CreateListingRequest. Max batch size allowed is “10”. The fields of the CreateListingRequest are described in the table below.
- Output:
- ☰ Toggle
Response Headers
Header Meaning Content-Type application/json; charset=utf-8 Status Codes
This call may return the HTTP status codes defined in the table below.
Status Interpretation 200 Success. Individual SKUs may have failed. The status
field has to be tested to determine the actual result.400 Bad Request 500 Internal Server Error Payload Model
- 200 OK
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "sku": { "status": "success|failure|warning", "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>" } ], "attribute_errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>", "attribute": "<attribute>", "path": "<path-to-attribute>" } ] } }
- 400 Bad Request
1 2 3 4 5 6 7 8 9 10
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>", "path": "<path-to-failed-json-node>" } ] }
- 500 Bad Request
1 2 3 4 5 6 7 8 9
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>" } ] }
Response field descriptions
The response is a map of SKU identifiers to their corresponding CreateListingResponse objects. The fields of the CreateListingResponse are defined in the table below.
Field Type Occurrence Description status Enumeration Mandatory Indicates the status of the request. errors Array Conditional Indicates errors encountered while processing the request, if any. errors[].severity Enumeration Mandatory The severity of the error. Warnings may require no further action. errors[].code Integer Mandatory The error code. errors[].description String Mandatory The error description. attribute_errors Array Conditional Indicates validation errors tied to a specified request attribute. attribute_errors[].severity Enumeration Mandatory The severity of the error. Warnings may require no further action. attribute_errors[].code Integer Mandatory The error code. attribute_errors[].description String Mandatory The error description. attribute_errors[].path String Mandatory The JSON path to the attribute.
GET /listings/v3/{sku-ids}
¶
- Summary:
- Retrieve the information listed against the provided SKU Ids.
- Description:
This call fetches the information listed against the specified SKUs. If the SKU does not exist in the system, then it will be identified in the
unavailable
field in the response.The authorization header is mandatory to access this API along with all other Flipkart Seller APIs.
- Input:
- ☰ Toggle
Request parameter descriptions
Parameter Type Occurrence Description sku-ids String Mandatory Comma-separated list of SKU Ids. Maximum per call: 10. - Output:
- ☰ Toggle
Response Headers
Header Meaning Content-Type application/json; charset=utf-8 Status Codes
This call may return the HTTP status codes defined in the table below.
Status Interpretation 200 Success. 400 Bad Request 500 Internal Server Error Payload Model
- 200 OK
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
{ "available": { "sku": { "listing_id": "<flipkart-system-identifier>", "product_id": "<flipkart-product-identifier>", "price": { "mrp": 0, "flipkart_selling_price": 0, "currency": "INR" }, "tax": { "hsn": "<hsn-code>", "tax_code" : "<tax-code>" }, "listing_status": "ACTIVE|INACTIVE", "shipping_fees": { "local": 0, "zonal": 0, "national": 0, "currency": "INR" }, "marketplace": "FLIPKART", "fulfillment_profile": "NON_FBF|FBF_LITE|FBF", "fulfillment": { "dispatch_sla": 1, "shipping_provider": "FLIPKART|SELLER|FLIPKART_SELLER", "forbid_shipping": "NATIONAL|ZONAL|LOCAL", "procurement_type": "REGULAR|EXPRESS|INTERNATIONAL|MADE_TO_ORDER|DOMESTIC" }, "packages": [ { "id": "<flipkart-system-identifier>", "name": "<name>", "dimensions": { "length": 1, "breadth": 1, "height": 1 }, "weight": 1, "description": "<description>", "handling": { "fragile": true }, "notional_value": { "amount": 1, "unit": "PERCENTAGE|<CURRENCY>" } } ], "locations": [ { "id": "<location-id>", "status": "ENABLED|DISABLED", "inventory": 0 } ], "address_label": { "manufacturer_details": [ "<address_of_manufacturer>" ], "importer_details": [ "<address_of_importer>" ], "packer_details": [ "<address_of_packer>" ], "countries_of_origin": [ "<iso_alpha2_code_of_country_of_origin>" ] }, "dating_label": { "mfg_date": "<Manufacturing date of the product in linux EPOCH (Seconds)>", "shelf_life": "<Shelf life of the product in Seconds>", "expiry_date": "<Expiry date of the product in linux EPOCH (Seconds)>" }, "archived_status": "ARCHIVED|NONE" }, "orders_to_be_fulfilled": 0 }, "unavailable": [ "<sku1>", "<sku2>" ], "invalid": [ "<sku>" ] }
- 400 Bad Request
1 2 3 4 5 6 7 8 9 10
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>", "path": "<path-to-failed-json-node>" } ] }
- 500 Bad Request
1 2 3 4 5 6 7 8 9
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>" } ] }
Response field descriptions
Field Type Occurrence Description available Map Conditional Holds the listing information for the requested SKU Ids. unavailable List Conditional The list of SKU Ids for which listing information could not be retrieved. invalid List Conditional The list of SKU Ids which are invalid according to the contracts’ specifications.
POST /listings/v3/update/price¶
- Summary:
- Update product listings’ price.
- Description:
This call updates listing’s price against the specified SKUs. If the SKU doesn’t exist in the system, then an error will be returned against the SKU. The values that the listing attributes can take can change with time and selling constructs. It is recommended to explicitly handle errors and warnings returned by this API.
In addition to the authorization header, which is required for all Flipkart REST API calls, the following table includes additional headers required by this call:
Header Description Required Allowed Values Content-Type The MIME type of the body of the request. Must be JSON. Yes application/json; charset=utf-8 - Input:
- ☰ Toggle
Payload Model
1 2 3 4 5 6 7 8 9 10
{ "<sku>": { "product_id": "<product_id>", "price": { "mrp": 0, "selling_price": 0, "currency": "INR" } } }
Request field descriptions
The payload is a map of SKU identifiers to their corresponding update price request. Max batch size allowed is “10”. The fields of the update price request are described in the table below.
Field Type Occurrence Description product_id String Mandatory This is the product’s identifier in the Flipkart Marketplace. Length Range -> 13 to 16 characters. price.mrp Non-negative Integer Mandatory The maximum retail price for the product price.sellingPrice Positive Integer Mandatory Your selling price for the product price.currency Enumeration Mandatory Currency represents the symbol of country currency - Output:
- ☰ Toggle
Response Headers
Header Meaning Content-Type application/json; charset=utf-8 Status Codes
This call may return the HTTP status codes defined in the table below.
Status Interpretation 200 Success. IndividualSKUs may have failed. The status
field has to be tested to determine the actual result.400 Bad Request 500 Internal ServerError Payload Model
- 200 OK
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "sku": { "status": "success|failure|warning", "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>" } ], "attribute_errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>", "attribute": "<attribute>", "path": "<path-to-attribute>" } ] } }
- 400 Bad Request
1 2 3 4 5 6 7 8 9 10
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>", "path": "<path-to-failed-json-node>" } ] }
- 500 Bad Request
1 2 3 4 5 6 7 8 9
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>" } ] }
Response field descriptions
The response is a map of SKU identifiers to their corresponding update listing response objects. The fields of the update listing response are defined in the table below.
Field Type Occurrence Description status Enumeration Mandatory Indicates the status of the request. errors Array Conditional Indicates errors encountered while processing the request, if any. errors[].severity Enumeration Mandatory The severity of the error. Warnings may require no further action. errors[].code Integer Mandatory The error code. errors[].description String Mandatory The error description. attribute_errors Array Conditional Indicates validation errors tied to a specified request attribute. attribute_errors[].severity Enumeration Mandatory The severity of the error. Warnings may require no further action. attribute_errors[].code Integer Mandatory The error code. attribute_errors[].description String Mandatory The error description. attribute_errors[].path String Mandatory The JSON path to the attribute.
POST /listings/v3/update/inventory¶
- Summary:
- Update product listing’s inventory.
- Description:
This call updates listing’s inventory against the specified SKUs. If the SKU doesn’t exist in the system, then an error will be returned against the SKU. The values that the listing attributes can take can change with time and selling constructs. It is recommended to explicitly handle errors and warnings returned by this API.
In addition to the authorization header, which is required for all Flipkart REST API calls, the following table includes additional headers required by this call:
Header Description Required Allowed Values Content-Type The MIME type of the body of the request. Must be JSON. Yes application/json; charset=utf-8 - Input:
- ☰ Toggle
Payload Model
1 2 3 4 5 6 7 8 9 10 11
{ "<sku>": { "product_id": "<product_id>", "locations": [ { "id": "<location-id>", "inventory": 0 } ] } }
Request field descriptions
The payload is a map of SKU identifiers to their corresponding update inventory request. Max batch size allowed is “10”. The fields of the update inventory request are described in the table below.
Field Type Occurrence Description product_id String Mandatory This is the product’s identifier in the Flipkart Marketplace. Length Range -> 13 to 16 characters. locations Array Mandatory Your selling locations for this listing. locations[].id String Mandatory The location ID obtained via the Onboarding API. locations[].inventory Non-negative Integer Mandatory The available inventory at this location. - Output:
- ☰ Toggle
Response Headers
Header Meaning Content-Type application/json; charset=utf-8 Status Codes
This call may return the HTTP status codes defined in the table below.
Status Interpretation 200 Success. IndividualSKUs may have failed. The status
field has to be tested to determine the actual result.400 Bad Request 500 Internal ServerError Payload Model
- 200 OK
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "sku": { "status": "success|failure|warning", "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>" } ], "attribute_errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>", "attribute": "<attribute>", "path": "<path-to-attribute>" } ] } }
- 400 Bad Request
1 2 3 4 5 6 7 8 9 10
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>", "path": "<path-to-failed-json-node>" } ] }
- 500 Bad Request
1 2 3 4 5 6 7 8 9
{ "errors": [ { "severity": "ERROR|WARNING", "code": "<code>", "description": "<description>" } ] }
Response field descriptions
The response is a map of SKU identifiers to their corresponding update listing response objects. The fields of the update listing response are defined in the table below.
Field Type Occurrence Description status Enumeration Mandatory Indicates the status of the request. errors Array Conditional Indicates errors encountered while processing the request, if any. errors[].severity Enumeration Mandatory The severity of the error. Warnings may require no further action. errors[].code Integer Mandatory The error code. errors[].description String Mandatory The error description. attribute_errors Array Conditional Indicates validation errors tied to a specified request attribute. attribute_errors[].severity Enumeration Mandatory The severity of the error. Warnings may require no further action. attribute_errors[].code Integer Mandatory The error code. attribute_errors[].description String Mandatory The error description. attribute_errors[].path String Mandatory The JSON path to the attribute.