Order Management API

API Test Environment

To access and test the Order Management pull APIs in sandbox, click here.

This section familiarizes you with the different types of order fulfilment workflows and their corresponding APIs. Let’s first understand a few basic terminologies around orders:

• Order : An order represents all the products that a customer has ordered in a checkout session. One order can have multiple products which can be fulfilled by different sellers on the marketplace.
• Order Item : An order item represents a particular product in a given order. An order item can have multiple quantities of a product in it.
• Shipment : A shipment is a group of order items that the seller needs to pick, pack and handover together to a logistics partner.

Note

• A single customer order can be splitted into multiple shipments even though all the products are from the same seller.
• A shipment can have multiple order item ids(products) of the same order/customer.
• A shipment cannot have order item ids of multiple orders/customers.

Most of the Flipkart Order Management API interactions happen on the shipment as this is the logical unit that the seller needs to pick, pack and handover together to a logistics partner.

Once the customer places an order on a seller’s listing, Flipkart systems decide on which location (i.e if the seller has the same listing across multiple locations) of the seller this order needs to go basis the fastest delivery time to the customer. Hence, every order is allocated to a seller location and the seller has to fulfil that order via the same location.

Note

• There is no construct of order acceptance via seller i.e if the seller has a positive inventory for a listing on a location and if a customer places the order on that listing then the seller has to fulfil that order via the Flipkart decided location.
• Failing to process orders will lead to seller account/location level actions and the seller will not be allowed to sell on Flipkart for some duration of time.

Once the order is placed by the customer it is assigned to the seller location for the fulfilment. As of now, Flipkart supports two types of order fulfilment workflows via APIs.

• Standard Fulfilment : This is the fulfilment where logistics of order fulfilment is taken care of by Flipkart. The seller has to just pack and handover the products to the Flipkart assigned delivery partner.
• Self Ship Fulfilment : This is the fulfilment order where logistics of order fulfilment is taken care by Seller himself i.e seller packs, dispatches, delivers, and handles post-delivery services of an order on its own.

Standard Fulfilment

☰ SHOW | HIDE

This section familiarizes you with the standard order fulfilment workflow with possible seller actions and their corresponding APIs.

As mentioned in the earlier section most of the Flipkart API interactions happen on the shipment as this is the logical unit that the seller needs to pick, pack and handover together to a logistics partner.

Forward Flow

Following are the different states of the shipments and possible seller actions against each state:

APPROVED:

All the new orders that the seller needs to process from a seller location are in this status at the start. Sellers can fetch these orders via calling the following APIs or by subscribing to order notification service. Please note that API is at shipment level and multiple order item ids can be part of once shipment.

API - GET /v3/shipments/{shipmentIds}

Notification - Shipment Created

Note

All the shipment/order related updates like state changes, important order attribute changes etc. can be fetched in 2 ways:

• Sellers calling Flipkart APIs in periodic intervals [Pull mechanism].
• Sellers subscribing to Flipkart Notification Service [Push mechanism].

Once the seller receives these shipment details, the seller should check dispatchAfterDate and hold status of the shipment.

Dispatch After Date : Sellers can not process all the shipments immediately. A shipment is actionable only after decided timestamp dispatchAfterDate. Flipkart owns the logic of calculating this timestamp basis the various factors like logistic partner fulfilment capacity etc.

Hold shipments : These are the shipments which Flipkart has put onhold and are not available for further processing by the sellers. This is done for shipments where Flipkart wants to verify certain details of the order before allowing the seller to process the orders.

Sellers can only act on the shipment after the dispatchAfterDate and when the hold status is FALSE. Sellers can get these two details in the shipment payload calling the above API or by subscribing to order notification service.

Once the hold status of the shipment has moved to the false and if the current date is after dispatchAfterDate sellers can start processing the shipment.

Hold Notification - Hold

Unhold Notification - UnHold

Following are the actions that the seller can take on these shipments:

Generate labels & invoices : Seller requires shipping labels and invoices to process the shipment. Sellers should request for generating these labels and invoices via calling the below-mentioned API.

