fulfillment APIv1.15.0

Fulfillment API release notes

Just getting started with the Fulfillment API? See the following documents for details on using this API:

The API release history

The following table lists the releases for the Fulfillment API:

Version

Release Date

Summary of Release

Version 1.15.0

2020-07-09

Updated getOrder and getOrders methods to return selling fees that are deducted from seller payouts. Also, added a new PaymentMethodTypeEnum enumeration value.

Version 1.14.0

2020-06-19

Added support for providing optional breakdown of taxes and fees to getOrder and getOrders methods.

Version 1.13.0

2020-05-05

Five new payment method enums added to handle eBay managed payments and offline payment methods.

Version 1.12.0

2020-03-31

Five new payment dispute methods for sellers opted in to eBay managed payments.

Version 1.11.1

2020-01-17

New error code for the issueRefund method.

Version 1.11.0

2019-10-30

Four new payment dispute methods for sellers opted in to eBay managed payments.

Version 1.10.1

2019-10-24

Logic change for eBay 'Collect and Remit' taxes and two new error codes for the issueRefund method.

Version 1.10.0

2019-08-08

getOrder and getOrders now return refundId values created with issueRefund method.

Version 1.9.0

2019-06-24

New issueRefund method for sellers opted in to eBay managed payments.

Version 1.8.0

2019-02-11

getOrder and getOrders now support In-Store Pickup orders.

Version 1.9.0

2019-06-24

New issueRefund method for sellers opted in to eBay managed payments.

Version 1.15.0

API updates

The following new feature was added with this release.

getOrder and getOrders returns selling fees that are deducted from seller payouts

For payments sellers who are subject to having final value fees deducted from seller payouts, a new amount field will be returned for each sales transaction.

The new schema adds the following field:

  • totalFeeBasisAmount: this field is the cumulative base amount used to calculate the final value fees for each order. The final value fees are deducted from the seller payout associated with the order. Final value fees are calculated as a percentage of order cost (item cost + shipping cost) and the percentage rate can vary by eBay category.

A new payment method enumeration value added

A new payment method enumeration value may now be returned by getOrder/getOrders. The following enumeration value was added to the PaymentMethodTypeEnum:

  • ESCROW: This enumeration value indicates that the buyer used Escrow to pay for the order. This form of payment is used for high-value orders

Version 1.14.0

API updates

This API release contains the following update.

New query parameter added to getOrder and getOrders

This release adds a new fieldGroups query parameter to getOrder/getOrders methods. When set to TAX_BREAKDOWN, this parameter includes a breakdown of applied taxes and fees in the returned order object. To support this feature, enumeration values were added to taxes. The following list describe existing and new values:

Existing enumeration values:

  • GST: This enumeration value indicates that a Goods and Services import tax was charged to the buyer against the order line item. This tax type is only applicable to items being sold in Australia and New Zealand to buyers outside of these two countries.

  • PROVINCE_SALES_TAX: This enumeration value indicates that provincial sales tax was charged to the buyer against the order line item. In states and provinces that mandate sales tax, any sales tax rate set up by the seller for the buyer's province will be ignored, and the seller is not involved with the collection of this tax at all.

  • REGION: This enumeration value indicates that regional sales tax was charged to the buyer against the order line item. In regions that mandate sales tax, any sales tax rate set up by the seller for the buyer's region will be ignored, and the seller is not involved with the collection of this tax at all.

  • STATE_SALES_TAX: This enumeration value indicates that US state sales tax was charged to the buyer against the order line item. In states that mandate sales tax, any sales tax rate set up by the seller for the buyer's state will be ignored, and the seller is not involved with the collection of this tax at all.

  • VAT: This enumeration value indicates that Value-Added tax (VAT) was charged to the buyer against the order line item. VAT is not applicable in all countries, including the United States.

