order APIv1_beta.17.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

v1_beta.18.0

2019-04-15

Added support for the EBAY_CA marketplace

v1_beta.17.0

2019-04-08

Added fields to support returning coupon information by getPurchaseOrder

v1_beta.16.0

2019-03-04

Improved existing error messages and added new errors.

v1_beta.15.0

2019-02-19

2019-01-28

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

Increased the number of line items

v1_beta.14.0

2019-01-23

Added support for additional marketplaces

Added a new error message

v1_beta.13.0

2018-11-08

Added fields and error messages to support obtaining marketing consent from the buyer

Added new and changed existing errors and warnings

v1_beta.12.0

2018-09-26

Added methods and response fields to support coupons

v1_beta.11.0

2018-07-12

Added proxy_guest_checkout_session resource

v1_beta.10.0

2018-07-02

Added the initiateGuestPayment method

v1_beta.9.0

2018-04-18

Added new error messages

 

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:

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.

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

 

v1_beta.13.0

Added support for obtaining marketing consent from the buyer and added new error messages and change some existing error/warning messages.

Added support for obtaining buyer's marketing consent

When buyer's are purchasing an item, you must give them the option to opt-in or opt-out-of receiving marketing messages from eBay. There are three guest checkout flows; Order API guest flow, the PayPal Smart Button flow, and the vault provider flow. For all three guest checkout flows, you must do the following.

Below the "Buy" button you must display a checkbox and the following legal consent message, which is returned in the marketingMessages.legalMessage field.

I agree to receive marketing offers, promotions, and surveys from eBay through email.

Note: There are different requirements for the US and other eBay marketplaces. For items purchased on the:

  • EBAY_US marketplace
    • The legal message and checkbox are optional until Q1 of 2019. After that, they will be required.
    • When the checkbox appears it is to be enabled (checked).
  • All other marketplaces
    • The legal message and checkbox are required.
    • When the checkbox appears it is to be disabled (un-checked).

To support obtaining marketing consent from buyers, the following fields and error/warning messages have been added.

Added request fields

The table below lists the new request fields and the methods to which they were added.

Method

Field

 

Description

placeGuestOrder
placeProxyGuestOrder
marketingTerms

Optional

The container for the marketing channels and types of messages the buyer can choose to receive and the field to indicate whether the buyer wants to receive marketing materials from eBay.
marketingTerms.marketingChannels

Optional

An enumeration value representing the available marketing channels, such as EMAIL. Currently, the only marketing channel available is EMAIL.
marketingTerms.marketingTermsAccepted

Optional

A boolean that indicates whether the buyer wants to receive marketing messages.
Note: This is an optional field. If it is left null, the defaults are:
  • US marketplace: true
  • Any other marketplace: false
marketingTerms.marketingTypes

Optional

An enumeration value representing the available types of marketing messages. Currently, if the buyer opts-in, they will receive all the available marketing types (OFFER, PROMOTION, and SURVEY).

Added response fields

The table below lists the new response fields and the methods to which they were added.

Method

Field

Description

getGuestCheckoutSession
initiateGuestCheckoutSession
initiateGuestPayment
updateGuestPaymentInfo
updateGuestQuantity
updateGuestShippingAddress
updateGuestShippingOption
getProxyGyestCheckoutSession
initiateProxyGyestCheckoutSession
initiateProxyGyestPayment
updateProxyGyestPaymentInfo
updateProxyGyestQuantity
updateProxyGyestShippingAddress
updateProxyGyestShippingOption
marketingMessages A list of the marketing channels and types of messages the buyer can choose to receive.
marketingMessages.legalMessage An enumeration value representing the marketing channels.
marketingMessages.marketingChannels A boolean the buyer sets to indicate whether they want to receive marketing messages.
marketingMessages.marketingTypes An enumeration value representing the type of marketing message.

Added new and changed existing errors and warnings

There were also error and warnings added and some error ID changes to existing error. The following table captures these error and warning changes.

Method

Error change

applyCoupon
applyGuestCoupon
applyProxyGuestCoupon
Replaced
"category": "REQUEST",
"description": "The coupon provided could not be applied. You may proceed with this session or provide another coupon.",
"domain": "API_ORDER",
"errorId": 15008


With
"category": "REQUEST",
"description": "The coupon provided could not be applied. You may proceed with this session or provide another coupon.",
"domain": "API_ORDER",
"errorId": 16024
removeCoupon
removeGuestCoupon
removeProxyGuestCoupon
Replaced
"category": "REQUEST",
"description": "The coupon was not applied to this cart.",
"domain": "API_ORDER",
"errorId": 16034