API - POST /v3/shipments/labels

Note

This is an async call and labels and invoices might take some time to generate and be available for download. Usually it takes 5-10 sec for labels and invoices to be available for download but sometime due to system load it might take upto 30 mins. If they are not ready for download after 30 secs then the seller can contact seller support for reporting this issue.

Cancel order : A seller can cancel the orders if not in a position to fulfil them. Please note, order cancellation results into that product going out of stock on Flipkart and if the number of order cancellation goes beyond a certain threshold then seller account/location will be deactivated for some duration of time i.e seller will not be allowed to sell on Flipkart for some duration of time.

API - POST /v3/shipments/cancel

PACKING_IN_PROGRESS :

Once you have requested for the labels and invoice generation the order status moves to “PACKING_IN_PROGRESS”. Sellers should keep packing the products and wait for this state to change when the documents are ready for download. There is no seller action that can trigger a state change here. Once the documents are ready to download state will change to “PACKED”

API - GET /v3/shipments/{shipmentIds}

PACKED :

The orders for which required labels and invoices are ready to download, move to this state from the “PACKING_IN_PROGRESS” state.

API - GET /v3/shipments/{shipmentIds}

Notification - Packed

Now, seller can take the following possible actions:

Download Labels : A seller can download the labels, invoices, and forms generated for the respective order item to complete the packing process.

API - GET /v3/shipments/{shipmentIds}/labels

Mark as “Ready to Dispatch” : A seller should mark orders as “Ready to Dispatch” once the entire order processing is complete to trigger the shipment pickup request for the logistics team.

API - POST /v3/shipments/dispatch

READY_TO_DISPATCH :

The shipments that the sellers have successfully marked as “Ready to Dispatch” will be in this state.

API - GET /v3/shipments/{shipmentIds}

Notification - Ready To Dispatch

Following are the possible Seller actions:

Download Manifest : A seller must download the manifest, which contains the list of orders that needs to be handed over to the logistics partner on a particular date and time.

POST /v3/shipments/manifest

SHIPPED : When the logistic partnerships the shipment to the customer, the shipment moves to this state.

API - GET /v3/shipments/{shipmentIds}

Notification - Shipped

DELIVERED : When the logistic partner delivers the shipment to the customer, the shipment moves to this state.

API - GET /v3/shipments/{shipmentIds}

Notification - Delivered

CANCELLED : When either the seller or the customers cancel the order. Cancellation can only happen before the shipment is shipped.

API - GET /v3/shipments/{shipmentIds}

Notification - Shipment Cancelled

Return Flow

Following are the different states of the order items that are returned by the customer:

CREATED : When the new return is created on an approved order item id then the status of the return will be CREATED.

API - GET /v2/returns

Notification - Return Created

COMPLETED : When the product is returned to the seller then the status of the return will move to COMPLETED.

API - GET /v2/returns

Notification - Return Completed

CANCELLED : When the created return is cancelled and not expected to reach the seller location then the status of the return will move to CANCELLED.

API - GET /v2/returns

Notification - Return Cancelled

Click here to Subscribe for Notifications - Subscribing to Notifications

Self Ship Fulfilment

☰ SHOW | HIDE

For Self Ship fulfilment, the order item and service item state life cycle is:

Forward Flow

A Self Ship order may have two aspects of fulfilment:

• Physical delivery of the product
• Post-delivery services such as assembly, installation, etc.

Important

Sellers must ensure that they dispatch, deliver, and complete post-delivery services for the self-ship order within the respective pre-defined SLAs for the order and service item.

