fulfillment APIv1.15.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 API does not cover pending payment purchases that require upfront payment before shipment.

In addition to the 'get orders' and 'shipping fulfillment' methods, the Fulfillment API also has a seller-initiated issueRefund method and a full suite of payment dispute methods. These methods can only be used by sellers that are opted in to eBay managed payments.

The issueRefund method allows a seller to issue a full or partial refund to a buyer for a managed payments order. Full or partial refunds can be issued at the order level or line item level.

The payment dispute methods allow the seller to retrieve and manage buyer-initiated payment disputes. These particular payment disputes are disputes that buyers open up with their payment provider, such as PayPal or Visa, and then the seller is alerted once the payment disputes come into eBay's system

This overview covers the following Fulfillment API topics:

Business use cases

This section outlines the business use cases addressed by the Fulfillment API.

Retrieve orders that need to be fulfilled

You can retrieve known orders using the getOrder method, or the getOrders method allows you to search for orders by creation date, modification date, or fulfillment status. See Discovering unfulfilled orders.

Fulfill orders

Use the createShippingFulfillment method to associate shipping packages and tracking numbers with one or more line items of the order. See Handling unfulfilled line items.

Manage fulfillments

You can retrieve the status of all fulfillments of an order by using the getShippingFulfillments method, or the can retrieve a specific fulfillment by using the getShippingFulfillment method. 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.

Manage buyer-iniated payment disputes

For sellers enrolled in eBay managed payments, 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 allows sellers to discover these types of disputes. In addition to 'get' calls that retrieve payment disputes that have been created, there are also operations to accept or contest these payment dispute, and operations to upload image files to support the seller's case if a seller decides to contest a payment dispute.

Fulfillment API requirements and 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 method and all payment dispute methods can only be used by sellers opted in to eBay managed payments, and this program is currently only available to a limited number of sellers on the US and Germany marketplaces. However, the managed payments program is scheduled to become available to more countries and sellers throughout 2020.

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