New enumeration values (available when fieldGroups is set to TAX_BREAKDOWN)

  • WHITE_GOODS_DISPOSABLE_TAX: This enumeration value indicates that the tax on disposable white goods was charged to the buyer against the order line item. White goods includes items like refrigerators, ranges, water heaters, freezers, unit air conditioners, washing machines, clothes dryers, and other similar domestic and commercial large appliances. Only available when fieldGroups is set to TAX_BREAKDOWN.

  • ELECTRONIC_RECYCLING_FEE: This enumeration value indicates that an Electronic Recycling Fee was charged to the buyer against the order line item. This fee is imposed on the retail sale or lease of certain electronic products that have been identified as covered electronic devices (CEDs). Only available when fieldGroups is set to TAX_BREAKDOWN.

  • MATTRESS_RECYCLING_FEE: This enumeration value indicates that a mattress waste recycling fee was charged to the buyer against the order line item for each mattress, box spring, foundation, and base sold. This recycling fee is per piece. Only available when fieldGroups is set to TAX_BREAKDOWN.

  • ADDITIONAL_FEE: This enumeration value indicates that an additional recycling fee was charged to the buyer against the order line item. Only available when fieldGroups is set to TAX_BREAKDOWN.

  • BATTERY_RECYCLING_FEE: This enumeration value indicates that the battery recycling fee was charged to the buyer against the order line item. Only available when fieldGroups is set to TAX_BREAKDOWN.

  • TIRE_RECYCLING_FEE: This enumeration value indicates that the tire recycling fee was charged to the buyer against the order line item. Only available when fieldGroups is set to TAX_BREAKDOWN.

Version 1.13.0

API updates

This API release contains the following update.

Five new payment method enums added

Five new payment method enum values may now be returned in getOrder/getOrders. These enumeration values were added to the PaymentMethodEnum type, and were added to handle eBay managed payments and offline payment methods. Below is the complete list of these new enumeration values:

  • EBAY: this value indicates that the order is an eBay managed payments order. With eBay managed payments, eBay handles payment from the buyer, and then distributes the funds to the seller's account via a 'seller payout'.
  • CASHIER_CHECK: this value indicates that the buyer paid for the order with a cashier's check. Payment with a cashier's check can only happen off of eBay's platform.
  • PERSONAL_CHECK: this value indicates that the buyer paid for the order with a personal check. Payment with a personal check can only happen off of eBay's platform.
  • CASH_ON_PICKUP: this value indicates that the buyer paid for the order with cash. Payment with cash can only happen off of eBay's platform.
  • EFT: this value indicates that the buyer paid for the order with an Electronic Funds Transfer (EFT). Payment with EFT can only happen off of eBay's platform.

Version 1.12.0

API updates

This API release contains the following updates.

Five new payment dispute methods

Five new payment dispute methods added to the payment_dispute resource. These five 'POST' methods include the following:

  • acceptPaymentDispute: used to accept a buyer-inititated payment dispute for a managed payment order
  • contestPaymentDispute: used to contest a buyer-inititated payment dispute for a managed payment order
  • uploadEvidenceFile: used to upload an image file that will be used on the seller's behalf to contest the payment dispute
  • addEvidence: used to create an evidence set with one or more evidence files
  • updateEvidence: used to add one or more evidence files to an existing evidence set

See the Resources Index Page for links to these five new methods

New taxIdentifier container returned in getOrder

A new taxIdentifier container returned in getOrder method for orders occurring on the eBay Spain and eBay Italy marketplaces. The taxIdentifier container provides tax ID information for buyers residing in Spain, Italy, or Guatemala.

New error codes for issueRefund method

The following three error codes were added to the issueRefund method:

Error Code Description
34925 The refund operation could not be completed with any of the payment methods saved to the seller's account.
34926 A suitable payment method could not be found for the refund operation. Please resolve in Seller Hub.
34927 The selected payment method for the refund operation was invalid or declined.

Version 1.11.1

API updates

This API release contains the following update

New Error Code

The following error code was added for the issueRefund method:

  • 34924: The item refund amount exceeds the item remaining amount.

Version 1.11.0