Order Status	Details	Seller Actions
Approved	New orders that the seller needs to process by marking them as “Dispatched” and providing necessary invoicing and logistics details	Cancel Order A seller can cancel these orders if not in a position to fulfill them. Dispatch Order A seller needs to update approved orders as “Dispatched” by providing details of invoice (invoice number, VAT/CST percentage) and logistics (courier partner name, AWB No., expected delivery date). This must be done before the Dispatch_By_Date to avoid dispatch SLA breach.
Shipped	Dispatched orders in transit	Delivery Attempt A seller can update delivery status on an order if: (a) delivery was attempted, (b) customer was unavailable, (c) mutual agreement between the seller and customer to reschedule delivery, or (d) due to an issue at the seller’s end. With this update, both the delivery attempt date and a new expected delivery date is required. Delivery Confirmation A seller needs to update delivery confirmation on an order after successful completion of delivery of a product to the customer. Delivery date is required with this update. This is expected to be done before the Deliver_By_Date to avoid delivery SLA breach.
Delivered	The orders that have been delivered to the customer,but are pending post-delivery service such as assembly, etc.	Service Attempt A seller can update service completion on an order if service was attempted but could not happen as: (a) customer was unavailable, (b) there’s mutual agreement between the seller and customer to reschedule service, or (c) there’s an issue at seller’s end. With this update, both service attempt date and a new expected service completion date is required. Service Completion A seller needs to update service confirmation on an order after successful completion of service of product to the customer. With this update, service completion date is required. This is expected to be done before Service_By_Date to avoid service SLA
Completed	The orders that the sellers have successfully fulfilled to the buyer’s satisfaction	N.A.

Associated Actions

Cancel order Order: Approved → Cancelled Service: Activated → Cancelled Dispatch order Order: Approved → Shipped Delivery attempt Increase in SLA for delivery. Confirm delivery If service item present: Order: Shipped → Delivered Service: Activated → In Progress If no service item present: Order: Shipped → Delivered → Complete Service attempt Increase in SLA for service completion Service complete Delivered → Complete Order: Delivered → Complete Service: In Progress → Complete

Returns Flow

The return item lifecycle is:

Self Ship returns are of two types:

• Courier returns (RVP)
  • Created due to buyer cancellations while the product is in transit to the customers
  • Customers can cancel the order any time depending on the cancellation policy associated with the product
  • These returns must be acknowledged or cancelled by sellers after verification of the product delivery status
  • If courier return is approved, seller needs to ensure it is not delivered to the customer and brought back to the warehouse
  • If courier return is cancelled, the forward fulfilment order item is updated as delivered
• Customer returns (RTO)
  • Created after delivery of the product to customers
  • Customers can request a return due to an issue with service (assembly/installation), quality (bad/defective/damaged) product, or due to wrong shipment
  • These returns must be approved or rejected by sellers after the a tech visit (or troubleshooting), as applicable
  • If returns are approved, seller needs to ensure product pickup from the customer
  • If returns are approved and a replacement order has been created, seller needs to fulfill it as any other Self Ship order
  • Any order cancelled in between the OFD to delivery completed state will be marked as a customer return not a courier return

Return Status	Details	Seller Actions
Requested	These are typically customer returns (RVP) that need your attention in terms of tech visit/troubleshooting the issue customer is facing. Post completion of tech visit, the seller needs to approve or reject the return.	RVP: Tech Visit Attempt A seller can update tech visit attempt on a return tech visit service item in case troubleshooting was attempted but could not happen due to customer unavailability, mutual agreement between seller and customer to reschedule tech visit or due to some issue at seller’s end. With this update, tech visit attempt date as well as a new expected tech visit date is required. RVP: Approve Return A seller can mark a customer return as approved post completion of tech visit. This is expected to be done before Tech_Visit_By date to avoid tech visit completion SLA breach. RVP: Reject Return A seller can mark a customer return as rejected post completion of tech visit. This is expected to be done before Tech_Visit_By date to avoid tech visit completion SLA breach.
Approved	These returns can either be approved customer returns (RVP) or courier returns (RTOs). In case of customer returns, reverse pickup confirmation is required to complete the return. In case of courier returns, RTO acknowledgement or cancellation is required to complete or close the return.	RVP: Reverse Pickup Attempt A seller can update reverse pickup attempt on an approved customer return in case pickup was attempted but could not happen due to customer unavailability, mutual agreement between seller and customer to reschedule reverse pickup or due to some issue at seller’s end. With this update, reverse pickup attempt date as well as a new expected reverse pickup date is also required. RVP: Reverse Pickup Confirmation A seller needs to update a customer return as completed post confirmation of reverse pickup. This is expected to be done before Reverse_Pickup_By date to avoid return completion SLA breach. RTO: Acknowledge RTO A seller needs to acknowledge buyer cancellation and confirm RTO after ensuring the product is not delivered to customer. RTO: Cancel RTO A seller needs to cancel an RTO in case the product has been delivered to customer. With this update, the forward product is to be confirmed as delivered and the delivery date is required as an input.
Completed	The returns that have been successfully closed by the sellers. Can include completed customer returns, acknowledged courier returns, rejected customer returns and cancelled courier returns.	N.A.

