Order Management API Reference

You can use the following APIs to create, receive, send, and work with various order related details.

POST /orders/search

Description - The Search Orders API searches order items using specific filters. It gets order items and their details based on the order date, dispatch date, order states, and seller SKU ID. The first call to the Search API returns a finite number of results based on the pageSize value. Calling the URL returned in the nextPageURL field of the response gets the subsequent pages of the search result. The response of the Search API contains a list of order items and their sub-items (freebies), to be packed together in one shipment, for which only one label is generated.

Request and Response Parameters

☰ SHOW | HIDE

URL: https://api.flipkart.net/sellers/v2/orders/search

Request Body Parameter: filter

Parameter/Attribute Type Requirement Description
  • orderDate:
    • fromDate
    • toDate
String Optional Filter based on orders placed within the selected date range, where the date strings are in ISO format
  • dispatchAfterDate:
    • fromDate
    • toDate
String Optional Filter based on orders to be processed within the selected date range, where the date strings are in ISO format
  • dispatchByDate:
    • fromDate
    • toDate
String Optional Filter based on orders to be dispatched within the selected date range, where the date strings are in ISO format
  • modifiedDate:
    • fromDate
    • toDate
String Optional Filter for orders that were modified within the selected date range, where the date strings are in ISO format
states List<String> Optional Filter orders based on a comma separated list of valid order states. Filtering based on processing states is not supported now. Possible values: APPROVED,``PACKED``, READY_TO_DISPATCH, and CANCELLED
sku List<String> Optional Filter orders based on a comma separated list of seller SKUs

Request Body Parameter: pagination

Parameter Type Requirement Description
pageSize Numeric Optional Number of search results to display in one page. Maximum size is 20

Request Body Parameter: sort

Parameter Type Requirement Description
field ISO String Optional Sort results by orderDate or dispatchByDate
order String Optional Sort results by desc or asc

Validations

pageSize: Value between 1 and 20
states: Options are APPROVED, PACKED, READY_TO_DISPATCH, CANCELLED
filter: All filters are optional
sort field: Can be orderDate or dispatchByDate

Note

  • Provides only those orders that are fulfilled based on the seller’s fulfillment service. Flipkart Advantage (FA) orders are not shown.
  • The default sort order is by dispatchByDate (to be marked “Ready to Dispatch”).
  • If the date strings do not contain timezone information, it is assumed as IST.

Response Body Parameters:

Parameter/Attribute/Field Type Description
hasMore Boolean A flag to indicate whethere there are more search results in the next page
orderItems List A comma separated list of order items
orderItemId String The primary identifier for seller actions
orderId String System generated order ID for the buyer
status String The current order processing status. Possible values: APPROVED, PACKING_IN_PROGRESS, PACKED, READY_TO_DISPATCH, PICKUP_COMPLETE, CANCELLED, SHIPPED, DELIVERED, RETURN_REQUESTED, RETURNED
sla Integer Order item specific SLA
quantity Integer Number of units ordered of a particular order item
title String Product listing title
listingId String Product listing ID
fsn String Flipkart system generated serial number used as a product identifier
sku String Seller SKU for the listing
priceComponenets.``sellingPrice`` Float Product price listed by the seller. This value can be less than or equal to the MRP
priceComponents.``customerPrice`` Float The price at which buyer bought the order item from the Website (sellingPrice - promotionDiscount)
priceComponents.``shippingCharge`` Float Shipping charge per unit
priceComponents.``totalPrice`` Float The price paid by the customer per unit (customerPrice + shippingCharge)
stateDocuments List<String> List of state documents to be attached with the shipment
subItems List<orderItem> Freebies associated with the order item. Note: Freebies must be shipped along with the primary order item
orderDate ISO String Date on which the order was placed
dispatchAfterDate ISO String Date after which the order items needs to be processed by the seller
dispatchByDate ISO String Date by which the order items needs to be dispatched by the seller
updatedAt ISO String Timestamp of the last update for a particular order item
url String A GET call on this URL fetches the current page results
nextPageUrl String A GET call on this URL fetches the next page results. Not present for the last page
previousPageUrl String A GET call on this URL fetches the previous page results. Not present for the first page

