Order API

Note: The current version of the Order API (v2) currently only supports the guest payment flow for eBay managed payments. If you need more information for handling member workflows, see Order API (V1).

The Order API supports both eBay guest and eBay member (signed in) checkouts. A guest checkout is where someone does not sign into the eBay site and you must collect or have all the information needed in order to purchase and ship the item. An eBay member checkout is where the buyer is logged into eBay and you can use the information from their account to purchase and ship the item. You can collect from the eBay member a different shipping address for the item than the one in their account information. For example when the buyers want to purchase something but send it to someone else.

The basic differences between these checkouts are described in the following table.

eBay Guest Checkout

eBay Member (signed in) Checkout

  • You will use an oauth application token. For information about this token, see OAuth access tokens.

  • The buyer pays for items using a credit card, direct debit, or other supported payment method through the Checkout with eBay widget. Because all guest payments are handled by the Checkout with eBay widget, Payment Card Industry Data Security Standards (PCI DSS) do not apply to the Guest Checkout flow.
  • You will use an oauth user token. For information about this token, see OAuth access tokens.

  • The buyer uses a credit card saved to their eBay member account to pay for their order. If the buyer does not have a stored credit card, you will need to supply the payment information. To do this, your application must comply with Payment Card Industry Data Security Standards (PCI DSS) to ensure proper handling of sensitive credit card data.

 

Order API methods overview

The Order API has checkout_session, purchase_order, guest_checkout_session, and guest_purchase_order resources to support cart checkouts for eBay members and eBay guests. The checkout functionality is described below:

  • Create a checkout session
    You use initiateCheckoutSession method to create a checkout session. This is the first step in all checkout flows.
  • Update quantity and shipping method
    You can change the quantity and/or the shipping method of a specific line item. This lets your buyer adjust the quantity and gives them the ability to have a unique shipping method for each line item. For example, they might pay more to have one item expedited but have the other items shipped in a less expensive way.
  • Update/add payment information
    • For member checkouts, you can add the payment information at this point or after the session has started. This allows the buyer to change their payment information. The payment information isn't required when you initially create the checkout session.
    • For guest user checkouts, all payment information is entered through the Checkout with eBay widget flow.
  • Update the shipping address
    There can be only one shipping address for a checkout session. But it does not have to be the buyer's address. This gives the buyer the ability to purchase items and have them sent to someone else.
  • Apply and remove a coupon
    You can use the applyCoupon methods to add a coupon to the purchase order. The coupon discount with be applied to all the eligible items in the order. You can also remove a coupon from the purchase order.
  • Retrieve the checkout session details
    You can retrieve all the checkout session details. This gives you the ability to review the order with the buyer and get their approval before creating the purchase order and submitting it for payment.
  • Submit the purchase order for payment
    You use the placeOrder methods to complete the checkout flow. The method creates the purchase order, initiates the payment process, and terminates the specified checkout session. The payment process can sometimes take a few minutes. The response from these methods often show that the payment for the purchase order is "PENDING".
  • Check payment status
    You can retrieve the details of a purchase order to check the value of the purchaseOrderPaymentStatus field to determine if the purchase order has been paid for. If it has been paid for, this field will return PAID.
  • Retrieve purchase order details
    You can retrieve the details, including the shipment tracking information, for a specific purchase order. This enables you to store a record of this transaction. The details also include the fields that enable you to use the Post Order API to handle returns and an cancellations, for eBay member checkouts. For more information, see Handling post order tasks.

Payment flows overview

The Order API supports the following flows:

Order API eBay member payment flow

An eBay member can use this flow to pay for items using a payment method saved to their account, which is passed in using the updatePaymentInfo method.

Note: You must use V1 endpoints for this flow. See Order API for details.

