order APIv1_beta.11.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.11.0

2018-07-12

Added proxy_guest_checkout_session resource

v1_beta.10.0

2018-07-02

Added the initiateGuestPayment call

v1_beta.9.0

2018-04-18

Added new error messages

v1_beta.8.0

2017-10-16

Changed call 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 calls

v1_beta.7.0

2017-06-07

SSL certificate change

Removed response fields

Added error message 15028 to the initiateCheckoutSession calls

v1_beta.6.0

2017-04-20

Response field changes.

Buying Integration changes.

 

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 call in this resource. For details about the VSP payment flow see Vault Service Provider (VSP) Checkout payment flow for eBay guests .

HTTP Method

Call

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 call. After integration with PayPal's checkout.js JavaScript on the client side, this call 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 call 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.

Call

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 calls 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 call names

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

Note: The endpoints of these calls did not change.

The table below shows the old and new call names.

Old Call Name

New Call 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 calls 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 call. This call 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 call. This call 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 call. This call initiates the item order cancellation process.

 

Added new error message for checkout calls

All calls 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 call 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 calls 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 calls 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 calls. 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 calls in this API calls 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 call responses from the prior release (Previous) with this release (New). The bolded text in the table shows the fields that have been renamed.

Checkout calls response changes

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

Previous

New

Change

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

 

Guest getPurchaseOrder call response changes

 

Previous

New

Change

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


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

 

Buying Integration Guide update

The following changes were made to the Buying Integration Guide:

  • The integration has been split into three chapters; Overview, Requirements, and Application Example
  • Added a section to the Overview chapter.