# Checkout/Bid Guide

**Guide Group:** Checkout/Bid

---

## Overview

The Checkout/Bid APIs allow users to manage and complete order checkout, as well as place bids on auction items.

## API Use Cases

[Manage and complete order checkout](#order-checkout)  
[Bid on an auction item](#bid)

##### 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)](https://www.pcisecuritystandards.org/) 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](https://developer.ebay.com/api-docs/buy/static/api-order.html#Integrat).

**Order API v1**

The **Order API v1** methods used to create and manage an **eBay member** **checkout** session are discussed below: 

![banner-image](/cms/img/checkoutbidguide/order-v1-flow.png)

1.  Create a member checkout session and add items to your cart using [InitiateCheckoutSession](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession). The key containers required for the request are briefly described below: 
    
    *   [lineItemInputs](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#request.lineItemInputs): An array of the line items being added to the cart during the checkout session. 
    *   [creditCard](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#request.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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#request.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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.acceptedPaymentMethods): An array of accepted payment methods that can be used to purchase the order. 
    *   [checkoutSessionId](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.expirationDate): The time and date, in UTC format, when the checkout session will expire. 
    *   [shippingOptions](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.lineItems.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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.pricingSummary): The total cost of all the line items in the order. 
2.  If needed, change the shipping method for a specified line item in the order using [updateShippingOption](/api-docs/buy/order_v1/resources/checkout_session/methods/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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.lineItems.shippingOptions target=) container in the [InitiateCheckoutSession](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.lineItems.shippingOptions) response to see all available shipping options for a line item, including their cost and expected delivery date range.
3.  Place and pay for the order using [placeOrder](/api-docs/buy/order_v1/resources/checkout_session/methods/placeOrder). The [purchaseOrderId](/api-docs/buy/order_v1/resources/checkout_session/methods/placeOrder#response.purchaseOrderId) for the order will also be returned, which will be needed to retrieve details on the order in the next step. 
4.  Review and retrieve details of the purchase order using [getPurchaseOrder](/keystone/guides/api-docs/buy/order_v1/resources/purchase_order/methods/getPurchaseOrder). This method can also be used to check if an order payment has cleared by checking the value of the [purchaseOrderPaymentStatus](/api-docs/buy/order_v1/resources/purchase_order/methods/getPurchaseOrder#response.purchaseOrderPaymentStatus) field, and the fulfillment status of the item by checking the [lineItemStatus](/api-docs/buy/order_v1/resources/purchase_order/methods/getPurchaseOrder#response.lineItems.lineItemStatus) enum.

Below are the other Order API v1 methods applicable for managing eBay member checkout sessions: 

*   Use [updateQuantity](/api-docs/buy/order_v1/resources/checkout_session/methods/updateQuantity) to change the quantity of a specified line item in a checkout session. 
*   Use [updateShippingAddress](/api-docs/buy/order_v1/resources/checkout_session/methods/updateShippingAddress) to change the shipping address for all line items in an order for a checkout session. 
*   Use [updatePaymentInfo](/api-docs/buy/order_v1/resources/checkout_session/methods/updatePaymentInfo) to change the payment method for a specified checkout session.
*   Use [updateAddonServiceStatus](/api-docs/buy/order_v1/resources/checkout_session/methods/updateAddonServicesStatus) 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](/api-docs/buy/order_v1/resources/checkout_session/methods/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](/api-docs/buy/order_v1/resources/checkout_session/methods/removeCoupon).
*   Use [getCheckoutSession](/api-docs/buy/order_v1/resources/checkout_session/methods/getCheckoutSession) to retrieve details about a specific checkout session.

**Order API v2**

The **Order API v2** methods used to create and manage an **eBay guest checkout** session are discussed below: 

![banner image](/cms/img/checkoutbidguide/order-v2-flow.png)

1.  Create a checkout session and add items to your cart using [InitiateGuestCheckoutSession](/api-docs/buy/order/resources/guest_checkout_session/methods/initiateGuestCheckoutSession). The key containers required for the request are briefly described below: 
    
    *   [lineItemInputs](/api-docs/buy/order/resources/guest_checkout_session/methods/initiateGuestCheckoutSession#request.lineItemInputs): An array of the line items being added to the cart during the checkout session.
    *   [shippingAddress](/api-docs/buy/order/resources/guest_checkout_session/methods/initiateGuestCheckoutSession#request.shippingAddress): The shipping address information for the order associated with the checkout session.
    *   [contactEmail](/api-docs/buy/order/resources/guest_checkout_session/methods/initiateGuestCheckoutSession#request.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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.acceptedPaymentMethods): An array of accepted payment methods that can be used to purchase the order. 
    *   [checkoutSessionId](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.expirationDate): The time and date, in UTC format, when the checkout session will expire. 
    *   [shippingOptions](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.lineItems.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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.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. .
    
2.  If needed, change the shipping method for a specified line item in the order using [updateGuestShippingOption](/api-docs/buy/order_v1/resources/checkout_session/methods/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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.lineItems.shippingOptions) container in the [InitiateCheckoutSession](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession#response.lineItems.shippingOptions) response to see all available shipping options for a line item, including their cost and expected delivery date range. 
3.  Place and pay for the order using the **Checkout with eBay** widget. The [purchaseOrderId](/api-docs/buy/order_v1/resources/checkout_session/methods/placeOrder#response.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](/api-docs/buy/static/api-order.html#Integrat).
4.  Review and retrieve details of the purchase order using [getGuestPurchaseOrder](/api-docs/buy/order/resources/guest_purchase_order/methods/getGuestPurchaseOrder). This method can also be used to check if an order has been paid for by checking the value of the [purchaseOrderPaymentStatus](/api-docs/buy/order_v1/resources/purchase_order/methods/getPurchaseOrder#response.purchaseOrderPaymentStatus) field, and the fulfillment status of the item by checking the [lineItemStatus](/api-docs/buy/order_v1/resources/purchase_order/methods/getPurchaseOrder#response.lineItems.lineItemStatus) enum.

Below are the other Order API v2 methods applicable for managing eBay member checkout sessions:

*   Use [updateGuestQuantity](/api-docs/buy/order_v1/resources/checkout_session/methods/updateQuantity) to change the quantity of a specified line item in a checkout session. 
*   Use [updateGuestShippingAddress](/api-docs/buy/order_v1/resources/checkout_session/methods/updateShippingAddress) to change the shipping address for all line items in an order for a checkout session. 
*   Use [applyGuestCoupon](/api-docs/buy/order_v1/resources/checkout_session/methods/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 [removeGuestCoupon](/api-docs/buy/order_v1/resources/checkout_session/methods/removeCoupon). 
*   Use [getGuestCheckoutSession](/api-docs/buy/order_v1/resources/checkout_session/methods/getCheckoutSession) 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: 

![banner-text](/cms/img/checkoutbidguide/offer-flow.png)

1.  Optionally, use the **Browse API** [search](/api-docs/buy/browse/resources/item_summary/methods/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](/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.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](/develop/guides-v2/inventory-discovery-and-refresh/inventory-discovery-and-refresh-guide).
2.  Use [placeProxyBid](/api-docs/buy/offer/resources/bidding/methods/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](/api-docs/buy/offer/resources/bidding/methods/placeProxyBid#uri.item_id) of the item you are bidding for, as well as the maximum amount ([maxAmount](/api-docs/buy/offer/resources/bidding/methods/placeProxyBid#request.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](/api-docs/buy/browse/resources/item_summary/methods/search#response.itemSummaries.currentBidPrice)  retrieved in the previous step.
3.  Use [getBidding](/api-docs/buy/offer/resources/bidding/methods/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](/api-docs/buy/offer/resources/bidding/methods/getBidding#response.currentPrice) container. If this amount is higher than the buyer’s set [maxAmount](/api-docs/buy/offer/resources/bidding/methods/placeProxyBid#request.maxAmount), call [placeProxyBid](/api-docs/buy/offer/resources/bidding/methods/placeProxyBid) again to increase this max bid amount. The buyer’s current proxy bid is also returned through the [currentProxyBid](/api-docs/buy/offer/resources/bidding/methods/getBidding#response.currentProxyBid) container, and the [suggestedBidAmounts](/api-docs/buy/offer/resources/bidding/methods/getBidding#response.suggestedBidAmounts) container will return a suggested bid amount for the next bid. Once the [auctionStatus](/api-docs/buy/offer/resources/bidding/methods/getBidding#response.auctionStatus) is `ENDED`, the value of [highBidder](/api-docs/buy/offer/resources/bidding/methods/getBidding#response.highBidder) will be returned as `true` if the buyer has won the auction.

## Code Samples

## 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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession) or [initiateGuestCheckoutSession](/api-docs/buy/order/resources/guest_checkout_session/methods/initiateGuestCheckoutSession) methods are failing due to the desired quantity exceeding the available quantity, use the [getItem](/api-docs/buy/browse/resources/item/methods/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](/api-docs/buy/offer/resources/bidding/methods/placeProxyBid), verify the bid meets the following criteria:
    *   The [currency](/api-docs/buy/offer/resources/bidding/methods/placeProxyBid#request.maxAmount.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](/api-docs/buy/browse/resources/item/methods/getItem) to see the item’s Buy It Now price ([price](/api-docs/buy/browse/resources/item/methods/getItem#response.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](/api-docs/buy/offer/resources/bidding/methods/getBidding) to show the current bid price ([currentPrice](/api-docs/buy/offer/resources/bidding/methods/getBidding#response.currentPrice)) of an auction item.
    *   The maximum bid amount is not lower than your initial maximum bid amount. The [placeProxyBid](https://developer.ebay.com/api-docs/buy/offer/resources/bidding/methods/placeProxyBid) method cannot be used to lower your maximum bid. If needed, use [getBidding](/api-docs/buy/offer/resources/bidding/methods/getBidding) to retrieve your current max bid amount ([maxAmount](/api-docs/buy/offer/resources/bidding/methods/getBidding#response.currentProxyBid.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](/api-docs/buy/static/api-order.html#integrat) 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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession) or [initiateGuestCheckoutSession](/api-docs/buy/order/resources/guest_checkout_session/methods/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](/api-docs/buy/order_v1/resources/checkout_session/methods/initiateCheckoutSession) or [initiateGuestCheckoutSession](/api-docs/buy/order/resources/guest_checkout_session/methods/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](/api-docs/buy/order/resources/guest_checkout_session/methods/getGuestCheckoutSession) to retrieve this information), as there are APIs to change this information if applicable.

## Code Samples

### Create a member checkout session

**Label:** Create a member checkout session 

#### Bash Sample

```bash
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

**Label:** Place proxy bid on an auction item

#### Bash Sample

```bash
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"
    }
}'

```

## Related Topics

- [Order API v1 ](/api-docs/buy/order_v1/resources/methods)
- [Order API v2](/api-docs/buy/order/resources/methods)
- [Offer API](/api-docs/buy/offer/resources/methods)
- [More Guides](/develop/guides)