Just getting started with the Order API? See the following documents for details on using this API:
See the API Site Status for announcements regarding recently resolved or current system wide issues. Visit the Developer Support page for support options and information on filing bugs.
The API release history
The following table lists recent Order API releases. For older releases, see the Order API Release Notes Archive.
|
Release Version |
Release Date |
Description of Release |
|---|---|---|
|
2020-10-13 |
Added a new fee enumeration value to support the white goods disposal tax |
|
|
2020-10-01 |
Added support for the Singapore (SG) marketplace to the Order API |
|
|
2020-09-24 |
|
|
|
2020-07-17 |
Added a new error message to the initiateCheckoutSession method |
|
|
2020-07-14 |
Added a new purchaseOrderWebUrl container to the getPurchaseOrder method response |
|
|
2020-07-09 |
Added support for line item fee details |
|
|
2020-06-01 |
Added a new error message |
|
|
2020-02-20 |
Added support for Australian 'Good and Services' tax |
|
|
2020-01-08 |
|
|
|
2019-09-30 |
Removed duplicate coupon error messages |
|
|
2019-08-22 |
Changes to error messages |
|
|
2019-05-29 |
|
|
|
2019-05-23 |
|
|
|
2019-04-15 |
Added support for the EBAY_CA marketplace |
|
|
2019-04-08 |
Added fields to support returning coupon information by getPurchaseOrder |
|
|
2019-03-04 |
Improved existing error messages and added new errors |
|
|
2019-02-19 2019-01-28 |
|
|
|
2019-01-23 |
|
v1_beta.27.0
A new WHITE_GOODS_DISPOSABLE_TAX value was added to the FeeEnum type to support the white goods disposal tax. When this enumeration value is returned, it indicates that a disposal tax on white goods was charged to the buyer against the order line item.
Note: 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.
v1_beta.26.0
Support for the Singapore (SG) marketplace has been added to the Order API.
v1_beta.25.2
The following sections describe the changes implemented in this release.
Added a new error message
A new error message was added to the initiateCheckoutSession method.
|
Error ID |
Description |
|---|---|
| 15051 | Additional user details required. Please complete your registration or contact eBay customer support. |
Updated an error message
The description for error message 15017 was updated as shown in the table below. This affects the initiateCheckoutSession, initiateGuestCheckoutSession, and initiateProxyGuestCheckoutSession methods.
|
Error ID |
Description |
|---|---|
| 15017 | The payment for the order line items in your cart could not be processed due to issues with one or more sellers. |
v1_beta.25.1
The following section describes the changes implemented in this release.
Added a new error message
A new error message was added to the initiateCheckoutSession method.
|
Error ID |
Description |
|---|---|
| 15050 | Your transaction cannot be completed with the given information. Contact eBay customer service. |
v1_beta.25.0
The following section describes the change implemented in this release.
Added a new purchaseOrderWebUrl container
A new purchaceOrderWebUrl container was added to the response of the getpurchaseOrder method. This new container returns the URL to the Order Details page on eBay.
v1_beta.24.0
The following sections describe the changes implemented in this release.
Added a new fees container
A new lineItem.fees container was added to the checkout and order methods. This new container provides a breakdown of the fees applicable to the line item, such as the type of fee and the fee amount.
Schema changes
To support this update, the following new types were added:
- Fee type
- FeeEnum type
- fees field added to OrderLineItem type
- fees field added to LineItem type
v1_beta.23.1
The following section describes the changes implemented in this release.
Added a new error message
A new error message was added to the following resource methods:
- initiateCheckoutSession
- initiateGuestCheckoutSession
- initiateProxyGuestCheckoutSession
- updateGuestPaymentInfo
- updateGuestShippingAddress
- updatePaymentInfo
- updateProxyGuestPaymentInfo
- updateProxyGuestShippingAddress
- updateShippingAddress
|
Error ID |
Description |
|---|---|
| 17002 | Invalid character(s) found in the shipping address. Please check name and shipping address fields, remove invalid character(s) and resubmit the call. |
v1_beta.23.0
This release contains the following changes.
Added support for Australian 'Good and Services' tax
If 'Good and Services' tax is applicable to one or more line items in an order, the new importTax container will be returned under the pricingSummary container. The total amount of 'Good and Services' tax for all line items of the order is shown in this container.
Schema changes
To support the 'Goods and Services' tax update, the following new types were added:
- ImportTax type
- ImportTaxTypeEnum type
- importTax field added to PricingSummary type
v1_beta.22.1
This release contains the following changes.
Changed postalCode to optional when shipping to HK
When shipping an item to EBAY_HK - Hong Kong (ebay.com.hk), the ShippingAddress.postalCode field is optional.
Added warning messages
Two warning messages were added to the following methods.
- initiateCheckoutSession
- getCheckoutSession
- initiateGuestCheckoutSession
- getGuestCheckoutSession
- initiateProxyGuestCheckoutSession
- getProxyGuestCheckoutSession
|
Warning ID |
Description |
|---|---|
| 20000 | This order contains the item {itemId} that may be subject to certain importation permitting/licensing requirements. Please check applicable regulations for specific import restrictions in your country. |
| 20001 | This item {itemId} ships via a freight carrier. For information regarding shipping, tracking, delivery, etc. check with the seller. |
v1_beta.22.0
In this release, the following error messages were removed from the add coupon methods. These errors were duplicates of other error messages.
|
|
Error ID |
Message |
|---|---|---|
|
Removed error |
16011 Duplicate of 16004 |
The coupon has not been activated. The coupon was ignored and no discount was applied to this order. |
|
Removed error |
16021 Duplicate of 16012 |
The coupon is not valid for the {fieldName}. The coupon was ignored and no discount was applied to this order. |
v1_beta.21.0
In this release, one error message was added and the error message of one error was changed for clarity.
|
|
Error ID |
Message |
Methods |
|---|---|---|---|
|
New error |
15049 | There is some issue with this payment. Contact eBay developer support for assistance. | placeGuestOrder placeProxyGuestOrder |
|
Improved message |
17000 |
New message:
Old message:
|
placeOrder placeGuestOrder placeProxyGuestOrder |
v1_beta.20.0
In this release, two error messages were added and a unique line item order ID field was added.
Added error messages
In this release, the following two error messages were added.
|
Error ID |
Message |
Methods |
|---|---|---|
| 15047 | In compliance with applicable economic sanctions and trade restrictions, eBay is unavailable in your location. If you believe you are receiving this notice in error, please contact eBay's Customer Service. |
initiateCheckoutSession initiateGuestCheckoutSession initiateProxyGuestCheckoutSession updateShippingAddress updateGuestShippingAddress updateProxyShippingAddress |
| 15048 | The value of {fieldName} is too long. For more information, see the documentation for this call. |
Added a unique line item order ID field (for future use)
Added the lineItems.orderId field to the getGuestPurchaseOrder and getPurchaseOrder methods.
This field returns the new eBay unique order ID as a string. This is being rolled out starting in Summer 2019. In the future, this will replace the lineItems.legacyReference fields you use in the Post Order API. For details see, Easier order management with updated order numbers.
v1_beta.19.0
Added import charges and shipment tracking information fields
The following fields were added to support import charges (for the Global Shipping Program) and the shipment tracking information.
|
Field |
Description |
Method |
|---|---|---|
| lineItems.shippingOptions.importCharges | The Global Shipping Program import charges for a specific line item. | checkout methods: apply, get, initiate, remove, and update |
| pricingSummary.importCharges | The sum of the Global Shipping Program import charges for all line items. |
checkout methods: apply, get, initiate, remove, and update getGuestPurchase Order getPurchaseOrder |
| shippingFulfillments.shipmentTrackingEvents.description | A string describing the tracking event. For example: On FedEx vehicle for delivery |
getPurchaseOrder |
| shippingFulfillments.shipmentTrackingEvents.eventDate | The date of the shipment tracking event. UTC Format: yyyy-MM-ddThh:00:00.000Z For example: 2019-03-01T12:12:00.000Z |
getPurchaseOrder |
| shippingFulfillments.shipmentTrackingEvents.eventType | A normalized string for shipment tracking event. For example: OUT_FOR_DELIVERY |
getPurchaseOrder |
| shippingFulfillments.shipmentTrackingEvents.location.city | The city where the tracking event occurred. | getPurchaseOrder |
| shippingFulfillments.shipmentTrackingEvents.location.country | The two letter code representing the country of the address where the tracking event occurred. | getPurchaseOrder |
| shippingFulfillments.shipmentTrackingEvents.location.county | The county where the tracking event occurred. | getPurchaseOrder |
| shippingFulfillments.shipmentTrackingEvents.location.postalCode | The postal code where the tracking event occurred. | getPurchaseOrder |
| shippingFulfillments.shipmentTrackingEvents.location.stateOrProvince | The state where the tracking event occurred. | getPurchaseOrder |
New Requirements for Global Shipping Program
The following are new user experience requirements for guest checkout when using the Global Shipping Program:
- For total shipping cost - You must show the import charges amount. See Total Shipping Cost for details.
- For total cost - You must breakdown of the charges and show the details regarding shipping and import costs. See Total Cost for details.
Error message changes
In this release, two error messages were added and one error message was changed.
|
|
Error ID |
Message |
Methods |
|---|---|---|---|
|
Existing message, added to 2 methods |
15012 | There is a limit on the quantity of this item that can be purchased. Reduce the quantity and resubmit the call. |
placeOrder placeGuestOrder |
| New message | 15046 | One or more of the mandatory values is missing for marketingChannels and/or marketingTypes. For help, refer to the placeGuestOrder call documentation and resubmit the call. |
placeGuestOrder placeProxyGuestOrder |
| Changed message | 15044 | At least one of the items in the cart cannot be purchased using this API. The purchase can be done on eBay, through the eBay app or eBay website. |
initiateCheckoutSession initiateGuestCheckoutSession initiateProxyGuestCheckoutSession |
Marketing consent requirement changes
In prior releases, the marketing consent requirements were different across marketplaces. With this release, the requirements for all marketplaces are:
Requirement changes for the buy button page
- You must expose the marketing consent message.
- You must expose an expressed marketing consent checkbox.
- When the checkbox appears:
- For marketplaces other than the US, the checkbox is to be disabled (un-checked).
- For the US, the checkbox is to be enabled (checked).
Fields requirement changes for guest place order methods:
All marketingTerms fields are required and you must pass in all the valid values for marketingTypes, even if marketingTermsAccepted is set to false. See the Sample for details.
- marketingTerms.marketingChannels
"marketingChannels": [ "EMAIL" ]
- marketingTerms.marketingTermsAccepted
"marketingTermsAccepted": false|true,
- marketingTerms.marketingTypes
"marketingTypes": [ "OFFER", "PROMOTION", "SURVEY" ]
v1_beta.18.0
You can now use the Order API for checkout and with the eBay Member and eBay Guest PayPal Smart Button payment flows on the Canada (ebay.ca) site. The Canada site supports both English and French.
- EBAY_CA - Canada (ebay.ca)
- English is the default
- For French set accept-language to
fr-CA
v1_beta.17.0
The following fields were added to the getPurchaseOrder and the getGuestPurchaseOrder method response. These field provide information about the coupons and/or promotions that were applied to the order.
| New Field | Description |
|---|---|
| lineItems.baseUnitPrice | The cost of a single item in this line item. |
| pricingSummary.additionalSavings | The total amount of the coupon discounts in the purchase order. |
| lineItems.promotions.discount | The discount amount on the applied promotional offer. |
| lineItems.promotions.discountPercentage | Note: The purchase order methods do not support this field. |
| lineItems.promotions.message | The text for the promotion title, which describes the promotion. For example, Buy 1 Get 1. |
| lineItems.promotions.promotionCode | An identifier of the promotion that was generated by the system when the promotion was created. |
| lineItems.promotions.promotionType | Indicates the kind of promotion. Some examples are: SellerDiscountedPromotionalOffer and COUPON. |
Announcement
Documentation on Integrating with PayPal's Smart Button
The Order API documentation now has details on how to integrate the Order API with PayPal's Smart Button. The PayPal Smart Button eBay guest payment flow is supported only for eBay guest checkouts. There are two flows:
- The web flow requires eBay partners to integrate with PayPal's client-side
REST
checkout.jsJavaScript. For more details, see PayPal Smart Button Web Integration. - The mobile flow for android and iOS requires eBay partners to integrate with PayPal's Checkout Native SDK. For more details, see PayPal Smart Button Mobile Integration.
These flows let eBay guests pay for items with or without having a PayPal account. They can sign into PayPal and use any payment method associated with their PayPal Account, or without a PayPal account they can pay using a credit card or a direct debit all without leaving your app or site. Using these flows you do not need to be PCI compliant.
v1_beta.16.0
In this release, the error message for 15023, 15024, and 17000 was improved and the following error were added.
|
Methods |
Error ID |
Description |
|---|---|---|
| initiateCheckoutSession | 15024 | There is a problem with the buyer's payment method. Please check or provide another payment method for this order. |
| applyGuestCoupon, removeGuestCoupon, updateGuestPaymentInfo, updateGuestQuantity, updateGuestShippingAddress, updateGuestShippingOption | 15032 | After using the 'initiateGuestPayment' call, you cannot make changes to the cart. If you need to change the cart, you must start over using the 'initiateGuestCheckoutSession' call. |
v1_beta.15.0
In this release, the following changes have been made:
- Added documentation to support integrating with PayPal's Smart Button on mobile. See PayPal Smart Button eBay guest payment flow for details.
- Increased the number of line items per checkout session. This values was increased from 4 to 10. Now any session can have up to 10 line items (one item ID per line).
v1_beta.14.0
In this release, a new error message and support for additional marketplaces were added.
Additional marketplace support
The Order API now supports the following marketplaces for the guest, member, and PayPal Smart Button payment flows. For details, see Buy API Support by Marketplace.
- EBAY_AU - Australia (ebay.com.au)
- EBAY_ES - Spain (ebay.es)
- EBAY_FR - France (ebay.fr)
- EBAY_IT - Italy (ebay.it)
The Buy APIs Requirements have been updated with the requirements for these marketplaces.
Added a new error message
The following error message has been added to the initiate checkout session methods. This error is return when one of the items cannot be purchased because the seller is not processing orders. The item ID is returned in the message. If there are other items that can be purchased, you need to create a new checkout session containing these items.
|
Error ID |
Error Message |
|---|---|
| 15045 | The item cannot be purchased because the seller is away and is not processing orders. If you are trying to purchase more than one item, you need to create a new checkout session to purchase the other items. |