Retrieving and fulfilling orders

Once a buyer completes the checkout process on eBay and purchases an item, an order is created. Orders can be made up of multiple line items, and it is up to the seller to group the line items of an order into one or more packages and fulfill the order.

The multiple approaches to managing orders and shipping fulfillments are discussed below:

Retrieving and fulfilling orders with Fulfillment API

The Fulfillment API allows sellers to efficiently manage the order fulfillment process, and includes functionality to retrieve orders, assign order line items to shipping packages, and provide shipment tracking.

Sellers can use getOrder to retrieve a specific order, or can use getOrders to retrieve multiple orders based on order IDs, date range, or fulfillment status. Below are some key fields that are returned in the response of both methods.

• Line item quantity (lineItems.quantity)
• Shipping address (shippingStep.shipTo)
• Buyer’s selected shipping service (shippingCarrierCode and shippingServiceCode)
• The expected shipping date window based on the selected shipping service and handling time (maxEstimatedDeliveryDate and minEstimatedDeliveryDate)
• Ship-by date (lineItemFulfillmentInstructions.shipByDate)
• Cost and tax information for the order
• Order cost (pricingSummary.total)
• Shipping costs (pricingSummary.deliveryCost)
• Tax amount (pricingSummary.tax)

Orders must be marked as shipped before they are considered "fulfilled" (see the orderFulfillmentStatus response field of the getOrder(s) method). If the seller purchases an eBay shipping label for the order, eBay will automatically mark the order as fulfilled and will provide tracking information for the order. If the seller does not use eBay shipping labels, they can use the createShippingFulfillment method to mark the order as shipped and provide shipment tracking information.

The createShippingFulfillment method can be used to assign one or more line items of an order to a single package, and shipment tracking information must be provided for that package. This call must be repeated for each package in an order.

Use getShippingFulfillment to retrieve details on a specific shipping package or an order, or use getShippingFulfillments to retrieve details on all shipping packages of an order.

Retrieving and fulfilling orders with Trading API

The order management calls of the Trading API allow sellers to manage the order fulfillment process and include functionality to retrieve all of their active orders, send invoices to the buyer, combine multiple unpaid order line items into one order, and perform various post-sale tasks.

The Trading API calls used to manage orders are discussed below:

• Retrieve information about the orders associated with a seller using GetOrders. The following data is retrieved for each order:
• Line item quantity (QuantityPurchased)
• Shipping address (ShippingAddress)
• Buyer’s selected shipping service (ShippingService)
• Cost and tax information for the order
• Order cost (Order.Total)
• Shipping costs (ShippingServiceCost)
• Tax amount (Taxes)

Orders must be marked as shipped before they are considered “fulfilled” (see OrderStatus response field of the GetOrder(s) methods). If the seller purchases an eBay shipping label for the order, eBay will automatically mark the order as fulfilled and will provide tracking information for the order. If the seller does not use eBay shipping labels, they can use the CompleteSale method to mark the order as shipped and provide shipment tracking information.

CompleteSale can also be used for various post-sale tasks, such as marking an order as paid (see the Paid boolean) or leaving feedback for the buyer (see the FeedbackInfo container).

Below are the other order-related calls available in the Trading API:

• Use GetSellerTransactions to retrieve line item information for one or more orders, or use GetItemTransactions to retrieve line item information for a specific fixed-price listing.
• If a buyer has not yet paid for an order, send an email invoice reminder to the buyer using SendInvoice.
• Use AddOrder to combine two or more unpaid order line items from the same buyer into one Combined Invoice order.

Downloading USPS shipping labels with Logistics API

The Logistics API allows you to retrieve available USPS shipping label costs based on ship-from, ship-to, and package weight/dimensions, select the appropriate shipping option, and download the USPS shipping label.

Note: The Logistics API is restricted and only accessible to approved eBay partners. This API can only be used for domestic shipping within the US, only supports USPS shipping rates and labels, and only supports order-level fulfillment.

Below is the basic flow used to view shipping quotes, select the quote you want, and download shipping labels:

1. Retrieve the costs and details of available USPS shipping options using createShippingQuote and configure the following required fields:

• ShipFrom
• ShipTo
• PackageSpecification

1. Using the shippingQuoteId and rateId values returned in createShippingQuote response, use createFromShippingQuote to generate and customize the USPS shipping label for the selected shipping service. Note that the selected shipping service should match the shipping service that the buyer selected at checkout.
2. Using the shipmentId value returned in createFromShippingQuote, use downloadLabelFile to download a PDF file of the USPS shipping label.

Below are the other methods available with the Logistics API:

