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.

Important! eBay guest checkout is no longer supported by the v1 version of the Order API. eBay guest checkout through Order API v1 was dependent on the PayPal checkout flow, and now 100 percent of eBay transactions exclusively go through eBay's checkout flow.

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

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. 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 guest_checkout_session, proxy_guest_checkout_session, checkout_session, guest_purchase_order, and purchase_order resources, which support checking out for eBay members and eBay guest. The checkout functionality is described below:

Important! eBay guest checkout is no longer supported by the v1 version of the Order API. eBay guest checkout through Order API v1 was dependent on the PayPal checkout flow, and now 100 percent of eBay transactions exclusively go through eBay's checkout flow.

  • 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 whitelisted 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:

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.

PayPal Smart Button eBay guest payment flow

Important! This flow is no longer supported. 100 percent of eBay transactions now exclusively go through eBay's checkout flow.

The following walks you through the process of having a Buyer (eBay guest) pay using PayPal Smart Button using the Order API. In the flow diagram below, processes between the eBay partner and eBay are in blue and processes between the eBay partner and PayPal are in gray.

PayPal Smart Button Payment Flow
  1. Start the checkout session

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

    Important! Do not pass in credit card information. If you do, you cannot use the PayPal Smart Button payment flow.

    This method returns the checkout session ID (checkoutSessionId).

  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. Specify payment as PayPal Checkout

    Use the initiateGuestPayment method to pass in the checkout session ID (checkoutSessionId) and set the request payload fields as shown below to indicate this is a PayPal Smart Button payment.

    paymentMethodBrandType = PAYPAL_CHECKOUT

    paymentMethodType = WALLET

    This method returns the order details and the PayPal cart ID in the externalReferenceId field.

    Important! Once you use the initiateGuestPayment method, you cannot change anything in the PayPal cart. If you need to change the PayPal cart, you must start over using the initiateGuestCheckoutSession method.

  4. Use PayPal Smart Button to pay for the order

    Note: Your app must be integrated with either PayPal checkout.js or the Checkout Native SDK. This step is between only the eBay partner and PayPal.

    Use the checkout.js JavaScript or the PayPal's Checkout Native SDK and the PayPal cart ID (externalReferenceId) to enable payment functionality on your site or app. The checkout.js will render the Smart Button UI and it's functionality for you, but if you are using the SDK you must create the PayPal checkout button per PayPal branding guidelines and add a listener to it.

    The Buyer clicks on the PayPal Smart button then either logs into PayPal or pays with a credit card or direct debit. If this is successful, PayPal returns control back to you and returns the PayPal cart ID and the payer ID in a URL.

  5. Update the checkout session with the payer ID

    Use the updateGuestPaymentInfo method to pass in the checkout session ID (checkoutSessionId) and set the request payload field as shown to update the checkout session with the payer ID.

    wallet.paymentToken = payerID

    This step returns the checkout session ID (checkoutSessionId) and the order details.

  6. Place the order

    To complete the transaction and retrieve the order details, pass in the checkout session ID (checkoutSessionId) using the placeGuestOrder method.

Vault service eBay guest payment flow

Important! This flow is no longer supported. 100 percent of eBay transactions now exclusively go through eBay's checkout flow.

The following walks you through the process of having a Buyer (eBay guest) pay using a VSP and the Order API. In the flow diagram below, processes between the eBay partner and eBay are in blue and processes between the eBay partner and the VSP are in gray.

Vault Service Provider Payment Flow
  1. Start the checkout session

    Use the initiateProxyGuestCheckoutSession method to pass in the item ID, quantity, the Buyer's contact information, the shipping address, and the required headers.

    Required Headers: Authorization and X-EBAY-C-MARKETPLACE-ID

    Note: The payment information is added to the checkout session using the updateProxyGuestPaymentInfo method.

    This method returns the checkout session ID (checkoutSessionId) and the purchase order details.

  2. Make adjustments to the order

    Note: The following changes can be made in any order.

    • Add or change the credit card information

      Pass in the checkout session ID (checkoutSessionId), the buyer's credit card information, and the following headers using the updateProxyGuestPaymentInfo method.

      Required Headers: Authorization and X-EBAY-C-MARKETPLACE-ID

      The method goes to the VSP. The VSP generates the X-EBAY-C-SIGNATURE, X-EBAY-C-REQUEST-NONCE, and X-EBAY-C-DATE headers and executes the method.

      It returns the checkout session ID (checkoutSessionId) and the purchase order details.

    • Update details and review the order

      Use the updateProxyGuestShippingAddress, updateProxyGuestShippingOption, updateProxyGuestQuantity, and getProxyGuestCheckoutSession methods to change the order and let the buyer review and approve the order.

      This method returns the order details.

  3. Place the order

    To complete the transaction and retrieve the order details, pass in the checkout session ID (checkoutSessionId) using the placeProxyGuestOrder method.

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

Important! eBay guest checkout is no longer supported by the v1 version of the Order API. eBay guest checkout through Order API v1 was dependent on the PayPal checkout flow, and 100 percent of eBay transactions now exclusively go through eBay's checkout flow.

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