The following describes the Order API payment flow.

  1. Pass in the item ID, quantity, the Buyer's contact information, and the shipping address.

    If the eBay member wants to use a credit card, pass in the buyer's credit card information.

    This method returns the checkout session ID (checkoutSessionId).

     

  2. Make adjustments to the order

    Use the update methods to change the quantity of an item, the shipping option of a line item, or the shipping address of the order.

    This method returns the order details.

     

  3. Review the order

    Use the getCheckoutSession method to pass in the checkout session ID (checkoutSessionId).


    This method returns the order details.

     

  4. Place the order

    To complete the transaction and retrieve the order details, use the placeOrder method and the checkout session ID (checkoutSessionId).

    This method returns the purchase order ID and payment status.

Order API Payment Flow

Checkout with eBay Button flow

The Checkout with eBay flow lets eBay guests to use the Checkout with eBay button to pay for items with a credit card, direct debit, or other supported payment method, without leaving your app or site. This flow does not require PCI DSS compliance.

The Checkout with eBay payment flow is supported only for guest checkouts.

The Checkout with eBay button process is a web flow that requires eBay partners to integrate eBay's client-side REST checkout.js JavaScript into their site. For more details on integrating the JavaScript, see Integrating the Checkout with eBay button.

The following walks you through the process of having a Buyer (eBay guest) pay using the Checkout with eBay button with the Order API.

  1. Start the checkout session

    Pass in the item ID, quantity, the Buyer's contact information, and the shipping address using the initiateGuestCheckoutSession method.

    This method returns the checkout session ID (checkoutSessionId) and a security token.

    Note: For attribution, you must pass the EPN campaign and reference ID in the EBAY-C-ENDUSERCTX header in the initiateCheckoutSession call. For more information about headers and accepted values, refer to Request components.

  2. Make adjustments, add/remove coupons, and review the order

    Use the updateGuestQuantity, updateGuestShippingAddress, updateGuestShippingOption, and getGuestCheckoutSession methods to change the order and let the buyer review and approve the order. You can also add a coupon (applyGuestCoupon) and remove a coupon (removeGuestCoupon).

    These methods return the order details.

  3. Use the Checkout with eBay button to show the eBay Checkout window.

  4. The security token, sessionId, paymentActions, onSuccess, affiliate details, onChange, onError values and any additonal data are passed to eBay Checkout.

  5. The Buyer uses the Checkout with eBay button to complete payment.

  6. The Checkout with eBay button passes values forpurchaseOrderId, purchaseStatus, checkoutSessionId .

Integrating the Checkout with eBay button

The Checkout with eBay widget allows eBay guests to pay for items without leaving your site. To implement the Checkout with eBay payment option, you must include the Checkout with eBay Javascript SDK to your web page.

1. Add the following code:

<body>
const script = document.createElement('script');
script.src = 'https://checkout.ebay.com/sdk/js?locale=<locale>&token=<encodedURIComponent(token)>sessionid=<sessionid>';
document.body.appendChild(script);
</body>

This adds the necessary scripts to the body of the web page. You will pass the following variables to the script:

Variable

Type

Description

locale

string

Pass this variable to identify the site content's language.
Available options:
1. en-US
2. de-DE
Default value: en-US

token

string

Used to authenticate your request. You should receive this value from the Buy API call that you initially made to create session.
The token must be encoded.

Occurrence: Required

sessionid

string

Used to authenticate your request. You should receive this value from the Buy API call that you initially made to create session.

Occurrence: Required

2. Add/Render the Checkout with eBay button to your web page. After you have added the Checkout with eBay Javascript SDK to your web page, the next step is to initialize JavaScript function that loads the Checkout with eBay button.

<body>
	<div id='checkout-with-ebay-container'></div>

	new window.ebaypay.Button({
	    token: <encodedURIComponent(token)>,
	    sessionId: <sessionid>,
	    paymentActions: {
	        onSuccess: (data) => {
	            // your code goes here
	        },
	        onError: (error) => {
	        	// your code goes here
	        }
	        onCancel: (data) => {
	        	// your code goes here
	        }
	    }
	}).render('#checkout-with-ebay-container');
</body>

 

Variable

 

Type

Description

token

 

string

Used to authenticate your request. You should receive this value from Buy API call that you initially made to create session.

