fulfillment API1.10.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 an issueRefund method that allows a seller (opted in to eBay Managed Payments) 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 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

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.

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 method 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 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