The Order API supports eBay member (signed in) checkouts. 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.

When using eBay Member (signed in) Checkout:

  • You will use an oauth user token. For information about this token, see Get 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.

Order API methods overview

The Order API has checkout_sessionand purchase_order resources which support checking out for eBay members. The checkout functionality is described below:

  • Create a checkout session

    You use initiateCheckoutSession methods to create a checkout session. This is the first step in the all the 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

    The payment information isn't required when you initially create the checkout session. So you can add it after the session has started. It also gives the buyer the ability to change the payment information.
  • 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 will be applied to all eligible items in the order. You can also remove a coupon from the purchase order.

    Note: Limited Icon(Limited Release) You must be white listed to use these methods.
  • 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 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 from this method often shows that the payment for the purchase order is "PENDING".
  • Check payment status

    You can use the getPurchaseOrder method 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 as PAID.
  • Retrieve purchase order details

    You can use the getPurchaseOrder method to retrieve all details of the order, including purchase price, tax, fees, and shipping information/the shipment tracking information for a specific purchase order. This enables you to store a record of this transaction.

Payment flows overview

The Order API supports the following flows:

  • Order API v1

    This flow is for eBay members using only the Order API.

eBay member payment flow

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

The following describes the Order API member payment flow.

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.

    This method returns the order details.

  3. Review the order

    Use the getCheckoutSession method to pass in the checkout session ID (checkoutSessionId) and return the order details.

    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.

Handling post order tasks

This section describes how post order (after sales) transactions, such as returns, disputes, cancellations, etc. are handled for eBay member 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 Order API v1 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.

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 line 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. The fields with unique IDs are bolded.

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

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********4",
     "legacyOrderId" : "3********4-8********4!1********1"
   },
   ...
"purchaseOrderPaymentStatus": "PENDING",
...
POST https://api.ebay.com/post-order/v2/return
{
  "returnRequest":
  {
    "itemId": "330005959274",
    "transactionId": "8905715014"
  }
}

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.legacyOrderId 3********4-8********4!1********1

buyerPaid

This is a Post Order boolean field.
lineItems.purchaseOrderPaymentStatus PENDING

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