Possible Error Response Codes

Error Codes Reason for Error
INVALID_REQUEST_PAGE_SIZE Validation failure of the requested pageSize value
INVALID_REQUEST_STATE Validation failure of the selected state
INVALID_REQUEST_JSON JSON parsing failure of the request
INVALID_DATE_FORMAT Parsing failure of the from or to dates

GET /orders/{orderItemId}

Description - The Get by OrderItemId API gets the order item detail by orderItemId. It returns the order item with the specified orderItemId and all its sub-items, if any.

Request and Response Parameters

☰ SHOW | HIDE

URL: https://api.flipkart.net/sellers/v2/orders/{orderItemId}

Request Header Parameters

Query Parameter Requirement Description
orderItemId Mandatory orderItemId of the primary order item

Validations

orderItemId: should be a valid order item id for the seller.

Response Body Parameters:

Parameter/Attribute/Field Type Description
orderItemId String The primary identifier for seller actions an order item and associated attributes
orderId String System generated order ID for the buyer
status String The current order processing status. Possible values: APPROVED, PACKING_IN_PROGRESS, PACKED, READY_TO_DISPATCH, PICKUP_COMPLETE, CANCELLED, SHIPPED, DELIVERED, RETURN_REQUESTED, RETURNED
hold Boolean Flag (true or false) for order verification process
orderDate ISO String Date on which the order was placed
dispatchAfterDate ISO String Date after which the order items needs to be processed by the seller
dispatchByDate ISO String Date by which the order items needs to be dispatched by the seller
sla Integer Allowed SLA for a particular order item
quantity Integer Number of units ordered for this order item
title String Product listing title
listingId String Product listing ID
fsn String Flipkart system generated serial number used as a product identifier
sku String Seller SKU for the listing
shippingPinCode String Postal address pin code
stateDocuments List<String> List of state documents to be attached with the shipment
subItems List<orderItem> Freebies associated with the order item. Note: Freebies must be shipped along with the primary order item

Possible Error Response Codes

Error Codes Reason for Error
INVALID_ITEM_ID The orderItemId passed in the path does not exist or is invalid for this seller

GET /orders/

Description - The Get by OrderItemIds API gets order item details for multiple order items based on the specified orderItemIds.

Request and Response Parameters

☰ SHOW | HIDE

URL: https://api.flipkart.net/sellers/v2/orders/?orderItemIds={id1,id2,...}

Request Header Parameters

Parameter Requirement Description
orderItemIds Mandatory Comma separated list of orderItemIds

Response Body Parameters:

Parameter/Attribute/Field Type Description
orderItemId String The primary identifier for seller actions for an order item and associated attributes
orderId String System generated order ID for the buyer
status String The current order processing status. Possible values: APPROVED, PACKING_IN_PROGRESS, PACKED, READY_TO_DISPATCH, PICKUP_COMPLETE, CANCELLED, SHIPPED, DELIVERED, RETURN_REQUESTED, RETURNED
hold Boolean Flag (true or false) for order verification process
orderDate ISO String Date on which the order was placed
dispatchAfterDate ISO String Date after which the order items needs to processed by the seller
dispatchByDate ISO String Date by which the order items needs to be dispatched by the seller
sla Integer Allowed SLA for this order item
quantity Integer Number of units ordered for this order item
title String Product listing title
listingId String Product listing ID
fsn String Flipkart product identifier
sku String Seller SKU for the listing
price Integer Total price of the order item Note: To be deprecated soon
shippingFee Float Shipping charge per unit Note: To be deprecated soon
shippingPinCode String Postal address pin code
stateDocuments List<String> List of state documents to be attached with the shipment
subItems List<orderItem> Freebies associated with the order item. Note: Freebies must be shipped along with the primary order item

