This archive document contains information about releases earlier than the previous ten versions. For current releases, see Fulfillment API release notes.
| Release Version | Release Date | Description of Release |
|---|---|---|
| Version 1.19.13 | 2022-06-16 |
Effective July 1, 2022, eBay is required to collect and remit sales tax in Canada; the following changes have been incorporated in this release:
|
| Version 1.19.12 | 2022-05-31 |
Two error codes were added and three error codes were updated for the issueRefund method. |
| Version 1.19.11 | 2022-05-05 |
Added new Schema to support eBay's Vault program. |
| Version 1.19.10 | 2021-10-18 |
Changed the limit maximum value to 200 for getOrders method. |
| Version 1.19.9 | 2021-08-18 | Added two enumeration values (APPEAL_DENIED and APPEAL_GRANTED) for the ActivityEnum type. |
| Version 1.19.8 | 2021-07-26 | Added a new enumeration value (DISPUTE_REVERSED) for the ActivityEnum type. |
| Version 1.19.7 | 2021-06-21 | Updated description of Amount for the getOrder and getOrders methods; added VAT support to be collected in EU countries starting on July 1, 2021 |
| Version 1.19.6 | 2021-06-08 | Added new Schema to support the return of fulfillment program information. |
| Version 1.19.5 | 2021-06-01 | Added new Schema to support the return of VAT identifiers. |
| Version 1.19.4 | 2021-05-10 | Added new error code to the issueRefund method for seller-initiated refunds. |
| Version 1.19.3 | 2021-01-15 | Added a new enumeration value (DISPUTE_REOPENED) for the ActivityEnum type. |
| Version 1.19.2 | 2020-11-09 | Updated the getOrder and getOrders methods to return a cumulative total of fees accrued that are deducted from seller payouts. |
| Version 1.19.1 | 2020-10-21 | Added a new enumeration value for the PostSaleAuthenticationProgram type. |
| Version 1.19.0 | 2020-09-28 | Added a tax address container (taxAddress) that consists of address information that can be used by sellers for tax purposes and affects the getOrder and getOrders methods. |
| Version 1.18.0 | 2020-09-14 | Added new schema to getPaymentDispute method to provide details on monetary transactions that occur after payment disputes are resolved. As part of this project, the getPaymentDispute method was also updated to show currency conversion values for cross-border trade orders. |
| Version 1.17.0 | 2020-09-01 | Updated api type names, added new BOPIS seller/merchant evidence type (PROOF_OF_PICKUP) for buyer to pick up items directly from the store, and corrections to documentation. |
| Version 1.16.0 | 2020-08-24 | Added support for the Authenticity Guarantee service program to the getOrder and getOrders methods. The Authenticity Guarantee service program informs the seller of the authentication status of an order as it passes through the item authentication process. |
| 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.7.0 | 2019-01-24 | New field added to support Selling Manager order reference number |
| Version 1.6.0 | 2018-10-09 | New field to support items sold through ad campaign |
| Version 1.5.0 | 2018-07-12 | New types and fields to support AU import tax |
| Version 1.4.0 | 2018-05-30 | New fields to support legacy orders and email |
| Version 1.3.0 | 2017-10-11 | New field to support the Global Shipping Program; availability of OpenAPI specification |
| Version 1.2.0 | 2017-06-12 | New fields to support line item delivery timing |
| Version 1.1.0 | 2017-01-25 | Minor update |
| Version 1.0.0 | 2017-10-19 | Initial release of Version 1.0.0 |
Version 1.19.13
API updates
This API release contains the following updates.
eBay now collects and remits Canadian federal and provincial sales tax
Canadian federal and provincial sales tax information is now returned as part of the getOrder and getOrders methods.
Sales tax is now being collected for Digitally Delivered Goods (DDG)
Sales tax information collected on DDG is now returned as part of the getOrder and getOrders methods.
Version 1.19.12
API updates
This API release contains the following update.
New error codes
The following error codes were added to the issueRefund method:
| Code | Meaning |
|---|---|
| 34929 | You cannot refund this order yet since the buyer payment has not been processed. Please try again later. |
| 34930 | Default payment method limit exceeded. Please use a different payment option or try again later. |
Error code updates
The following issueRefund method error code meanings were updated:
| Code | Meaning |
|---|---|
| 34917 | This order was already refunded. |
| 34920 | It's too late to issue a refund for this order. |
| 34923 | Refund cannot be issued for this type of order. |
Version 1.19.11
API updates
This API release contains the following update.
New schema to support eBay's Vault program
The following schema changes have been made to the getOrder and getOrders methods in this release to support eBay's Vault program:
- ebayVault field added to Program type: This field provides information about the specific eBay Vault program selected for eligible items within an order.
- EbayVaultProgram type added: This type provides information about the eBay vault program that has been selected for an order and includes the following field:
- fulfillmentType: This field specifies how an eBay vault order will be fulfilled.
- New EbayVaultFulfillmentTypeEnum: Specifies which EbayVaultProgram has been selected for an order.
- New FULFILLED_BY_EBAY enumeration value added to FulfillmentInstructionsType: Indicates that eBay will package and ship an order as specified by fulfillmentType.
Version 1.19.10
API updates
This API release contains the following update.
Updated limit
The limit value (the number of orders to return per page of the result set) used by the getOrders method now has a maximum value of 200.
Version 1.19.9
API updates
This API release contains the following update.
New enumeration values
Two enumeration values were added to the ActivityEnum for the PaymentDisputeActivity type used by the getActivities method.
- APPEAL_DENIED: This enumeration value indicates eBay has declined the seller's appeal and upheld the original decision.
- APPEAL_GRANTED: This enumeration value indicates eBay has granted the seller's appeal.
Version 1.19.8
API updates
This API release contains the following update.
New enumeration value
A new enumeration value was added to the ActivityEnum for the PaymentDisputeActivity type used by the getActivities method.
The new enumeration value, DISPUTE_REVERSED, indicates that in the case of a dispute that was previously closed as Seller Lost, the decision has been reversed to Seller Won. eBay will credit back to the seller the amount that was recouped by eBay when the dispute was originally closed as Seller Lost.
Version 1.19.7
API updates
This API release contains the following updates.
Updated description for getOrder and getOrders methods
The description of Amount in the getOrder and getOrders methods was updated to remove these notes:
- Removed note for getOrder: This logic change does not apply to sellers opted in to eBay managed payments, and any 'Collect and Remit' tax is fully handled by eBay, and the proceeds of this tax is never distributed through seller payouts. Also, for sellers opted in to eBay managed payments, the lineItems.taxes array is returned empty.
- Removed note for getOrders: This logic change does not apply to sellers who are in eBay managed payments, so the amount in this field will never reflect any 'Collect and Remit' tax, even if the order is subject to 'Collect and Remit' tax.
Support for EU VAT tax collection added
This presently includes US state-mandated sales tax, 'Goods and Services' tax in Australia and New Zealand, and VAT collected for UK. Starting on July 1, 2021, VAT will be collected in EU countries. This update applies to the EbayCollectAndRemitTax type and the following fields for the getOrder and getOrders methods:
- ebayCollectAndRemitTax
- lineItems.total
- lineItems.ebayCollectAndRemitTaxes
- lineItems.ebayCollectAndRemitTaxes.amount
- paymentSummary.totalDueSeller
- paymentSummary.payments.amount
- pricingSummary.total
Version 1.19.6
API updates
This API release contains the following update.
New Schema Added to Support the Fulfillment Program
The following schema changes to the getOrder and getOrders methods were implemented in this release to support the return of fulfillment program information:
- fulfillmentProgram field added to the Program type: This field provides details about an order line item being handled by eBay fulfillment. It is only returned for paid orders being fulfilled by eBay or an eBay fulfillment partner.
- EbayFulfillmentProgram type added: This type is used to provide details about an order line item being fulfilled by eBay or an eBay fulfillment partner and includes the following field:
fulfilledBy: The value returned in this field indicates the party that is handling fulfillment of the order line item.
Valid value:
EBAY
Version 1.19.5
API updates
This API release contains the following update.
Note: The eBay VAT ID and buyer VATIN fields will not start getting returned until June 30, 2021. On January 31, 2022, the orders.fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.addressLine2 will stop being used to return VAT information, so developers should make sure they integrate with the new fields before that time.
New Schema Added to Support the Return of VAT Identifier Numbers
Schema changes including new enumeration values and fields were added with this release.
New TaxIdentifierTypeEnum
A new enumeration value was added to the TaxIdentifierTypeEnum for the TaxIdentifier type used by the getOrder and getOrders methods:
- VATIN: This value indicates that the taxpayerId value is a VATIN number, which is the value-added tax identification number for the buyer. This identifier is used for value added tax purposes in many countries, including the countries of the European Union.
New EbayTaxReference type
The EbayTaxReference type was added to the EbayCollectAndRemitTax type for the getOrder and getOrders methods. This type is used to indicate the eBay VAT tax type and the eBay VAT identifier number. This field will be returned if VAT tax is applicable for the order and contains the following fields:
- name: This field value is returned to indicate the VAT tax type, which will vary by country/region. This string value will be one of the following:
ABN: if this string is returned, the ID in the value field is an Australia tax IDIOSS: if this string is returned, the ID in the value field is an eBay EU or UK IOSS numberIRD: if this string is returned, the ID in the value field is an eBay New Zealand tax IDOSS: if this string is returned, the ID in the value field is an eBay Germany VAT IDVOEC: if this string is returned, the ID in the value field is an eBay Norway tax ID
- value: The value returned in this field is the VAT identifier number (VATIN), which will vary by country/region. This field will be returned if VAT tax is applicable for the order. The name field indicates the VAT tax type, which will vary by country/region:
- ABN: eBay AU tax ID
- IOSS: eBay EU IOSS number / eBay UK IOSS number
- IRD: eBay NZ tax ID
- OSS: eBay DE VAT ID
- VOEC: eBay NO number
New ItemLocation type
The new ItemLocation type was added to the LineItem type for the getOrder and getOrders methods. This type describes the physical location of an order and contains the following fields:
- countryCode: The two-letter ISO 3166 code representing the country of the address.
- location: Indicates the geographical location of the item (along with the value in the countryCode field). This field provides city, province, state, or similar information.
- postalCode: The postal code of the address.
Version 1.19.3
API updates
This API release contains the following update.
New enumeration value
A new enumeration value was added to the ActivityEnum for the PaymentDisputeActivity type used by the getActivities method.
The new enumeration value, DISPUTE_REOPENED, indicates that a previously closed payment dispute was reopened.
Version 1.19.2
API updates
The following new feature was added with this release.
getOrder and getOrders returns cumulative total of accrued selling fees
The new schema adds the following new Amount type container field that will be returned for each sales order containing market place fees:
- totalMarketplaceFee: This is the cumulative total of fees accrued for the order and deducted from the seller payout.
Version 1.19.1
API updates
This API release contains the following update.
New enumeration value
A new enumeration value was added to the AuthenticityVerificationReasonEnum for the PostSaleAuthenticationProgram type used by the getOrder and getOrders methods:
- NOT_AUTHENTIC_NO_RETURN: This enumeration value indicates that the order line item was found as counterfeit and cannot be returned to the seller because of legal constraints.
Version 1.19.0
API updates
This API release contains the following updates.
getOrder and getOrders returns new tax address container
A new tax address container (taxAddress) is now returned. This container consists of address information that can be used by sellers for tax purposes and affects the getOrder and getOrders methods. This container has the following fields:
- city: The city name that can be used by sellers for tax purpose.
- countryCode: The country code that can be used by sellers for tax purpose, represented as a two-letter ISO 3166-1 alpha-2 country code. For example, US represents the United States, and DE represents Germany.
- postalCode: The postal code that can be used by sellers for tax purpose. Usually referred to as Zip codes in the US.
- stateOrProvince: : The state name that can be used by sellers for tax purpose.
Version 1.18.0
API updates
This API release contains the following updates.
Schema updates
The following new types were added with this release. These types are all used by the getPaymentDispute method.
- DisputeAmount
- MonetaryTransaction
- MonetaryTransactionReasonEnum
- MonetaryTransactionTypeEnum
The following new fields were added with this release. These types are all used by the getPaymentDispute method.
- monetaryTransactions: new array under PaymentDispute type
- protectedAmount: new field under PaymentDisputeOutcomeDetail type
- totalFeeCredit: new field under PaymentDisputeOutcomeDetail type
The following enumeration value was added to DisputeReasonEnum type: AUTHORIZATION_FAILED
Monetary transaction details now returned with getPaymentDispute
The monetaryTransactions container added to the getPaymentDispute response provides details on one or more monetary transactions that may occur when a payment dispute between a buyer and seller is resolved. Details include transaction type, transaction reason, transaction date, and transaction amount.
getPaymentDispute enhanced for active cross-border trade orders
To account for active cross-border trade orders that require currency conversion, the getPaymentDispute method was enhanced to show both the listing site's currency, the seller's default currency, and the exchange rate used for the conversion. This data is shown under the new monetaryTransactions.amount container in the response. The DisputeAmount type was added to support this capability.
Two new fields added to PaymentDisputeOutcomeDetail type
The following new fields were added to the PaymentDisputeOutcomeDetailtype.
- protectedAmount: this field shows the amount of money that the seller is protected against in a payment dispute under eBay's seller protection policy.
- totalFeeCredit: this field shows the amount of money in selling fee credits due back to the seller after a payment dispute is settled.
Version 1.17.0
API updates
This API release contains the following update.
Changed type names
This release modifies the field names for the following types:
| Previous type name | New type name | Affected method |
|---|---|---|
| AddEvidenceRequest | AddEvidencePaymentDisputeRequest | addEvidence |
| AddEvidenceResponse | AddEvidencePaymentDisputeResponse | addEvidence |
| UpdateEvidenceRequest | UpdateEvidencePaymentDisputeRequest | updateEvidence |
Added new BOPIS seller/merchant evidence type
A new evidence type is available that provides documentation when an online buyer picks up items from store directly. The following new evidence type was added to the EvidenceTypeEnum and affects the getPaymentDispute, addEvidence, and updateEvidence methods of payment_dispute:
PROOF_OF_PICKUP- This enumeration value indicates that the evidential documentation is for buy online, pick up in store.
Documentation changes
Corrections were made that clarified the definitions of Fulfillment API seller payment fields.
Version 1.16.0
API updates
This API release contains the following update.
Support for the new Authenticity Guarantee service program added to the getOrder and getOrders methods
A program container is now returned for order line items going through the authenticity verification process. This container gives the current status and outcome of an authentication verification inspection.
Schema Changes
These are the new types added for this release.
PostSaleAuthenticationProgram: This type is used to provide the status and outcome of an order line item going through the Authenticity Guarantee service verification process.AuthenticityStatusEnum: The value in this field indicates whether the order line item has passed or failed the authenticity verification test, or if the test and/or results are still pending. The possible values returned here are PENDING, PASSED, FAILED, and PASSED WITH EXCEPTION.AuthenticityVerificationReasonEnum: This field indicates the result of the authenticity verification test on an order line item. This field is not returned when the status value of the order line item is PENDING or PASSED. The possible values returned here are NOT AUTHENTIC, NOT AS DESCRIBED, CUSTOMIZED, and MISCATEGORIZED.
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 type:
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 disposal tax for white goods was charged to the buyer against the order line item (White Goods Disposal Tax). 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 toTAX_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 toTAX_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 toTAX_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 toTAX_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 toTAX_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 toTAX_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
- getOrders:
GET /order - getOrder:
GET /order/{orderId} - issueRefund:
POST /order/{order_id}/issue_refund
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
- getOrders:
GET /order - getOrder:
GET /order/{orderId}
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
- getOrders:
GET /order - getOrder:
GET /order/{orderId}
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
- getOrders:
GET /order - getOrder:
GET /order/{orderId}
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
- getOrders:
GET /order - getOrder:
GET /order/{orderId}
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
- getOrders:
GET /order - getOrder:
GET /order/{orderId}
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
- getOrders:
GET /order - getOrder:
GET /order/{orderId}
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
- getOrders:
GET /order - getOrder:
GET /order/{orderId}
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.
Download Fulfillment API JSON specification (beta)
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
- getOrders:
GET /order - getOrder:
GET /order/{orderId}
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
- getOrders:
GET /order
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.