Four new payment dispute methods added to the API. These four 'GET' methods allow a seller (opted in to eBay managed payments) retrieve details on any payment disputes that are initiated by buyers outside of eBay's (Buyer Protection/Resolution Center) system.

Version 1.10.1

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Calls

Schema changes

New collectionMethod value returned for 'Collect and Remit' taxes

For orders/line items subject to eBay 'Collect and Remit' tax, a new collectionMethod field will be returned under the lineItems.ebayCollectAndRemitTaxes container in getOrder/getOrders responses. To support this new field and supported values, the CollectionMethodEnum type was also added.

Beginning in early November 2019, for orders that are subject to 'eBay Collect and Remit' tax, which includes US state-mandated sales tax and 'Good and Services' tax in Australia and New Zealand, the 'Collect and Remit' tax amount for the order will be included in various order total and line item total fields.

To determine if 'Collect and Remit' taxes were added into these order total and line item total fields, the user can check for the lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with a taxType value of STATE_SALES_TAX (in US) or GST (in Australia or New Zealand), the 'Collect and Remit' tax amount that the buyer paid are in these amounts.

Sellers should be aware that the 'Collect and Remit' tax that the buyer pays for the order will initially be included when the order funds are distributed to their PayPal account, but that PayPal will pull out the 'Collect and Remit' tax amount shortly after the payment clears, and will distribute the tax to the appropriate taxing authority. Previous to this change, PayPal would strip out the 'Collect and Remit' tax before distributing order funds to the seller's account.

This logic change does not apply to sellers who are in eBay managed payments, and for orders that are subject to 'Collect and Remit' tax, the lineItems.ebayCollectAndRemitTaxes container will still appear, but eBay will fully handle the tax distribution, and these tax proceeds will never be a part of a seller payout. The lineItems.taxes container will appear as an empty array.

New Error Codes

The following error codes were added for the issueRefund method:

  • 34922: Refund can't be issued while previous refund is processing.
  • 34923: Refund can’t be issued for this type of order (seller created order).

Version 1.10.0

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Calls

Schema changes

New refundId value returned for eBay managed payments refunds

For refunds initiated through the issueRefund method, a new refundId field will be returned in getOrder/getOrders responses. A refundId value is generated in the response of a successful issueRefund call, and this same value will be returned in getOrder/getOrders responses so seller can track the status of the refund. For order-level refunds, the refund identifier can be found in the paymentSummary.refunds.refundId field, and for line item level refunds, the refund identifier(s) can be found in the lineItems.refunds.refundId field(s).

Version 1.9.0

New issueRefund method added to the API. This method 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.

Version 1.8.0

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Calls

Schema changes

New type, field, and enumeration value to support In-Store Pickup orders

The getOrders and getOrder methods now return the pickupStep container for In-Store Pickup orders. The PickupStep complex type was added to support this container. For In-Store Pickup and Click and Collect orders, the enumeration value returned in the fulfillmentInstructionsType field will be PREPARE_FOR_PICKUP. The PREPARE_FOR_PICKUP enumeration value was already defined in FulfillmentInstructionsType and applicable to Click and Collect orders, but this value is also applicable to In-Store Pickup orders.

The merchantLocationKey field returned under the pickupStep container will indicate the specific merchant store where the buyer will pick up the order.

Note: The In-Store Pickup feature is supported in the US, Canada, UK, Germany, and Australia marketplaces.

Doc changes

Made a correction to maxEstimatedDeliveryDate and minEstimatedDeliveryDate descriptions

