Handling order inquiries

The Post-Order API supports item inquiry flows. In this flow, the buyer is basically informing eBay and the seller that an item has not arrived within the expected delivery window. While buyers often inquire about items using the eBay web flows, sellers can programmatically manage buyer-initiated order inquires.

The buyer is eligible to create an Item Not Received (INR) inquiry as soon as the estimated delivery date window has passed. The estimated delivery date window is established at checkout time, and is based on the seller's maximum handling time and on the estimated transit time of the selected shipping service. When a buyer is eligible to create an INR inquiry, it is up to the buyer to inform the seller about whether he/she still wants the item or if they now want a full refund instead. If the estimated delivery date window has not passed, but the buyer is still curious about the whereabouts of the order, and the shipment-tracking information is not available, that buyer can still contact that seller through eBay member messaging to ask about the status of the shipment.

Buyer still wants item

As long as shipment tracking is available with the selected shipping service, the seller should always mark an order as shipped and upload shipment tracking information (shipping carrier and tracking number) so the buyer can track the shipment. If this information is not provided, the buyer can create an INR inquiry to alert the seller and eBay that shipment tracking information is desired by the buyer.

The Post-Order API contains both seller- and buyer-facing interfaces. Normally, you will implement only the seller-facing interfaces in your applications; the buyer-facing calls are included to facilitate application testing (buyers use eBay Web flows to initiate cancellations, returns, inquiries, and escalations).

The following flow demonstrates a typical lifecycle of an INR inquiry if the buyer just wants to track the item that has not been received. Although buyers will more likely create and close an INR inquiry through the eBay Web flow, this flow demonstrates how these actions would be done using Post-Order Inquiry calls:

1. The buyer checks to see if they are eligible to create an INR inquiry for the specified order line item.

   The buyer calls POST /post-order/v2/inquiry/check_eligibility to see if an order line item is eligible for an inquiry request. In the call, the buyer passes in itemId and transactionId values to identify the order line item.

   If the buyer is eligible to file an INR inquiry against the order line item, the inquiryEligibilityStatus field will be returned in the response with a value of ELIGIBLE_TO_FILE_REQUEST or ELIGIBLE_TO_FILE_WITH_WARNING. If the latter value is returned, the seller can find out more information about the warning(s) by looking at the warnings container, which should be returned if the ELIGIBLE_TO_FILE_WITH_WARNING value is returned. If the returned value of the inquiryEligibilityStatus field is INELIGIBLE, the buyer may want to look at the errors or nonOverridableErrors containers if these are returned. In some cases, it may be too early for the buyer to create an INR inquiry. If this is the case, the buyer may want to look at the earliestPossibleFilingDate container.

2. The buyer creates an INR inquiry.

   The buyer calls POST /post-order/v2/inquiry/ with the desiredOutcome value set to STILL_WANT_ITEM to create an INR inquiry. If successful, the call returns an inquiryId in the Location HTTP response header. Note that the desiredOutcome value cannot be set to FULL_REFUND unless the estimated delivery date window for the item has already passed. The full refund scenario is covered in the next section.

3. The seller responds to the INR inquiry with shipment information.

   The seller calls POST /post-order/v2/inquiry/{inquiryId}/provide_shipment_info to provide shipment tracking details and other information about the shipment. It may also be a good idea for the seller to include the sellerComments container in the call request just to provide more information about the status of the buyer's item.

   Once the seller uploads a tracking ID, it will appear below the item title in the Sold section of My eBay.

   eBay emails the tracking number to the buyer, and the buyer can also find this information in the Purchase History > Order Details page of My eBay, and on the Feedback page.

4. The seller conditionally sends a message to the buyer.

   If the seller receives an INR inquiry despite having already provided a tracking ID, it usually indicates the shipment did not arrive as scheduled, and it could be that the shipping carrier is having an issue.

   In this scenario, the seller should investigate the status of the shipment by contacting the shipping carrier, and communicate any updated shipping information that they get from the shipping carrier to the buyer by calling POST /post-order/v2/inquiry/{inquiryId}/send_message.

5. Buyer closes the INR inquiry.

   Once the INR inquiry has been properly addressed, whether that means that the seller has provided the shipment tracking information, or maybe the item has arrive, the buyer can close the INR inquiry by calling POST /post-order/v2/inquiry/{inquiryId}/close. Depending on the scenario, the buyer should include the closeReason field and set its value to ITEM_ARRIVED (if the item has arrived) or WORKED_OUT_WITH_SELLER (if the buyer is satisfied that the seller has properly addressed the INR inquiry).

