fulfillment API1.11.0

Fulfillment API

The outcome of a buyer's eBay checkout process is an order. This API enables sellers to manage the completion of an order in accordance with the payment method and timing specified at checkout. The line items in the order are grouped into one or more packages. As the seller addresses, handles, and ships each package, the set of specifications for this process is known as a fulfillment. Use the Fulfillment API to facilitate and monitor these activities from the order to completion. Sellers' status on eBay depend partly on their record of timely fulfillment.

Note: The Fulfillment API covers only the transactions that have completed the checkout process. This includes both paid purchases and purchases that do not require upfront payment (such as COD). However, the API does not cover pending payment purchases that require upfront payment before shipment.

The Fulfillment API also has four payment dispute 'GET' methods that allows a seller to retrieve details on any buyer-initiated payment dispute (that the buyer opens with their payment provider), and an issueRefund method that allows a seller to issue a full or partial refund to a buyer for an order. Full or partial refunds can be issued at the order level or line item level. For the issueRefund method and the payment dispute methods, the seller's account must be opted in to eBay managed payments.

For more information about using REST APIs, see Using eBay RESTful APIs.

Technical overview

The checkout process produces an order and generates its order identifier, which serves as the starting point for the Fulfillment API.

Primary Fulfillment API objects

Objects are as follows:

Order

The Order object contains information about an order that requires shipping, including:

  • Information about the buyer and seller
  • Information about the order’s line items
  • The plans for packaging, addressing and shipping the order
  • The status of payment, packaging, addressing, and shipping the order
  • A summary of monetary amounts specific to the order, such as pricing, payments, and shipping costs
Line Item

The LineItem object contains details about one or more units of a sold item in an order, including:

  • Information about the item's eBay listing, including listing title, promotions, and the seller's SKU
  • All monetary amounts specific to the line item such as pricing, promotions, delivery costs, fees, taxes, and refunds
  • The status of packaging, addressing and shipping the line item
Shipping Fulfillment

The ShippingFulfillment object contains information about one package and its delivery, including:

  • The plans for packaging, addressing and shipping a set of line items
  • The history of the fulfillment
  • Shipping and tracking details of the fulfillment
  • Estimated and actual delivery dates
Fulfillment Start Instruction

The FulfillmentStartInstruction object contains recommendations for fulfilling an order, including:

  • The type of fulfillment
  • The shipping carrier and service
  • Recipient contact and address information
  • The estimated delivery window
Issue Refund Request

The request payload of the issueRefund method allows sellers (enrolled in eBay managed payments) to:

  • Issue a full or partial refund
  • Issue a refund for an entire order, or for one or more line items in a multiple line item order
  • Use legacy or REST-based identifiers for orders and order line items
Get Payment Dispute Summary

The getPaymentDisputeSummaries response includes summary information about one or more buyer-initiated payment disputes opened against the seller's order(s). The seller has the option of retrieving all payment disputes against their account, or they can use query parameters to retrieve payment disputes in a certain state (open, closed, or 'action needed'), payment disputes created during a specified time period, payment disputes created by a specific buyer, or payment disputes opened against a specific order.

Get Payment Dispute Details

The getPaymentDispute response includes detailed information about a specific payment dispute. The payment dispute is identified through a call URI path parameter. Information in the getPaymentDispute response includes the status of the payment dispute, the reason why the buyer opened the payment dispute, the order and line items associated with the payment dispute, and the dollar amount involved in the payment dispute. Other details in the response will vary based on the status of the dispute.

Get Payment Dispute Activity

The getActivities response shows all actions that have occurred for a specific payment dispute, from the dispute being opened to the dispute being closed. For each action, there is a timestamp for when the action occured and it states the actor (buyer, seller, system) that performed the action.

Get Evidence File

In the fetchEvidenceContent method, the seller identifies the payment dispute, evidence set, and evidence file (using path and query parameters) to retrieve an evidence file that was provided to support the seller's case against the payment dispute.

Business use cases

This section outlines the high-level use cases addressed by the Fulfillment API.

Discover orders that need to be fulfilled

Retrieve unfulfilled orders so you can create and process each order's shipping fulfillments. You can retrieve known orders or search for orders by creation date, modification date, or fulfillment status. See Discovering unfulfilled orders.

Package line items and define delivery parameters

Determine whether any line items in an order have not been assigned to a shipping fulfillment, or have been assigned to a shipping fulfillment but not fulfilled. Ensure that all line items have been included in one or more packages, and that each package is assigned to a shipping fulfillment. See Handling unfulfilled line items.

Monitor fulfillments to completion

Periodically retrieve and examine an order's shipping fulfillments to determine if they have been fulfilled. When all of the order's shipping fulfillments are complete, the order is fulfilled. See Managing fulfillments for an order.

Issue full or partial refunds to buyers

Sellers enrolled in eBay managed payments can issue full or partial refunds to buyers in the case or order cancellations, returned items, or other order issues, including items 'not as described'. Buyer refunds issued through the issueRefund method are processed asynchronously, and sellers can track the status of the refund by making a getOrder call.

Retrieve information on payment disputes

Sellers enrolled in eBay managed payments can retrieve information on payment disputes. Currently, the available payment dispute methods are only 'GET' calls, so the sellers will still have to rely on My eBay/Seller Hub to perform actions against payment disputes, such as accepting or contesting these disputes, or providing evidential documents.

API restrictions

Supported marketplaces

The order and fulfillment methods of the Fulfillment API are supported on all eBay marketplaces that support selling and order management, including the following:

  • eBay US (EBAY_US, www.ebay.com)
  • eBay UK (EBAY_GB, www.ebay.co.uk)
  • eBay Germany (EBAY_DE, www.ebay.de)
  • eBay Australia (EBAY_AU, www.ebay.com.au)
  • eBay Canada (EBAY_CA, www.ebay.ca (English) and www.cafr.ebay.ca (French))
  • eBay France (EBAY_FR, www.ebay.fr)
  • eBay Italy (EBAY_IT, www.ebay.it)
  • eBay Spain (EBAY_ES, www.ebay.es)
  • eBay Austria (EBAY_AT, www.ebay.at)
  • eBay Switzerland (EBAY_CH, www.ebay.ch)
  • eBay Ireland (EBAY_IE, www.ebay.ie)
  • eBay Netherlands (EBAY_NL, www.ebay.nl)
  • eBay Poland (EBAY_PL, www.ebay.pl)
  • eBay Belgium (EBAY_BE, www.benl.ebay.be (Dutch) and www.befr.ebay.be (French))
  • eBay Hong Kong (EBAY_HK, www.ebay.com.hk)
  • eBay Philippines (EBAY_PH, www.ebay.ph)
  • eBay Malaysia (EBAY_MY, www.ebay.com.my)
  • eBay Singapore (EBAY_SG, www.ebay.com.sg)

The issueRefund and payment dispute methods can only be used by sellers opted in to eBay managed payments. eBay managed payments is currently only available to a limited number of US and German sellers, but this program is scheduled to become available to more sellers throughout 2019 and beyond.

Rate limits

The number of calls you can make per day using the Fulfillment API depends on your application's eBay compatibility level:

  • All applications: 100,000 calls/day
  • eBay compatible applications: 2,500,000 calls/day