The maxEstimatedDeliveryDate and minEstimatedDeliveryDate field descriptions incorrectly stated that these fields are not returned for In-Store Pickup and Click and Collect orders (when the fulfillmentInstructionsType field's value is PREPARE_FOR_PICKUP). This is actually not true.

For both In-Store Pickup and Click and Collect orders, the date range specified with the maxEstimatedDeliveryDate and minEstimatedDeliveryDate fields is when the order must be ready for pickup at the store that the buyer selected at checkout.

Version 1.7.0

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Calls

Schema changes

New field added to support Selling Manager order reference number

The getOrders and getOrder methods now return the salesRecordReference field at the order level. The value in this field is an eBay-generated identifier that is used to identify and manage orders through the Selling Manager and Selling Manager Pro tools. This order identifier can also be found under the Orders tab in Seller Hub.

Announcement

Fulfillment API is now available for all eBay marketplaces

The Fulfillment API is supported on all eBay marketplaces that support selling and order management. For a full list of supported eBay marketplaces, see the Supported marketplaces section in the API Overview Page.

Doc Change

Buyer emails not returned two weeks after order creation

Updated the description for the shipTo.email field to indicate that the buyer's email address stops getting returned two weeks after order creation.

Version 1.6.0

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Calls

Schema changes

New field to support items sold through ad campaign

The getOrders and getOrder methods now return the properties.soldViaAdCampaign boolean field at the order line item level to indicate if a line item was sold to a buyer who was routed to the listing through a Promoted Listings ad campaign.

Announcement

'eBay Collect And Remit Tax' fields now handle sales tax

The ebayCollectAndRemitTaxes boolean field, returned at the order level, and the ebayCollectAndRemitTaxes container, returned at the line item level, no longer only pertain to Australian import tax charged to Australian buyers, but to sales tax collected in some states and provinces. The type of tax collected by eBay and remitted to the appropriate taxing authority is indicated in the ebayCollectAndRemitTaxes.taxType field.

Version 1.5.0

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Calls

Schema changes

New boolean field added to indicate AU import tax

The getOrders and getOrder methods now return the ebayCollectAndRemitTax boolean field if an order is subject to Australian import tax charged to the buyer.

New ebayCollectAndRemitTaxes container added at line item level

The getOrders and getOrder methods now return the ebayCollectAndRemitTaxes container if an order line item is subject to Australian import tax charged to the buyer. This container states the amount of import tax collected by eBay and remitted to the Australian government. To support this new feature, the TaxTypeEnum type was also added. The ebayCollectAndRemitTaxes container may be applicable to other tax types and tax jurisdictions in the future.

Version 1.4.0

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Calls

Schema changes

New fields to support legacy API order processing

The getOrders and getOrder calls now return the legacyOrderId field in addition to the orderId field. Both fields identify the same order, and both fields are always returned, but the legacyOrderId field is formatted to be compatible with legacy APIs such as Trading and Post-Order, and the orderId field is compatible with RESTful APIs such as Fulfillment. Use the value of legacyOrderId instead of the value of orderId with APIs that require a legacy order ID.

New email contact field

The getOrders and getOrder calls now return the email field as part of the fulfillmentStartInstructions.shippingStep.shipTo container. This field (the buyer's email address) is returned only within 14 days of order creation. The email field always contains the email address of the buyer, even with a Global Shipping Program shipment that's addressed to the global shipping provider's domestic warehouse.

Version 1.3.0

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Calls

Schema changes

New field to support the Global Shipping Program

The getOrders and getOrder calls now return the fulfillmentStartInstructions.shippingStep.shipToReferenceId field, which supports eBay's Global Shipping Program by providing the seller with an identifier for the shipment. The seller must include the value of shipToReferenceId on the shipping label immediately above the street address of the international shipping provider. The international shipping provider uses it to retrieve essential information necessary to complete the international leg of the shipment.

Announcement

Availability of OpenAPI Specification

This release of the Fulfillment API includes Beta version downloadable JSON and YAML formats of the API contract that comply with version 2.0 of the OpenAPI Specification. The OpenAPI Specification is a widely adopted standard for describing RESTful APIs. The eBay API specification files can facilitate your development process through the ability to generate client code in numerous languages, using the Swagger-Codegen tools, as well as the ability to easily view and test the API via the Swagger UI projects. Development of the OpenAPI Specification is overseen by the Open API Initiative, an open source collaborative project of the Linux Foundation.

Note: If you want to use the Swagger editing tool for viewing and testing, we advise you use the version of the editor that is compatible with 2.0 OpenAPI specifications: https://editor2.swagger.io/

Read the eBay API documentation for comprehensive API details, including allowed values, constraints, method-specific error messages, and implementation details.

File download     Download Fulfillment API JSON specification (beta)

File download     Download Fulfillment API YAML specification (beta)

Version 1.2.0

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Calls

Schema changes

New fields to support line item delivery timing

The getOrders and getOrder calls now return the lineItemFulfillmentInstructions container, which supports eBay Guaranteed Delivery by providing guidance for handling and delivery timing when fulfilling a line item. It also provides such information for non-guaranteed delivery. For details, see the documentation for the LineItemFulfillmentInstructions type.

Announcements

Coming soon: eBay Guaranteed Delivery

Later in Summer 2017, eBay will introduce the eBay Guaranteed Delivery program. Sellers who opt in will be able to guarantee the delivery date of an item based on the following criteria:

  • The item is of a type, size, weight, and location defined by the seller as available for eBay Guaranteed Delivery in a shipping rate table.
  • The seller is offering the item with eBay Guaranteed Delivery.
  • The buyer is located in a destination region that can be shipped to within the delivery window of at least one shipping service category (e.g. One-day, Expedited, Standard, or Economy) for which eBay Guaranteed Delivery is offered by the seller for the item.

Sellers will be able to choose to support the entire handling and delivery timing door-to-door, or just the handling period (same-day or one-day). With the handling-period-only option, eBay will determine and guarantee the actual delivery date on behalf of the seller, and will take responsibility for that guarantee.

The Fulfillment API now provides the lineItemFulfillmentInstructions container, with fields that assist sellers to determine the handling and shipping time requirements and the status of purchased Guaranteed Delivery line items.

Note: eBay Guaranteed Delivery is being rolled out in phases.

In phase one, the new lineItemFulfillmentInstructions container is now available so you can plan your application development to incorporate it. Until phase three, the boolean guaranteedDelivery field will return a value of false.

In phase two (planned for August 2nd), sellers will be able to opt in to the eBay Guaranteed Delivery program and use new shipping rate tables to define which items they plan to offer with Guaranteed Delivery. They will also be able to define their work week, and the handling cutoff time for each day of the work week.

In phase three (planned for September 20th), you will be able to use the Account API to retrieve the new rate tables and define fulfillment policies that incorporate Guaranteed Delivery into listings specified by your sellers. Buyers will then see and be able to take advantage of the Guaranteed Delivery option for those listings.

Version 1.1.0

The following sections detail the updates that have been made for this release.

API updates

This API release contains the following updates and changes:

Changed Call

Schema changes

Additional enforcement for order search date range

Two of the available criteria for the getOrders call's filter parameter are date ranges: creationdate and lastmodifieddate. The call can return several error codes for dates that don't comply with the permitted date ranges for these criteria. A new error code has been added:

Code

Domain

Category

Nature

Meaning

30850

API_FULFILLMENT

REQUEST

ERROR

Start and end dates can't be in the future

Documentation changes and errata

Orders requiring upfront payment must be paid to be fulfilled

This documentation previously stated that the Fulfillment API covers transactions that have completed the checkout process. The documentation has been updated to clarify that this includes all paid purchases and purchases that do not require upfront payment (e.g., COD), but does not include pending payment purchases that require upfront payment before shipment.

Version 1.0.0

This is the initial release of the Fulfillment API, Version 1.0.0. For a list of the new calls, see the Fulfillment API Reference.

The following sections detail the updates that have been made for this release.

Documentation changes and errata

Creating a shipping fulfillment can occasionally fail

The createShippingFulfillment call can occasionally return an HTTP 500 error due to an internal server issue. However, in some cases this call may succeed if you issue it once more after receiving this error.

getOrders call does not return cancellation requests

Currently, for the getOrders call, the cancelStatus.cancelRequests array is returned but is always empty. To retrieve any active cancellation requests for an order, you must use the getOrder call.