Order API

The Order API supports both eBay guest and eBay member 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.

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

Order API methods overview

The Order API has checkout_session, purchase_order, guest_checkout_session, and guest_purchase_order resources to support checkouts for eBay members and eBay guests.

The checkout functionality is described below:

• Create a checkout session

  You use the initiateGuestCheckoutSession or 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 using the updateGuestQuantity, and updateGuestShippingOption or updateQuantity, andupdateShippingOption methods. 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.

• Apply and remove a coupon

  You can use the applyGuestCoupon or applyCoupon method 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 with the removeGuestCoupon or removeCoupon method.

  Note:(Limited Release) You must be white listed to use these methods.

• Update the shipping address

  You can change the shipping address using the updateShippingAddress and updateGuestShippingAddress methods. 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.

• Update Addon Services Status

  For member checkouts, changes the selection of add-on services for the checkout session. This is not available for guest checkout.

• Update/add payment information
  • For guest checkouts, all payment information is entered through the Checkout with eBay widget flow. For details, see Checkout with eBay Button flow.
  • For member checkouts, you can add/change the payment information any time after the session has started using updatePaymentInfo. This allows the buyer to change their payment information. The payment information isn't required when you initially create the checkout session.

• Retrieve the checkout session details

  You can retrieve all the checkout session details using getGuestCheckoutSession and getCheckoutSesson. 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

  • For member checkouts, you use the placeOrder method 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 often shows that the payment for the purchase order is "PENDING".
  • Guest checkouts do not have a placeOrder method. This is handled by the Checkout with eBay widget. For details, see Checkout with eBay Button flow.

• Check payment status

  You can retrieve the details of a purchase order using getGuestPurchaseOrder and getPurchaseOrder. The value returned in the purchaseOrderPaymentStatus field shows whether 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 using getGuestPurchaseOrder and getPurchaseOrder. This enables you to store a record of this transaction.

  For eBay member checkout, the details also include the fields that enable you to use the Post Order API to handle returns and an cancellations. For more information, see Handling post order tasks.

Order API error details

This section provides more information on troubleshooting errors that may occur with the Order API.

Error code 15002 for invalid itemId

There are several possibilities why an item is not be available for purchase, and the 15002 error code will be triggered.

• The item is out of stock. The buyer will need to track that item to see if seller adds more quantity.
• The listing has ended. The buyer will need to find a similar item in another listing.
• The buyer is an active bidder in an auction, but the auction has not ended yet. The buyer will need to track the auction until it ends, and make higher bids as necessary. The auction item will only be purchasable if the buyer is the winner of the auction.
• The buyer is not the winner of the auction. The buyer will need to find a similar item in another listing.

Payment flows overview

The Order API supports the following flows:

• The Order API eBay member payment flow. This flow is for eBay members using the Order API.
• The Checkout with eBay Button flow. This flow is for eBay guests using the Checkout with eBay button. This flow does not require the Partner to be CPI complaint.

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.

The following describes the Order API payment flow.

1. Start the checkout session

   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.

   These methods return 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.

Checkout with eBay Button flow

The Checkout with eBay flow is only for eBay guests. You 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 Payment Card Industry Data Security Standards (PCI DSS) compliance.

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

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

2. Make adjustments and review 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.

   These methods return the order details.

3. Review the order

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

   This method returns the order details.

4. Complete the order using the Checkout with eBay button.

   Use the Checkout with eBay button to let the buyer enter payment information and purchase the item.

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

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

• The Checkout with eBay button passes the values for purchaseOrderId, 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:

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>

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

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

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
• Creating a return request using the Post Order API
• Submitting a cancellation request using the Post Order API

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"
     }
   } ... ]

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.

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.

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

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.

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