POST /orders/labels

Description - The Label Generation API (also known as the Pack API) generates invoice and shipping labels for the order items and marks order items as packed. It takes the invoice details in the request as input. If the orderItemId requires a serial number or IMEI number (also known as serialized product), that input is also required when calling this API.

Request and Response Parameters

☰ SHOW | HIDE

URL: https://api.flipkart.net/sellers/v2/orders/labels

Request Body Parameter

Parameter Type Requirement Description
orderItemID String Mandatory The orderItemId of the primary item
serialNumbers
List<List
<String>>
Mandatory if the item needs FSN (IMEI) else, Optional To specify FSN, ISBN or IMEI, as applicable
invoiceDate ISO String Mandatory Date on which the seller invoice was generated
invoiceNumber String Optional Invoice number
taxRate Numeric Mandatory Tax rate for the item
subItems List Optional List of freebies items and details returned by the POST /orders/search

Validations

orderItemId: should be a valid order item id for this seller.
invoiceDate: should be a valid date in the format YYYY-MM-DD and should be between order date and current date
taxRate: should be a value between 0 and 100.

Response Structure

Response Code Description
200 The label generation request processed succesfully. Response object contains details about validations.

Possible Error Response Codes

Error Codes Reason for Error
INVALID_REQUEST_ITEM_ID Item ID passed in the request does not exist
INVALID_REQUEST_TAX Validation failure for the tax value
INVALID_ITEM_STATE Order item is not ready to be packed
INVALID_REQUEST_JSON JSON parsing failure of the request
INVALID_REQUEST_DATE_FORMAT Parsing failure of the invoice date format (should be YYYY:MM:DD)

GET /orders/labels?orderItemIds={id list}

Description - The Download Labels API prints integrated shipping label and invoice (optional) for packed items. The invoice is printed only if the seller opts for the auto-invoicing solution. The shipping labels and customer invoices can be printed for multiple order items. It produces a single, merged PDF, if multiple order item IDs are passed in the request parameters.

Request and Response Parameters

☰ SHOW | HIDE

URL: https://api.flipkart.net/sellers/v2/orders/labels?orderItemId={id1,id2,..}

Request Header Parameters

Query Parameter Requirement Description
orderItemIds Mandatory Prints integrated shipping label (PDF) for multiple orderItemIds and their sub-items

Validations

orderItemIds: should be a valid order item ids for this seller and the label

Possible Error Response Codes

Error Codes Reason for Error
INVALID_REQUEST_ITEM_ID The item ID passed in the request does not exist
INTERNAL_SERVER_ERROR An error in generating labels

POST /orders/dispatch

Description - The Dispatch Orders API marks order items as “Ready to Dispatch” and communicates to the logistics partners that the order is ready for pick up.

Request and Response Parameters

☰ SHOW | HIDE

URL: https://api.flipkart.net/sellers/v2/orders/dispatch

Request Body Parameters: orderItems

Parameter Type Requirement Description
orderItemId String Mandatory The orderItemId to be marked as “Ready to dispatch”
quantity Numeric Mandatory Number of units of the orderItem to be dispatched

Possible Response Error Codes

Error Code Reason for error
INVALID_ITEM_ID The orderItemId passed in the request header does not exist
INTERNAL_SERVER_ERROR Server error (5xx) encountered when generating labels
QUANTITY_MISMATCH_ERROR The item quantity in the request did not match with the actual quantity
ORDER_ITEM_ALREADY_DISPATCHED Cannot mark a dispatched order item as “Ready to Dispatch”
ORDER_ITEM_ALREADY_CANCELLED Cannot mark a cancelled order item as “Ready to Dispatch”
ORDER_ITEM_NOT_PACKED Cannot mark an order item that is not packed as “Ready to Dispatch”

GET /orders/manifest

Description - The Manifest API returns a PDF file with a list of orders ready to handover to the logistics team.