Occurrence: Required

sessionid

 

string

Used to authenticate your request. You should receive this value from Buy API call that you initially made to create session.

Occurrence: Required

paymentActions

object

Object variable that contains callbacks upon success (onSuccess), cancellation (onCancel), and failure (onError).

paymentActions.onSuccess

JavaScript object

A JavaScript object containing two keys, purchaseOrderId and purchaseStatus. The callback options will pass the data back to you for use when an operation is successful:

purchaseOrderId:

Type: string

Value: purchaseOrderId for this order, created through the purchase order method.

purchaseStatus:

Type: string

Value: one of "PAID" or "PENDING"

Example:

{
"purchaseOrderId": "1********7",
"purchaseStatus": "PAID"
}

paymentActions.onCancel

JavaScript object

A JavaScript object containing one key, sessionid.

The callback options will pass the data back to you for use when an operation is cancelled (e.g., when the user closes the mini-browser or something abrupt happens to close the mini-browser).

sessionid:

Type: string

Value: sessionId created through the checkout session method.

Example:

{
"sessionid": "1********7"
}

 

paymentActions.onError

JavaScript exception

The callback options will pass an exception back to you for use when an operation is cancelled (e.g., when something abrupt happens while loading the mini-browser or due to a Javascript exception).

This callback options will pass the error object back to you to perform on error operations.

error:

Type: A Javascript exception.

Handling post order tasks

This section describes how post order (after sales) transactions, such as returns, disputes, cancellations, etc. are handled for eBay member and guest checkouts.

For eBay member checkouts

For eBay member checkouts, you can use the Post Order API to complete returns or cancellations. The Order API returns the legacyItemId, legacyTransactionId, and the legacyOrderId information. This information can be used with the Post Order API to create a return request or submit a cancellation request. See Using the Post Order API for more information.

For post order tasks other than a return or cancellation, the shopper must log into their eBay account. The post order transaction is handled by the seller on the eBay site.

For eBay guest checkouts

For guest checkouts, all post order transactions are handled on the eBay site. When a shopper purchases items on eBay without signing into eBay, eBay sends the shopper an order confirmation email for each seller. This email contains a View order details link. To initiate a post order transaction, the buyer clicks on the link in the email, follows the instructions, and then signs into eBay as a guest using their email address. From there they can contact the seller to report the issue.

 

Using the Post Order API

This section describes how you use the legacyReference fields returned by the Order API to create return requests and submit cancellation requests using the Post Order API. This section describes the following:

Understanding the legacyReference fields

When you place an order, the checkout session is ended and a purchase order is created. So for any order there is only one checkoutSessionId and one purchaseOrderId. When the purchase order has more than one line item:

  • Each item has a unique lineItemID, itemId, and legacyItemId
  • Each seller has a unique legacyOrderId
  • All the items have the same purchaseOrderId and legacyTransactionId

The following shows a portion of a purchase order response that has two items from different sellers.

