Overview
API Use Cases
Manage and complete order checkout
The Order APIs allow users to create and manage checkout sessions for both eBay members and eBay guest users. Using the methods in these APIs, users can create and update a checkout session, apply coupons and add-ons to the session, pay for an order, and retrieve information on said orders.
There are two different versions of the Order API:
- The Order API v1 can be used to create and manage eBay member checkout sessions. A member checkout involves a buyer that is logged into their eBay account and can use information stored with their account, such as their payment and shipping details, to purchase an item. Applications integrating with this checkout method must comply with Payment Card Industry Data Security Standards (PCI DSS) to ensure proper handling of sensitive credit card data.
- The Order API v2 can be used to create and manage eBay guest checkout sessions. A guest checkout involves a buyer that does not have or is not logged into an eBay account. Their information must be collected in order to purchase and ship an item, and the order is completed through the Checkout with eBay widget. For more details about the Checkout with eBay widget, see Integrating the Checkout with eBay button.
The Order API v1 methods used to create and manage an eBay member checkout session are discussed below:

- Create a member checkout session and add items to your cart using InitiateCheckoutSession. The key containers required for the request are briefly described below:
- lineItemInputs: An array of the line items being added to the cart during the checkout session.
- creditCard (optional): The buyer’s credit card information. This container is not required unless the member is using a credit card different from the one on file.
- shippingAddress (optional): The shipping address information for the order associated with the checkout session. This container is not required unless the member is using a shipping address different from the one on file.
If the call is successful, information about the checkout session will be returned in the response. The following key containers and fields will be returned in the response:
- acceptedPaymentMethods: An array of accepted payment methods that can be used to purchase the order.
- checkoutSessionId: The unique eBay identifier of the checkout session.
Note: This value is used as a URI parameter for the other checkout methods. Users should keep track of this value as there is no programmatic way to retrieve it at this time.
- ExpirationDate: The time and date, in UTC format, when the checkout session will expire.
- shippingOptions: An array of shipping options that are available for the order. By default , the first returned shipping option will be selected. See the next step for instructions on how to change the shipping option for an order.
- pricingSummary: The total cost of all the line items in the order.
- If needed, change the shipping method for a specified line item in the order using updateShippingOption. This method can be used if the buyer does not want to use the first returned shipping option automatically selected when creating a checkout session. See the shippingOptions container in the InitiateCheckoutSession response to see all available shipping options for a line item, including their cost and expected delivery date range.
- Place and pay for the order using placeOrder. The purchaseOrderId for the order will also be returned, which will be needed to retrieve details on the order in the next step.
- Review and retrieve details of the purchase order using getPurchaseOrder. This method can also be used to check if an order payment has cleared by checking the value of the purchaseOrderPaymentStatus field, and the fulfillment status of the item by checking the lineItemStatus enum.
Below are the other Order API v1 methods applicable for managing eBay member checkout sessions:
- Use updateQuantity to change the quantity of a specified line item in a checkout session.
- Use updateShippingAddress to change the shipping address for all line items in an order for a checkout session.
- Use updatePaymentInfo to change the payment method for a specified checkout session.
- Use updateAddonServiceStatus to add or remove add-on services, such as Authenticity Guarantee, to a specified line item in an order for a checkout session.
- Use applyCoupon to add a coupon to an order. Coupons are specified by their redemptionCode, and one coupon can be applied per order. Coupons can be removed from an order using removeCoupon.
- Use getCheckoutSession to retrieve details about a specific checkout session.
The Order API v2 methods used to create and manage an eBay guest checkout session are discussed below:

- Create a checkout session and add items to your cart using InitiateGuestCheckoutSession. The key containers required for the request are briefly described below:
- lineItemInputs: An array of the line items being added to the cart during the checkout session.
- shippingAddress: The shipping address information for the order associated with the checkout session.
- contactEmail: The buyer’s email address.
If the call is successful, information about the checkout session will be returned in the response. The following key containers and fields will be returned in the response:
- acceptedPaymentMethods: An array of accepted payment methods that can be used to purchase the order.
- checkoutSessionId: The unique eBay identifier of the checkout session.
Note: This value is used as a URI parameter for the other checkout methods. Users should keep track of this value as there is no programmatic way to retrieve it at this time.
- ExpirationDate: The time and date, in UTC format, when the checkout session will expire.
- shippingOptions: An array of shipping options that are available for the order. By default , the first returned shipping option will be selected. See the next step for instructions on how to change the shipping option for an order.
- pricingSummary: The total cost of all the line items in the order.
Important: In addition, the X-EBAY-SECURITY-SIGNATURE response header will be returned when using this method. This header returns the token used to launch the Checkout with eBay widget. Users should keep track of this token as there is no programmatic way to retrieve it at this time. .
- If needed, change the shipping method for a specified line item in the order using updateGuestShippingOption. This method can be used if the buyer does not want to use the first returned shipping option automatically selected when creating a checkout session. See the shippingOptions container in the InitiateCheckoutSession response to see all available shipping options for a line item, including their cost and expected delivery date range.
- Place and pay for the order using the Checkout with eBay widget. The purchaseOrderId for the order will be returned in the response URL that is sent through the Checkout with eBay widget, which will be needed to retrieve details on the order in the next step. For more details about the Checkout with eBay widget, see Integrating the Checkout with eBay button.
- Review and retrieve details of the purchase order using getGuestPurchaseOrder. This method can also be used to check if an order has been paid for by checking the value of the purchaseOrderPaymentStatus field, and the fulfillment status of the item by checking the lineItemStatus enum.
Below are the other Order API v2 methods applicable for managing eBay member checkout sessions:
- Use updateGuestQuantity to change the quantity of a specified line item in a checkout session.
- Use updateGuestShippingAddress to change the shipping address for all line items in an order for a checkout session.
- Use applyGuestCoupon to add a coupon to an order. Coupons are specified by their redemptionCode, and one coupon can be applied per order. Coupons can be removed from an order using removeGuestCoupon.
- Use getGuestCheckoutSession to retrieve details about a specific checkout session.
Bid on an auction item
The Offer API allows users to bid on a specific auction item on behalf of a buyer, setting a maximum amount they are willing to spend on the item. eBay will then make offers up to this amount, notifying the user if they have been outbid or if the bid has exceeded this set amount. Users can also retrieve the bidding details specific to the buyer of a specific auction using this API.
The API methods used to bid on an auction item are discussed below:

- Optionally, use the Browse API search method to find an auction item the buyer wants to bid on. For example, the following filter can be used to search only for auction items:
filter=buyingOptions:{AUCTION}. Buyers can also check the returned currentBidPrice container to see the current highest bid price for an auction item. For more information on retrieving items using the Browse API, see the Inventory Discovery and Refresh Guide. - Use placeProxyBid to place a proxy bid for a specific auction item on behalf of a buyer, up to a maximum amount set by the buyer. You must pass in the item_id of the item you are bidding for, as well as the maximum amount (maxAmount) the buyer is willing to bid for the item. Multiple bids may occur up to the maxAmount value, with each bid being erased by a higher bid from another user. This value should be higher than the currentBidPrice retrieved in the previous step.
- Use getBidding to retrieve the bidding details for a specific auction. If the auction is still ongoing, the current highest bid amount of the item will be returned in the currentPrice container. If this amount is higher than the buyer’s set maxAmount, call placeProxyBid again to increase this max bid amount. The buyer’s current proxy bid is also returned through the currentProxyBid container, and the suggestedBidAmounts container will return a suggested bid amount for the next bid. Once the auctionStatus is
ENDED, the value of highBidder will be returned astrueif the buyer has won the auction.
Code Samples
Create a member checkout session
curl -X POST "https://apix.ebay.com/buy/order/v1/checkout_session/initiate"
-H "Authorization: Bearer OAUTH_token"
-H "Content-Type: application/json"
-H "X-EBAY-C-MARKETPLACE-ID: EBAY_US"
-d '{
"lineItemInputs": [
{
"quantity": 1,
"itemId": "v1|1**********4|0"
},
{
"quantity": 1,
"itemId": "v1|1**********5|0"
},
{
"quantity": 1,
"itemId": "v1|1**********6|0"
}
]
}'
Place proxy bid on an auction item
curl -X POST "https://api.ebay.com/buy/offer/v1_beta/bidding/v1|2**********2|0/place_proxy_bid"
-H "Authorization: Bearer OAUTH_token"
-H "Content-Type: application/json"
-H "X-EBAY-C-MARKETPLACE-ID: EBAY_US"
-d '{
"maxAmount": {
"currency": "USD",
"value": "100.00"
}
}'
Error Handling
- When adding items to the shopping cart using the Order API, or when placing a proxy bid through the Offer API, make sure the itemId for the item belongs to the marketplace specified through the X-EBAY-C-MARKETPLACE-ID header. If the item does not belong to this marketplace, an error will occur.
- If the initiateCheckoutSession or initiateGuestCheckoutSession methods are failing due to the desired quantity exceeding the available quantity, use the getItem method of the Browse API to verify the latest quantity of the listing to make sure the requested quantity does not exceed this amount.
- If you get an invalid bid error when attempting to place a proxy bid through placeProxyBid, verify the bid meets the following criteria:
- The currency value matches the currency used on the listing marketplace
- The maximum bid amount is not higher than the auction’s Buy It Now price. If needed use getItem to see the item’s Buy It Now price (price) for an auction listing
- The maximum bid amount is not below the auction’s current bid price or minimum bid requirements. If needed, use getBidding to show the current bid price (currentPrice) of an auction item.
- The maximum bid amount is not lower than your initial maximum bid amount. The placeProxyBid method cannot be used to lower your maximum bid. If needed, use getBidding to retrieve your current max bid amount (maxAmount) for an auction item.
Best Practices
- For developers using the guest checkout methods of the Order API v2, it is required that they integrate the Checkout with eBay widget. This widget allows guests to pay for items without leaving our site. For more information on implementing Checkout with eBay, see Integrating the Checkout with eBay button in the Buying Integration Guide.
- When placing a proxy bid through the Offer API, the buyer agrees to purchase the item if they win the auction. Keep this in mind to remind the buyer of this when placing a bid on their behalf using this method.
- The initiateCheckoutSession or initiateGuestCheckoutSession methods return the eBay-generated checkoutSessionId value for a checkout session. This value is used as a URI parameter for the other checkout methods. Users should keep track of this value as there is no programmatic way to retrieve it at this time.
- The initiateCheckoutSession or initiateGuestCheckoutSession methods return a variety of information about a checkout session, such as the accepted payment methods, the available shipping options, and the shipping address that will be used for the order. Consider keeping track of this information (or using getGuestCheckoutSession to retrieve this information), as there are APIs to change this information if applicable.