• Use getShipment to retrieve the shipping details of a specific shipment.
• Use getShippingQuote to retrieve the completed details of a specific shipping quote.
• Use cancelShipment to cancel a shipment and delete its associated shipping label.

Managing order cancellations

The Post-Order API allows sellers to cancel orders up to 30 days after checkout. Sellers can cancel an order for a number of reasons, such as if a buyer requests a cancellation or if the purchased item is out of stock. The order is automatically cancelled if the seller makes a Create Cancellation Request call, and the buyer will be refunded by eBay if the order has already been paid for.

The Post-Order API methods used to manage order cancellations are discussed below:

1. Use Search Cancellations to see if a seller has any cancellation requests. Numerous filters are available for this method, including by date range or item_id. Refer to the cancelReason field to see why the buyer initiated the cancel request, and the cancelState and cancelStatus fields to determine upcoming cancellation events and the appropriate actions you can take.
2. If a buyer requests to cancel an order, sellers can either approve or reject the cancellation using Approve Cancellation or Reject Cancellation.
• If the seller approves the cancellation, the buyer will be fully refunded by eBay.
• If the seller rejects the cancellation, such as if the order has already been shipped, the shipped date and tracking number should be supplied through the shipmentDate and trackingNumber fields, respectively.
3. If approved, if the item has already been paid for, eBay will automatically issue a full refund to the buyer.

 Below are the other methods applicable to managing order cancellations with the Post-Order API:

