order APIv1_beta.12.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.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.8.0

2017-10-16

Changed method names in the guest_checkout_session and guest_purchase_order resources

Added fields to support using the Post Order API for returns and cancellations (eBay member checkouts only)

Added a new error message for checkout methods

v1_beta.7.0

2017-06-07

SSL certificate change

Removed response fields

Added error message 15028 to the initiateCheckoutSession methods

v1_beta.6.0

2017-04-20

Response field changes.

Buying Integration changes.

 

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 guest checkout 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 provider (VSP) guest checkout 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.

 

Announcements - February 2018

TLS1.2 exclusive support

eBay will add TLS1.2 exclusive support to the following PCI Production Order API endpoint by February 28, 2018. This means after this date, you can use only TLS1.2 on Production for this endpoint.

https://apix.ebay.com

To support testing your transition to TLS1.2, we have enabled a TLS1.2 exclusive environment in the Sandbox environment (https://apix.sandbox.ebay.com). The sandbox environment is available to test your implementation now.

The URLs for all the Order API methods in the checkout_session and guest_checkout_session resources are:

  • Production URL: https://apix.ebay.com/buy/order/v1
  • Sandbox URL: https://apix.sandbox.ebay.com/buy/order/v1

Important! In reference to the PCI zone and assets which connect directly to this zone, eBay will no longer continue to support TLS 1.0 and 1.1 after February 28, 2018. If your application is on an older stack, it is highly recommended that you plan for this change in order to meet the February 2018 deadline. This change is part of an industry-wide initiative to improve security standards across the Web.

Please file a support ticket at http://developer.ebay.com/support/developersupport/default.aspx if you experience any issues.

 

Announcements - October 2017

Availability of OpenAPI Specification

This release of the Order API includes Beta version downloadable JSON and YAML formats of the API contract that comply with version 3.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 3.0 OpenAPI specifications: https://editor3.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 Order API 3 JSON specification (beta)

File download     Download Order API 3 YAML specification (beta)

 

Support for returns and cancellations using the Post Order API

The getPurchaseOrder and getGuestPurchaseOrder methods return the legacyItemId, legacyTransactionId, and legacyOrderId fields. The values from these fields can be used with the Post Order API to request a return or submit a cancellation. You can then use the Post Order API to complete the return or cancellation process.

 

v1_beta.8.0

The following changes were made to the Order API.

Changed method names

The name of the guest_checkout_session and guest_purchase_order resource methods have been changed by adding 'Guest' to the name. The following table shows the old and new name of each method that was changed.

Note: The endpoints of these methods did not change.

The table below shows the old and new method names.

Old Method Name

New Method Name

guest_checkout_session resource
getCheckoutSession getGuestCheckoutSession
initiateCheckoutSession initiateGuestCheckoutSession
placeOrder placeGuestOrder
updatePaymentInfo updateGuestPaymentInfo
updateQuantity updateGuestQuantity
updateShippingAddress updateGuestShippingAddress
updateShippingOption updateGuestShippingOption
guest_purchase_order resource
getPurchaseOrder getGuestPurchaseOrder

 

Added support for Post Order API

The getPurchaseOrder and getGuestPurchaseOrder methods now return the legacyItemId, legacyTransactionId, and legacyOrderId fields. The values from these fields are used with the Post Order API to request a return or request a cancellation. You can then use the Post Order API to complete the return or cancellation.

For more information about how to you use these fields in the Post Order API, see Handling post order tasks in the Buy Integration Guide.

The table below shows the new type and fields and their description.

New Field

Description

lineItems.legacyReference

The container that returns fields to support using the Post Order API for returns and cancellations.

lineItems.legacyReference.legacyItemId

The legacy ID used to identify an item. This is used by the Post Order API Create Return Request method. This method initiates the item return process.

lineItems.legacyReference.legacyTransactionId

The legacy ID of the transaction. This is used by the Post Order API Create Return Request method. This method initiates the item return process.

lineItems.legacyReference.legacyOrderId

The legacy ID of the order, which is a concatenation of the legacyItemId and legacyTransactionId. This is used by the Post Order API Submit Cancellation Request method. This method initiates the item order cancellation process.

 

Added new error message for checkout methods

All methods the affect a checkout session, must use the same X-EBAY-C-MARKETPLACE-ID value that was used when the checkout session was created. For example, lets say you used X-EBAY-C-MARKETPLACE-ID = EBAY-US to create a checkout session with the ID of 100008000651370. Any method that passes in the checkout session ID 100008000651370, must have the X-EBAY-C-MARKETPLACE-ID header set to EBAY-US.

The following error is returned if you use a different X-EBAY-C-MARKETPLACE-ID value than the one that was used when the checkout session was created.

Error ID

Error Description

15029 The <DPH id="fieldName"/> value <DPH id="fieldValue"/> is invalid for this checkout session because it is different from the <DPH id="fieldName"/> header value used to create the session. For all methods in this checkout session, you must use <DPH id="fieldName"/> <DPH id="supportedValues"/>.

v1_beta.7.0

SSL certificate change

The SSL certificate for the domain https://apix.ebay.com used by the Checkout methods was renewed on Monday June 12, 2017. The new SSL certificate implements the hashing algorithm SHA2 instead of SHA1.

If your application stored the current certificate locally (https://apix.ebay.com), you will need to replace it with the new certificate in order to ensure your application continues working correctly.

There is no action item on your side if your application is not storing the certificate locally.

Removed response fields

The following response fields were removed. These fields were renamed in the v1_beta.6.0 release.

Removed

Use Instead

lineItems.shippingDetail.shippingCarrierName lineItems.shippingDetail.shippingCarrierCode
lineItems.shippingDetail.shippingServiceName lineItems.shippingDetail.shippingServiceCode

 

Added error message

The error message 15028 was added to the initiateCheckoutSession methods. This error occurs when an item is not allowed to be purchased in the country to which it is being shipped.

v1_beta.6.0

Changes to response fields

The shippingCarrierName and shippingServiceName fields were renamed in the Order API. This affects all the methods in this API methods except, placeOrder and placeGuestOrder.

Important! These changes are backward incompatible.

The new release of the Buy API will be available in production on 4/20/2017. To give you more time to integrated with this change, the shippingCarrierName and shippingServiceName fields will be supported until 5/19/2017. After that date, they will removed from the interface.

The following tables compares the Order API method responses from the prior release (Previous) with this release (New). The bolded text in the table shows the fields that have been renamed.

Checkout methods response changes

The changes shown in the table below apply to all the Checkout methods except, placeOrder and placeGuestOrder.

Previous

New

Change

lineItems.shippingDetail.shippingCarrierName lineItems.shippingDetail.shippingCarrierCode Renamed
lineItems.shippingDetail.shippingServiceName lineItems.shippingDetail.shippingServiceCode Renamed

 

Guest getPurchaseOrder method response changes

 

Previous

New

Change

lineItems.shippingDetail.shippingCarrierName lineItems.shippingDetail.shippingCarrierCode Renamed
lineItems.shippingDetail.shippingServiceName lineItems.shippingDetail.shippingServiceCode Renamed


getPurchaseOrder method response changes

 

Previous

New

Change

lineItems.shippingDetail.shippingCarrierName lineItems.shippingDetail.shippingCarrierCode Renamed
lineItems.shippingDetail.shippingServiceName lineItems.shippingDetail.shippingServiceCode Renamed
shippingFulfillments.shippingCarrierName shippingFulfillments.shippingCarrierCode Renamed
shippingFulfillments.shippingServiceName shippingFulfillments.shippingServiceCode Renamed