Order Management API

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.
https://img1a.flixcart.com/fk-sp-static/images/order-terminologies.png

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

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

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

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:

Associated Actions

The return item lifecycle is:

Self Ship returns are of two types:

Associated Actions


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