With
"category": "REQUEST",
"description": "The coupon was not applied to this cart.",
"domain": "API_ORDER",
"errorId": 16025
initiateCheckoutSession
initiateGuestCheckoutSession
initiateProxyGuestCheckoutSession
Added error
"category": "BUSINESS",
"description": "At least one of the items in the cart cannot be purchased using this API. The purchase can be done on ebay.com.",
"domain": "API_ORDER",
"errorId": 15044


Added warning
"category": "BUSINESS",
"description": "The Item {itemId} cannot be purchased using this API and has been removed from the cart. The purchase can be done on ebay.com.",
"domain": "API_ORDER",
"errorId": 15043
placeOrder
placeGuestOrder
placeProxyGuestOrder
Added error
"category": "BUSINESS",
"description": "The payment cannot be processed at this time.",
"domain": "API_ORDER",
"errorId": 17000
All POST methods except placeOrder. Changed Behavior - If the address is not valid, this used to return a warning. With this release, it will now return an error and the call will fail.
"category": "REQUEST",
"description": "Invalid field: {fieldName}. The indicated field contains an invalid value. Correct the value and resubmit the call.",
"domain": "API_ORDER",
"errorId": 15002,
"inputRefIdsSupported": true,
"parametersDescription": "fieldName"

Important! This is a backward incompatible change.

 

v1_beta.12.0

(Limited Release) You must be whitelisted to use these new methods.

To support the use of coupons the following new methods and response fields have been added.

New methods

These new methods let buyers apply a coupon to their order. The coupon is applied at the cart level and applies discounts to all the eligible items in the order. You can apply only one coupon per purchase order.

Note: The PayPal Smart Button guest payment flow, does not support the use of coupons.

HTTP Method

Method

Description

POST applyCoupon
applyGuestCoupon
applyProxyGuestCoupon
Adds a coupon to the checkout session and applies it to all the eligible items in the order.
POST removeCoupon
removeGuestCoupon
removeProxyGuestCoupon
Removes the specified coupon from the checkout session.

New response fields

The following fields were added to the responses of all the Order API methods.

New Response Fields

Description

appliedCoupons.redemptionCode The coupon redemption code.
pricingSummary.additionalSavings The total amount of the coupon discount in the purchase order.
promotions.promotionType New enumeration value COUPON was added.
promotions.discountPercentage The discount percentage of the applied promotional offer.

 

v1_beta.11.0

Added proxy_guest_checkout_session resource to enable checkout using a VSP (vault service provider), such as Braintree. The following table lists the method in this resource. For details about the VSP payment flow see Vault service eBay guest payment flow .

HTTP Method

Methods

Description

POST initiateProxyGuestCheckoutSession Creates an eBay proxy guest checkout session. You can pass in the item IDs, quantity, the Buyer's contact information, and the shipping address,
POST updateProxyGuestPaymentInfo Adds and updates the payment method in an eBay proxy guest session. Note: This endpoint is invoked by the VSP (vault service provider) on behalf of the partner.
POST updateProxyGuestQuantity Updates the quantity of the specified line item in an eBay proxy guest checkout.
POST updateProxyGuestShippingAddress Updates the quantity of the specified line item in an eBay proxy guest checkout.
POST updateProxyGuestShippingOption Updates the shipping address for the specified line item in an eBay proxy guest checkout session.
GET getProxyGuestCheckoutSession Retrieves the specified eBay proxy guest checkout session details.
POST placeProxyGuestOrder Pays for the items in the specified eBay proxy guest checkout session.

 

v1_beta.10.0

Added the initiateGuestPayment method. After integration with PayPal's checkout.js JavaScript on the client side, this method enables eBay guests to pay for their items with or without having a PayPal account without leaving your App or site. To pay for items, buyers can either:

  • Sign into their PayPal account and use any payment method associated with that account .
  • Without a PayPal account, they can pay using a credit card or a direct debit.
    For details about this flow, see PayPal Checkout payment flow. Note: This method is used only in the PayPal Checkout payment flow.

v1_beta.9.0

Added new error messages

The following error messages were added to the Order API.

Method

Error ID

Error Description

initiateCheckoutSession and initiateGuestCheckoutSession 15031 The item is not purchasable because the buyer has been blocked by the seller.
updateShippingAddress and updateGuestShippingAddress 15026 The item is not shippable to the specified shipping address.