Associated Actions

Cancel Courier Return Return: Return Approved → Return Cancelled Acknowledge Courier Return Return: Return Approved → Return Completed Return Tech Visit Attempt Increase in SLA for tech visit completion Return Tech visit complete and Return approval Service: Service Requested → Service Completed Return: Return Requested → Return Approved Return Tech visit complete and Return rejected Service: Service Requested → Service Cancelled Return: Return Requested → Return Rejected Reverse Pick up Attempt Increase in SLA for reverse pick up Reverse Pick up Complete Return: Return Approved → Return Completed

Complete List of Order Management Pull APIs

Format: JSON

Protocol: HTTPS

API	Description / Use Case	Type
POST /v3/shipments/filter/	Search shipments based on dates, state, seller SKU ID, or shipmentId	Common
GET /v3/shipments?shipmentIds={} or, GET /v3/shipments?orderItemIds={} or, GET /v3/shipments?orderIds={}	Get shipment details based on the shipmentId/orderItemId/orderId	Common
POST /v3/shipments/labels	Mark shipments as packed and generate labels	Standard
GET /v3/shipments/{shipmentIds}/labels	Print shipping labels	Standard
POST /v3/shipments/{shipmentIds}/labelOnly/pdf	Download labels in PDF format for shipments	Standard
POST /v3/shipments/{shipmentIds}/labelOnly	Download labels in Byte-Stream for shipments	Standard
POST /v3/shipments/dispatch	Mark shipments as “Ready to Dispatch”	Standard
GET /v3/shipments/{shipmentIds}	Get shipment information of shipment ids	Common
GET /v3/shipments/{shipmentIds}/invoices	Get invoice information of shipment ids	Standard
POST /v3/shipments/cancel	Cancel an approved shipment	Common
GET /v3/shipments/{shipmentIds}/forms	Get forms associated with a shipment	Standard
POST /v3/shipments/forms/updateAck	Update ACK number and process form failed shipment	Standard
GET /v3/shipments/handover/counts?locationId={location_id}	Get vendor pick up details	Standard
POST /v3/shipments/manifest	Get manifest based on vendor	Standard
GET /v3/shipments/otc/{locationId}?requestType={requestType}	Get OTC details	Standard
GET /v2/returns	Get the details of order items returned	Common
POST /v3/shipments/selfShip/dispatch	Mark dispatch on Self Ship item	Self Ship
POST /v3/shipments/selfShip/delivery	Mark Self Ship item as delivered	Self Ship
POST /v3/shipments/selfShip/deliveryAttempt	Mark delivery attempt on Self Ship item	Self Ship
POST /v2/services/attempt	Mark service attempt detail	Self Ship
POST /v2/services/complete	Mark service as completed	Self Ship
POST /v2/returns/approve	Approve Self Ship returns	Self Ship
POST /v2/returns/reject	Reject Self Ship returns	Self Ship
POST /v2/returns/complete	Acknowledge Self Ship RVP returns	Self Ship
POST /v2/returns/pickup	Mark Self Ship retuns as picked up	Self Ship
POST /v2/returns/pickupAttempt	Mark pickup attempt on Self Ship returns	Self Ship
GET /selfship/vendors	Get the list selfShip vendors	Self Ship

Frequently Asked Questions - FAQ