• For the seller to initiate an order cancellation, use Create Cancellation Request and specify the reason for the cancellation though the cancelReason field with one of the following values:
• BUYER_ASKED_CANCEL (cancelling order upon request from the buyer).
• OUT_OF_STOCK_OR_CANNOT_FULFILL (used if the seller is out of stock on the item or otherwise can't fulfill the order).
• Use Get Cancellation to retrieve details about a specific cancellation request.

Managing Item Not Received (INR) inquiries

An Item Not Received (INR) inquiry can be created by a buyer once the estimated delivery date window for an item they have purchased has passed and the item has still not been received. When a buyer creates an INR inquiry, they can either request a full refund for the item, or inform the seller that they still want the item.

The Post-Order API methods used to manage INR inquiries are discussed below:

Managing INR inquiries

1. Use Search Inquiries to see if a seller has any INR inquiry requests. Numerous filters are available for this method, including by date range or item_id. Refer to the InquiryStatusEnum response enum to see the current status of an INR inquiry.
2. If the buyer still wants the item they filed an INR inquiry against, provide updated shipment tracking details for the shipment of the line item using Provide Inquiry Shipment Info.
3. If the buyer wants a refund for the item they filed an INR inquiry against, issue a refund for missing line item using Issue Inquiry Refund. If necessary, sellers can also provide more information to the buyer about the refund using Provide Inquiry Refund Info.

Managing INR cases

If a seller doesn’t address an INR inquiry in a timely manner, a buyer may escalate the inquiry into an INR case. Below is the typical flow one might use with Post-Order API methods:

1. Use Search Cases to retrieve all recent cases. Numerous filters are available for this method, including date range filter or case status. You will want to include the case_status_filter query parameter and set its value to OPEN to retrieve all open cases.
2. Use Get Case after Search Cases to see what can be done to help resolve the case. The case ID is required as a path parameter to this call. The response of this call has full history details, including the history of the INR inquiry that led to the case.
3. One of the following methods can be used to help resolve the case and lead to the buyer or eBay closing the case:
• Issue Case Refund: this method should be used if the buyer no longer wants the item and just wants to be refunded.
• Provide Case Shipment Info: this method should be used if the buyer still wants the item and wants to be able to track the shipment of the order.

Below are the other methods applicable to managing INR inquiries with the Post-Order API:

• Use Send Inquiry Message to send a message to the buyer about an INR inquiry.
• If needed, use Escalate Inquiry to escalate an INR inquiry into a case. This can be used if the seller has already shipped the order line item, but the buyer is refusing to close the inquiry.
• Use Get Inquiry to retrieve details about a specific INR inquiry.

Managing returns

There are occasionally circumstances where a buyer will request to return an order. There are a variety of reasons this may occur, such as if an article of clothing did not fit, the item was damaged during shipment, the item wasn’t as described in the listing, or the buyer just changed their mind about the item. The Post-Order API has methods that allow the seller to view any current return requests and manage the return process.

The Post-Order API methods used to manage return requests are discussed below:

Standard approve return flow

1. Use Search Returns to see if a seller has any return requests. If so, refer to the creationInfo.reason field to see the buyer’s reason for the return, as well as the creationInfo.reasonType field to check if the return has been classified as SNAD or REMORSE. Sellers are responsible for the return shipping cost for SNAD returns.
2. Approve return request using Process Return Request.
• If approved and the buyer is responsible for the return shipping, they can ship the item back after the return request has been approved by the seller.
• If approved and the seller is responsible for the return shipping, use Add Shipping Label Info to create and send a shipping label to the buyer.
3. Once the item has been returned by the buyer, mark the item as received using Mark Return Received.

Managing SNAD return cases

If a seller doesn’t address a SNAD (Significantly not as Described) return request in a timely manner, a buyer may escalate the return request into a Return case. Below is the typical flow one might use with Post-Order API methods:

1. Use Search Cases to retrieve all recent cases. Numerous filters are available for this method, including by date range or case status. You will want to include the case_status_filter query parameter and set its value to OPEN to retrieve all open cases.
2. Use Get Case to see what can be done to resolve the case. The case ID is required as a path parameter to this call. The response of this call has full history details, including the history of the return request that led to the case.
3. One of the following methods can be used to resolve the case and lead to the buyer or eBay closing the case:
• Issue Case Refund: this method can be used if the seller is willing to let the buyer keep the item, but still issue a full refund.
• Provides Return Address: this method can be used to provide the buyer the return address and RMA number (if applicable).

Below are the other methods applicable to managing return requests with the Post-Order API:

• Use Issue Return Refund to issue a full or partial refund to the buyer for the returned item. This method is used if the seller tells the buyer to keep the item and that they will still send them a full refund, or if the buyer reports the item as SNAD, but the buyer and seller negotiate a partial refund.  Once the refund has been sent, use Mark Return Refund Sent to notify the buyer that a refund has been issued for the item.
• Use Get Return Files to retrieve the files associated with a return request.
• Use Set Return Preferences to set your return preferences, such as if a Return Merchandise Authorization (RMA) is required for returned items.
• Use Get Return Preferences to retrieve a seller’s return preferences, such as if an RMA is required or if automated return rules are turned on.
• Use Get Return Shipping Label to retrieve the data for a return shipping label, including the URL where the label can be downloaded.
• Use Get Shipment Tracking Info to retrieve shipment tracking activity on a specific return request.
• Use Send Return Message to send a message to a buyer regarding a return request.
• Use Void Shipping Label to void a current return shipping label.
• If needed, use Escalate Return to escalate a return request into a case. This can be used if the seller never receives the item back from the buyer, or if the seller has an issue with the returned item.

Managing payment disputes

It is possible that an eBay buyer will initiate a payment dispute with their payment provider instead of directly on the eBay platform. The payment dispute operations in the Fulfillment API allow sellers to discover these types of disputes. This API contains methods to retrieve payment disputes that have been created, as well as operations to accept or contest these payment disputes and upload image files to support the seller's case if a seller decides to contest a dispute.

The Fulfillment API methods used to manage third-party payment disputes are discussed below:

1. Use getPaymentDisputeSummaries to retrieve one or more payment disputes filed against a seller. You can filter by an order ID, buyer user ID, date range, or dispute status. The following information is returned for each payment dispute:
• paymentDisputeStatus: The status of the payment dispute. Disputes with a status of ACTION_NEEDED indicate that the payment dispute is open and the seller is required to take action.
• respondByDate: The time and date the seller must respond to a payment dispute.
• reason: The reason the buyer initiated the payment dispute. For a list of supported reasons, see DisputeReasonEnum.
• paymentDisputeId: The unique identifier of the payment dispute. This value should be stored for future reference.
2. To retrieve more details about an open dispute that the seller needs to take action against, use getPaymentDispute.
3. Accept the dispute using acceptPaymentDispute or contest the dispute. If the payment dispute is accepted, the buyer will be refunded and the dispute will be closed. If the seller chooses to contest the payment dispute, proceed with the following steps.
4. Use uploadEvidenceFile to upload each file being used to contest the dispute.
5. Referencing the fileId value returned in the previous step, use addEvidence to create an evidence set and add one or more uploaded files to the evidence set. The type of evidence required depends on the buyer’s dispute reason. See EvidenceTypeEnum for a full list of supported types.
6. Once the evidence set has been created, use contestPaymentDispute to officially contest the dispute, and any evidence you uploaded will already be associated with the dispute.

Below are the other methods applicable to managing payment disputes with the Fulfillment API:

• Use getActivities to retrieve a log of activity for a payment dispute, including a timestamp for each action of the dispute from creation to resolution.
• Use updateEvidence to add one or more evidence files to an existing evidence set.
• Use fetchEvidenceContent to retrieve a specific evidence file for a payment dispute.