Order API

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 the item using PayPal 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 user token. For information about this token, see OAuth access tokens.

  • If the buyer has a PayPal account linked to their eBay member account, they can pay with PayPal. If not, 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. You can either go through the process of becoming PCI compliant or use a PCI vault service.

 

Order API calls Overview

The Order API has 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:

  • Create a checkout session
    You use initiateCheckoutSession or the initiateGuestCheckoutSession call 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.
  • 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 or placeGuestOrder call to complete the checkout flow. The call creates the purchase order, initiates the payment process, and terminates the specified guest checkout session. The payment process can sometimes take a few minutes. The response from these calls 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 about 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 payment flow

An eBay guest can use this flow to pay for items using a credit card, which is passed in using the initiateGuestCheckoutSession or the updateGuestPaymentInfo calls.

An eBay member can use this flow to pay for items using any payment method associated with their PayPal account or using another credit card, which is passed in using the updatePaymentInfo call.

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 this is an eBay guest checkout or the eBay member wants to use a credit card not associated with their PayPal account, pass in the buyer's credit card information.

    This call returns the checkout session ID (checkoutSessionId).

     

  2. Make adjustments to the order

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

    This call returns the order details.

     

  3. Review the order

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


    This call returns the order details.

     

  4. Place the order

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

    This call returns the purchase order ID and payment status.

 

Order API Payment Flow

 

PayPal Checkout payment flow for eBay guests

Important! The PayPal Checkout payment flow is supported only for eBay guest checkouts and requires eBay partners to integrate with PayPal's client-side REST checkout.js JavaScript. For details see, PayPal checkout.js Integration.


This flow lets eBay guests pay for items with or without having a PayPal account. They can sign into PayPal and use any payment method associated with their Paypal Account, or without a PayPal account they can pay using a credit card or a direct debit all without leaving your App or site. Using this flow you do not need to be PCI compliant.

For this flow, you do not pass in the credit card information in the initiateGuestCheckoutSession call. Instead you use the initiateGuestPayment call to set the payment method to PayPal's Checkout.

The following walks you through the process of having a Buyer (eBay guest) pay using PayPal Checkout 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.

  1. Start the checkout session

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

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

    This call returns the checkout session ID (checkoutSessionId).

     

  2. Make adjustments and review the order

    Use the updateGuestQuantity, updateGuestShippingAddress, updateGuestShippingOption, and getGuestCheckoutSession calls to change the order and let the buyer review and approve the order.

    This call returns the order details.

     

  3. Specify payment as PayPal Checkout

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

         paymentMethodBrandType = PAYPAL_CHECKOUT
         paymentMethodType = WALLET

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

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

     

  4. Use checkout.js to pay for the order

    Note: Your App must be integrated with PayPal checkout.js. This step is between only the eBay partner and PayPal.

    Use checkout.js JavaScript and the PayPal cart ID (externalReferenceId) to render the PayPal UI button and payment functionality on your site.

    The Buyer clicks on the PayPal 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 call 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 call .

PayPal Checkout Payment Flow

 

Vault Service Provider (VSP) Checkout payment flow for eBay guests

This flow lets eBay guests pay for items with a credit card and you do not need to be PCI compliant. However, eBay partners must integrate with a VSP, such as Braintree. For this flow, you use the calls in the proxy_guest_checkout_session resource. The VSP handles only calls that pass in payment information. In this flow, the VSP handles only the updateProxyGuestPaymentInfo call.

Note: This payment flow is supported only for the EBAY-US marketplace

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.

  1. Start the checkout session

    Use the initiateProxyGuestCheckoutSession call 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 call.

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

     

  2.  Make adjustments to the order

    Note: Making the following changes can be done in any order.

    • Add or change the credit card information

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

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

      The call 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 call.

      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 calls to change the order and let the buyer review and approve the order.

      This call 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 call.

Vault Service Provider Payment Flow

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 using the Post Order API or Submit a cancellation request using the Post Order API.

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

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

Note: The following processes can be used only for eBay member checkouts.

Create a return request using the Post Order API

The lineItems.legacyReference.legacyItemId and lineItemslegacyReference.legacyTransactionId fields returned by the Order API getPurchaseOrder call are used in the Post Order API Create Return Request call 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 call and the corresponding fields returned by the getPurchaseOrder call.

Post Order API Field

Order API Field

Value Returned by
Order API

returnRequest.itemId lineItems.legacyReference.legacyItemId

330005959274

returnRequest.transactionId lineItems.legacyReference.legacyTransactionId

8905715014


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

Order API
getPurchaseOrder Call Response
Post Order API
Create Return Request

   "legacyReference" :
     {
       "legacyItemId" : "330005959274",
       "legacyTransactionId" : "8905715014",
       "legacyOrderId" : "330005959274-8905715014!120000000708871"            
     },
     ... 
"purchaseOrderPaymentStatus": "PENDING",
... 	
POST https://api.ebay.com/post-order/v2/return      
{
  "returnRequest":
  {
    "itemId": "330005959274",
    "transactionId": "8905715014"
  }
}

 

Submit a cancellation request using the Post Order API

The lineItems.legacyReference.legacyOrderId field is returned by the Order API getPurchaseOrder call and is used in the Post Order API Submit Cancellation Request call 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 call and the corresponding field returned by the getPurchaseOrder call.

Post Order API Field

Order API Field

Value Returned by Order API

legacyOrderId    lineItems.legacyReference.legacyOrderId330005959274-8905715014!120000000708871
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 call using the values of the legacyOrderId and purchaseOrderPaymentStatus fields.

Order API
getPurchaseOrder Call Response
Post Order API
Create Return Request

   "legacyReference" :
     {
       "legacyItemId" : "330005959274",
       "legacyTransactionId" : "8905715014",
       "legacyOrderId" : "330005959274-8905715014!120000000708871"    
     },
     ... 
"purchaseOrderPaymentStatus": "PENDING",
... 
 POST https://api.ebay.com/post-order/v2/cancellation     
{
  "legacyOrderId": "330005959274-8905715014!120000000708871",     
  "buyerPaid": "false",
  "cancelReason":"ORDER_MISTAKE"
}