Buyer wants a refund

If the estimated delivery date window has passed and the item has still not arrived, the buyer becomes eligible to ask the seller for a full refund of their purchase price instead of receiving the item.

The following flow demonstrates a typical lifecycle of an INR inquiry if the estimated delivery date window has passed, and the buyer now wants a full refund instead of receiving the item. Although buyers will more likely create and close an INR inquiry through the eBay Web flow, this flow demonstrates how these actions would be done using Post-Order Inquiry calls:

1. The buyer checks to see if they are eligible to create an INR inquiry for the specified order line item.

   The buyer calls POST /post-order/v2/inquiry/check_eligibility to see if an order line item is eligible for an inquiry request. In the call, the buyer passes in itemId and transactionId values to identify the order line item.

   If the buyer is eligible to file an INR inquiry against the order line item, the inquiryEligibilityStatus field will be returned in the response with a value of ELIGIBLE_TO_FILE_REQUEST or ELIGIBLE_TO_FILE_WITH_WARNING. If the latter value is returned, the seller can find out more information about the warning(s) by looking at the warnings container, which should be returned if the ELIGIBLE_TO_FILE_WITH_WARNING value is returned. If the returned value of the inquiryEligibilityStatus field is INELIGIBLE, the buyer may want to look at the errors or nonOverridableErrors containers if these are returned. In some cases, it may be too late for the buyer to create an INR inquiry. If this is the case, the buyer may want to look at the latestPossibleFilingDate container.

2. The buyer requests a refund.

   The buyer calls POST /post-order/v2/inquiry/ with the desiredOutcome value set to FULL_REFUND to create an INR inquiry, and to inform seller that a full refund is desired. If successful, the call returns an inquiryId in the Location HTTP response header.

3. The seller obtains details about the INR inquiry.

   The seller calls GET /post-order/v2/inquiry/{inquiryId} to retrieve the activity to date relating to a specific inquiry. This includes any actions taken by the buyer, the seller, the Order Inquiry service, or eBay customer support representatives.

4. The seller issues a full refund to the buyer.

   The seller calls POST /post-order/v2/inquiry/{inquiryId}/issue_refund.

   eBay completes the refund by issuing an eCheck or a payout in line with buyer's original payment method.

   The seller will take this action unless the item is in transit to the buyer. In which case, the seller might use the POST /post-order/v2/inquiry/{inquiryId}/provide_shipment_info call to provide shipment tracking information and to inform the buyer that a refund cannot be issued at this time since the item has already been shipped. Buyer will then have the option of escalating the INR inquiry into an INR case if they are still seeking a refund and the seller is not willing to offer a refund.

5. The buyer confirms the refund was received.

   Buyer calls POST /post-order/v2/inquiry/{inquiryId}/confirm_refund to confirm that the refund has been received.

6. Close the INR inquiry.

   Buyer closes the INR inquiry by calling POST /post-order/v2/inquiry/{inquiryId}/close. This is normally done by the buyer, but if the buyer neglects to close the case after they have received the refund, the seller can also close the inquiry.

Escalating an inquiry

If the buyer doesn't agree with the seller's response to an INR inquiry, they can escalate the inquiry to eBay customer support. For example, if the seller doesn't refund the full amount of an order that doesn't get delivered, the buyer can escalate the INR inquiry. This results in the creation of an INR case, which the seller can manage using the Post-Order API Case Management operations. It is in the seller's best interest to satisfy the buyer before an INR inquiry is escalated, as cases that go against the seller will result in a defect on the seller's account. The seller can use the POST /post-order/v2/inquiry/{inquiryId}/send_message operation to create a dialog with the buyer in hopes of resolving the issue before escalation occurs.

If efforts to resolve the INR inquiry fail, the buyer can initiate an escalation by calling POST /post-order/v2/inquiry/{inquiryId}/escalate. This operation turns an INR inquiry into an INR case with customer support. In the call, the escalationReason field is required in the request payload. The buyer should pass in the most appropriate value. If the buyer still wants the item and the estimated delivery date window has passed, the buyer would probably use the NOT_RECEIVED value. If the buyer wants a full refund instead, and the estimated delivery date window has passed, the buyer would probably use the NO_REFUND value. The message field can be used to elaborate on the reason for the escalation. The call returns a caseId in the Location HTTP response header, which you can use as input to the Post-Order API Case Management operations.

See Escalating and Resolving a Case for details on how to handle cases that have been escalated to eBay customer support.