.. _omapioverview-label: ==================== Order Management API ==================== .. sidebar:: 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. .. image:: https://img1a.flixcart.com/fk-sp-static/images/order-terminologies.png :scale: 30% :align: center | .. 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 =================== .. container:: toggle .. container:: header **☰ 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** .. image:: https://img1a.flixcart.com/fk-sp-static/images/standard-fulfilment-fwd-flow.png :scale: 30% :align: center | | 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 - :ref:`getShipmentDetails-label` Notification - :ref:`push-shipment-create-label` .. 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 - :ref:`push-hold-label` Unhold Notification - :ref:`push-unhold-label` 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 - :ref:`shipmentPack-label` .. 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 - :ref:`shipmentCancel-label` **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 - :ref:`getShipmentDetails-label` **PACKED** : The orders for which required labels and invoices are ready to download, move to this state from the “PACKING_IN_PROGRESS” state. API - :ref:`getShipmentDetails-label` Notification - :ref:`push-pack-label` 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 - :ref:`getShipmentLabel-label` **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 - :ref:`shipmentRTD-label` **READY_TO_DISPATCH** : The shipments that the sellers have successfully marked as “Ready to Dispatch” will be in this state. API - :ref:`getShipmentDetails-label` Notification - :ref:`push-rtd-label` 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. :ref:`getShipmentManifest-label` **SHIPPED** : When the logistic partnerships the shipment to the customer, the shipment moves to this state. API - :ref:`getShipmentDetails-label` Notification - :ref:`push-ship-label` **DELIVERED** : When the logistic partner delivers the shipment to the customer, the shipment moves to this state. API - :ref:`getShipmentDetails-label` Notification - :ref:`push-deliver-label` **CANCELLED** : When either the seller or the customers cancel the order. Cancellation can only happen before the shipment is shipped. API - :ref:`getShipmentDetails-label` Notification - :ref:`push-cancel-label` .. _standard-fulfilment-return-flow-label: .. container:: title **Return Flow** | Following are the different states of the order items that are returned by the customer: .. image:: https://img1a.flixcart.com/fk-sp-static/images/standard-fulfilment-return-states.png :scale: 30% :align: center | **CREATED** : When the new return is created on an approved order item id then the status of the return will be CREATED. API - :ref:`return-label` Notification - :ref:`push-createreturn-label` **COMPLETED** : When the product is returned to the seller then the status of the return will move to COMPLETED. API - :ref:`return-label` Notification - :ref:`push-completereturn-label` **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 - :ref:`return-label` Notification - :ref:`push-cancelreturn-label` Click here to Subscribe for Notifications - :ref:`subscribe-notification-label` | .. _selfshipoverview-label: Self Ship Fulfilment ==================== .. container:: toggle .. container:: header **☰ SHOW | HIDE** | For Self Ship fulfilment, the order item and service item state life cycle is: .. image:: https://img1a.flixcart.com/fk-api-docs/_static/images/SelfshipFwdFlow.jpg :scale: 30% :align: center **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 |**Cancel Order** | | |needs to process by marking | | | |them as "Dispatched" and |A seller can cancel these orders if not in a | | |providing necessary invoicing |position to fulfill them. | | |and logistics details | | | | |**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 |**Service Attempt** | | |delivered to the customer,but | | | |are pending post-delivery |A seller can update service completion on an | | |service such as assembly, etc.|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 |**N.A.** | | |have successfully fulfilled to| | | |the buyer's satisfaction | | +----------------+------------------------------+---------------------------------------------+ **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 | +---------------------------------------------------------------+ .. container:: title Returns Flow | The return item lifecycle is: .. image:: https://img1a.flixcart.com/fk-api-docs/_static/images/SelfShipReturnsFlow.png :scale: 30% :align: center 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 |**RVP: Tech Visit Attempt** | | |returns (RVP) that need your | | | |attention in terms of tech |A seller can update tech visit attempt on a | | |visit/troubleshooting the |return tech visit service item in case | | |issue customer is facing. Post|troubleshooting was attempted but could not | | |completion of tech visit, the |happen due to customer unavailability, mutual| | |seller needs to approve or |agreement between seller and customer to | | |reject the return. |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 |**RVP: Reverse Pickup Attempt** | | |approved customer returns | | | |(RVP) or courier returns |A seller can update reverse pickup attempt on| | |(RTOs). |an approved customer return in case pickup | | | |was attempted but could not happen due to | | |In case of customer returns, |customer unavailability, mutual agreement | | |reverse pickup confirmation is|between seller and customer to reschedule | | |required to complete the |reverse pickup or due to some issue at | | |return. |seller’s end. | | | | | | |In case of courier returns, |With this update, reverse pickup attempt date| | |RTO acknowledgement or |as well as a new expected reverse pickup date| | |cancellation is required to |is also required. | | |complete or close the return. | | | | |**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 |**N.A.** | | |successfully closed by the | | | |sellers. | | | | | | | |Can include completed customer| | | |returns, acknowledged courier | | | |returns, rejected customer | | | |returns and cancelled courier | | | |returns. | | +----------------+------------------------------+---------------------------------------------+ **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 | +=================================+==========================================+=================+ |:ref:`getShipment-label` |Search shipments based on dates, state, |Common | | |seller SKU ID, or ``shipmentId`` | | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getByShipmentIds-label` |Get shipment details based on the |Common | | |``shipmentId``/``orderItemId``/``orderId``| | +---------------------------------+------------------------------------------+-----------------+ |:ref:`shipmentPack-label` |Mark shipments as packed and generate |Standard | | |labels | | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getShipmentLabel-label` |Print shipping labels |Standard | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getShipmentLabelOnly-pdf` |Download labels in PDF format for |Standard | | |shipments | | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getShipmentLabelOnly-bs` |Download labels in Byte-Stream for |Standard | | |shipments | | +---------------------------------+------------------------------------------+-----------------+ |:ref:`shipmentRTD-label` |Mark shipments as "Ready to Dispatch" |Standard | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getShipmentDetails-label` |Get shipment information of shipment ids |Common | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getShipment-invoice-label` |Get invoice information of shipment ids |Standard | +---------------------------------+------------------------------------------+-----------------+ |:ref:`shipmentCancel-label` |Cancel an approved shipment |Common | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getForms-label` |Get forms associated with a shipment |Standard | +---------------------------------+------------------------------------------+-----------------+ |:ref:`updateFormAckNumber-label` | Update ACK number and process form failed|Standard | | | shipment | | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getVendorDetails-label` |Get vendor pick up details |Standard | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getShipmentManifest-label` |Get manifest based on vendor |Standard | +---------------------------------+------------------------------------------+-----------------+ |:ref:`getReverseOTC-label` |Get OTC details |Standard | +---------------------------------+------------------------------------------+-----------------+ |:ref:`return-label` |Get the details of order items returned |Common | +---------------------------------+------------------------------------------+-----------------+ |:ref:`selfShipDispatch-label` |Mark dispatch on Self Ship item |Self Ship | +---------------------------------+------------------------------------------+-----------------+ |:ref:`selfShipDelivery-label` |Mark Self Ship item as delivered |Self Ship | +---------------------------------+------------------------------------------+-----------------+ |:ref:`selfShipDelAttempt-label` |Mark delivery attempt on Self Ship item |Self Ship | +---------------------------------+------------------------------------------+-----------------+ |:ref:`serviceAttempt-label` |Mark service attempt detail |Self Ship | +---------------------------------+------------------------------------------+-----------------+ |:ref:`serviceComplete-label` |Mark service as completed |Self Ship | +---------------------------------+------------------------------------------+-----------------+ |:ref:`returnsApprove-label` |Approve Self Ship returns |Self Ship | +---------------------------------+------------------------------------------+-----------------+ |:ref:`returnsReject-label` |Reject Self Ship returns |Self Ship | +---------------------------------+------------------------------------------+-----------------+ |:ref:`returnsComplete-label` |Acknowledge Self Ship RVP returns |Self Ship | +---------------------------------+------------------------------------------+-----------------+ |:ref:`returnsPickup-label` |Mark Self Ship retuns as picked up |Self Ship | +---------------------------------+------------------------------------------+-----------------+ |:ref:`returnsPickupAttempt-label`|Mark pickup attempt on Self Ship returns |Self Ship | +---------------------------------+------------------------------------------+-----------------+ Frequently Asked Questions - :ref:`faq-label`