{
 "purchaseOrderId": "5********0",
 "purchaseOrderCreationDate": "2016-01-06T19:49:38.000Z",
 "lineItems": [
   {
     "lineItemId": "6********0",
     "itemId": "v1|1********4|0",
     "title": "Lego Marvel Super Heroes",
     "image": {
       "imageUrl": "http://pics.ebaystatic.com..."
     },
     "seller": {
       "username": "m***R"
     },
     "quantity": 1,
     "netPrice": {
       "value": "18.99",
       "currency": "USD"
     },
     "lineItemPaymentStatus": "PAID",
     "lineItemStatus": "PENDING",
     "shippingDetail": {
       "shippingServiceCode": "USPS First Class Package",
       "shippingCarrierCode": "USPS",
       "minEstimatedDeliveryDate": "2016-01-09T08:00:00.000Z",
       "maxEstimatedDeliveryDate": "2016-01-13T08:00:00.000Z"
     },
     "legacyReference": {
       "legacyTransactionId": "9********9",
       "legacyItemId": "1********4",
       "legacyOrderId": "1********4-9********9!5********0"
     }
   }


   

   {
     "lineItemId": "6********0",
     "itemId": "v1|3********5|0",
     "title": "LEGO Marvel Heroes Doctor Strange",
     "image": {
       "imageUrl": "http://pics.ebaystatic.com..."
     },
     "seller": {
       "username": "t***s"
     },
     "quantity": 1,
     "netPrice": {
       "value": "24.99",
       "currency": "USD"
     },
     "lineItemPaymentStatus": "PAID",
     "lineItemStatus": "PENDING",
     "shippingDetail": {
       "shippingServiceCode": "USPS First Class Package",
       "shippingCarrierCode": "USPS",
       "minEstimatedDeliveryDate": "2016-01-09T08:00:00.000Z",
       "maxEstimatedDeliveryDate": "2016-01-13T08:00:00.000Z"
     },
     "legacyReference": {
       "legacyTransactionId": "9********",
       "legacyItemId": "3********5",
       "legacyOrderId": "3********5-9********9!5********0"
     }
   } ... ]

Note: The legacyReference fields are returned for both guest and member checkouts. But using the values of these field with the Post Order API is supported only for eBay member checkouts.

Creating a return request using the Post Order API

The lineItems.legacyReference.legacyItemId and lineItemslegacyReference.legacyTransactionId fields returned by the Order API getPurchaseOrder method are used in the Post Order API Create Return Request method to initiate a return. Once the return process is started, you can use the Post Order API to perform all other return tasks required to complete the return process.

The table below, lists the fields required by the Post Order API Create Return Request method and the corresponding fields returned by the getPurchaseOrder method.

Post Order API Field

Order API Field

Value Returned by
Order API

returnRequest.itemId lineItems.legacyReference.legacyItemId

3********4

returnRequest.transactionId lineItems.legacyReference.legacyTransactionId

8********4


The following shows the Order API response and the Post Order API Create Return Request method using the values of the legacyTransactionId and legacyOrderId fields.

Order API
getPurchaseOrder Method Response
Post Order API
Create Return Request

  "legacyReference" :
    {
      "legacyItemId" : "3*********4",
      "legacyTransactionId" : "8********",
      "legacyOrderId" : "3********4-8********4!1********1"
    },
    ... 
"purchaseOrderPaymentStatus": "PENDING",
... 	
POST https://api.ebay.com/post-order/v2/return      
{
  "returnRequest":
  {
    "itemId": "3********4",
    "transactionId": "8********4"
  }
}

Submitting a cancellation request using the Post Order API

The lineItems.legacyReference.legacyOrderId field is returned by the Order API getPurchaseOrder method and is used in the Post Order API Submit Cancellation Request method to initiate a cancellation. Once the cancellation process is started, you can use the Post Order API to perform all other tasks required to complete a cancellation.

The table below, lists the field required by the Post Order API Submit Cancellation Request method and the corresponding field returned by the getPurchaseOrder method.

Post Order API Field

Order API Field

Value Returned by Order API

legacyOrderId    lineItems.legacyReference.legacyOrderId3********4-8********!1********1
buyerPaid

This is a Post Order boolean field.
lineItems.purchaseOrderPaymentStatusPENDING
cancelReason
This is a Post Order API enum value.

 

 


The following shows the Order API response and the Post Order API Submit Cancellation Request method using the values of the legacyOrderId and purchaseOrderPaymentStatus fields.

Order API
getPurchaseOrder Method Response
Post Order API
Create Return Request

   "legacyReference" :
     {
       "legacyItemId" : "3********4",
       "legacyTransactionId" : "8********4",
       "legacyOrderId" : "3********4-8********4!1********1"    
     },
     ... 
"purchaseOrderPaymentStatus": "PENDING",
... 
 POST https://api.ebay.com/post-order/v2/cancellation     
{
  "legacyOrderId": "3********4-8********4!1********1",     
  "buyerPaid": "false",
  "cancelReason":"ORDER_MISTAKE"
}