Request and Response Parameters

☰ SHOW | HIDE

URL: ``https://api.flipkart.net/sellers/v2/orders/manifest`

Request Header Parameters

N.A.


GET /orders/shipments?orderItemIds={id list}

Description - The Shipments API gives the shipping details for multiple order items based on the specified orderItemIds. The recommended limit is 25 orderItemIds.

Request and Response Parameters

☰ SHOW | HIDE

URL: https://api.flipkart.net/sellers/v2/orders/shipments?orderItemsIds={id1,id2...}

Request Header Parameters

URL Parameter Type Requirement Description
orderItemsIds String Mandatory Comma separated list of order item IDs for which shipment information is queried

Possible Response Error Codes

Error Code Reason for error
INVALID_ITEM_ID The item ID passed in the request header does not exist

GET /orders/invoices

Description - The Invoices API gives the invoice details of order items.

Request and Response Parameters

☰ SHOW | HIDE

URL: https://api.flipkart.net/sellers/v2/orders/invoices?orderItemsIds={id1,id2...}

Request Header Parameters

URL Parameter Type Requirement Description
orderItemsIds String Mandatory Comma separated list of order item IDs for which invoice details is needed

Possible Response Error Codes

Error Code Reason for error
INVALID_ITEM_ID The item ID passed in the request header does not exist

POST /orders/cancel

Description - The Cancel Orders API enables the seller to cancel an order that may already have been approved by the Flipkart Marketplace.

Request and Response Parameters

☰ SHOW | HIDE

URL: https://api.flipkart.net/sellers/v2/orders/cancel

Request Body Parameters

Parameter Type Requirement Description
orderItemId Long Mandatory orderItemId of the primary item cancelled
reason String Optional Reason for cancellation. Permitted values: cannot_procure_item, not_enough_inventory, and b2b_order

GET /returns

Description - The Get Returns API provides details of an order item returned by the buyer or undelivered by the courier, and the reason for return.

Request and Response Parameters

☰ SHOW | HIDE

URL: http://api.flipkart.net/sellers/v2/returns?source={source_mode}&modifiedAfter={date}&createdAfter={date}

Request Header Parameters

Parameter Type Requirement Description
source String Mandatory Source of the returns. Possible values: customer_return, courier_return
modifiedAfter ISO String Optional Get the returns details for orders modified after the date specified
createdAfter ISO String Optional Get the returns details for orders created after the date specified

GET /returns?returnIds={id list}

Description - The Get Returns by returnIds API provides details of returns.

Request and Response Parameters

☰ SHOW | HIDE

URL: http://api.flipkart.net/sellers/v2/returns?returnIds={id list}

Request Header Parameters

Parameter Type Requirement Description
returnIds String Mandatory Comma separated list of returnsIds.

POST /shipments/dispatch

Description - Self Ship API to mark items as dispatched from the seller warehouse. In addition to marking items as dispatched from the warehouse, seller must enter invoice details.

POST /shipments/delivery

Description - Self Ship API to mark items as delivered to the buyer.

POST /shipments/deliveryAttempt

Description - Self Ship API to mark an attempted delivery. The next delivery date must be mentioned.

POST /services/attempt

Description - API to mark service attempt done by the service partner. The next scheduled service date is also marked.

POST /services/complete

Description - Self Ship API to mark a service as completed with the details of service.

POST /returns/approve

Description - Self Ship API to approve returns requested by the buyer with or without tech visit.

POST /returns/reject

Description - Self Ship API to mark returns requested by the buyer as rejected. Tech visit service is madatory to reject the returns.

POST /returns/complete

Description - Self Ship API to acknowledge completion of returns to the seller warehouse.

POST /returns/pickup

Description - Selfship API to mark item as picked up from the buyer.

POST /returns/pickupAttempt

Description - Self Ship API to mark attempted pickup of the item from the buyer. The next pickup by date must be mentioned.