order APIv1_beta.23.0

Order API Release Notes

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



Added support for Australian 'Good and Services' tax.



For the shipping address the postalCode is now optional when shipping to HK

Added warning messages



Removed duplicate coupon error messages



Changes to error messages



Added error messages

Added a unique line item order ID field



Added import charges and shipment tracking information fields

Added new requirements for Global Shipping Program

Added and changed error messages

Changed marketing consent requirements



Added support for the EBAY_CA marketplace



Added fields to support returning coupon information by getPurchaseOrder



Improved existing error messages and added new errors




Added documentation to support for integrating with PayPal's Smart Button on mobile.

Increased the number of line items



Added support for additional marketplaces

Added a new error message



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



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


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.



In this release, the following error messages were removed from the add coupon methods. These errors were duplicates of other error messages.


Error ID


Removed error

Duplicate of 16004
The coupon has not been activated. The coupon was ignored and no discount was applied to this order.

Removed error

Duplicate of 16012

The coupon is not valid for the {fieldName}. The coupon was ignored and no discount was applied to this order.


In this release, one error message was added and the error message of one error was changed for clarity.


Error ID



New error

15049 There is some issue with this payment. Contact eBay developer support for assistance.



Improved message


New message:
The payment cannot be processed due to a payment processor issue, such as invalid incentive, funding or financing issue, etc.

Old message:
The payment cannot be processed due to insufficient funds or other issues with funding source. To complete this order, use the appropriate initiate checkout session call to create a new session and provide a new payment method.






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



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



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.




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
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
shippingFulfillments.shipmentTrackingEvents.eventType A normalized string for shipment tracking event.
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



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


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": [
  • marketingTerms.marketingTermsAccepted
    "marketingTermsAccepted": false|true,
  • marketingTerms.marketingTypes
    "marketingTypes": [



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


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.


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:

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.


In this release, the error message for 15023, 15024, and 17000 was improved and the following error were added.


Error ID


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.



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).


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.