Buy APIs Application Example

This section shows you how to use the Feed, Browse, and Order APIs in a shopping flow. This flow is just one of many flows supported by the eBay Buy APIs.

Feed Browse Order API Flow Chart

Note: In the following sections, the screen shots are from a hypothetical application that integrates the eBay Buy APIs using the flow shown above.

Offering eBay items

The first step in the flow is to retrieve the eBay items by downloading a feed file using the Feed API.

getItemFeed method request
GET https://api.ebay.com/buy/feed/v1_beta/item?feed_scope=NEWLY_LISTED&category_id=15032&date=20170924
getItemFeed method response

The response is aTSV_GZIP (tab separated value gzip) file. Below is a partial feed file that shows only the fields containing data and is formatted for readability. To a list of the fields in the Item feed file, see Response payload in the method reference.

Important! The Feed API does not return JSON. It only returns a TSV_GZIP file. The Response Payload in the method reference is shown in JSON so that each column header can be explained.

 

Column

Value

 

itemId v1|190006102824|0 The screen below shows a page with a variety of items. The item in the upper-left was created using the title, imageUrl, and priceValue values.

 

Image of an iPhone showing eBay Items

 

 

 

title Samsung Galaxy Note 4 Sm-n910u Gold 5.7" QHD, 32GB, 16MP
imageUrl https://i.ebayimg.com/xxx.jpg
categoryId 170594
category Cell Phones & Accessories:Cell Phones & Smartphones
localizedAspects color:Gold,size:32GB
sellerUsername weSellPhones
sellerFeedbackScore 54918
sellerFeedbackPercentage 98
brand Samsung
mnp SMN910U
conditionId 1000
condition New
priceValue 456.99
priceCurrency USD

 

Getting item details

When the shopper clicks on an item, use the value of the ItemId field from the feed file as a URI parameter in the Browse API getItem method to retrieve the details of the item.

Note: It is strongly recommended you use the X-EBAY-C-ENDUSERCTX header to improved shipping information accuracy and affiliates must use this header to get their affiliate tracking ID. Refer to the Browse API getItem method reference page for details.

getItem method request
GET https://api.ebay.com/buy/browse/v1/item/v1|201533667898|0
getItem method response

The getItem method response contains the details of the item. Below are the fields that were used from the response to create the screen to the right.

Response Field

Value

 

title

Samsung Galaxy Note 4 SM-N910U Gold 5.7\" QHD, 32GB, 16MP

Image of an iPhone with details of a specific item

 

 

 

 

 

 

 

 

 

 

 

image

https://i.ebayimg.com/....

price.value

456.99

price.currency

USD

localizedAspects.name
localizedAspects.value

Contract

Without Contract

localizedAspects.name
localizedAspects.value

OS

Android

localizedAspects.name
localizedAspects.value

Carrier

Unlocked

localizedAspects.name

localizedAspects.value

Lock Status

Factory Unlocked

seller.username

weSellPhones

seller.feedbackPercentage

seller.feedbackScore

99.8

54918

shippingOptions.shippingServiceCode

shippingOptions.shippingCost.value

USPS Standard

0.00

shippingOptions.shippingServiceCode

shippingOptions.shippingCost.value

FedEx Express

4.99

 

Completing the transaction (Checkout)

The checkout flow begins when a shopper indicates they want to purchase the item. In the example above, the shopper would click on the Buy It Now button to start the transaction. This flow creates a checkout session, captures the shipping address and payment method, and creates and pays for the order.

Note: To meet security requirements for payments, the Production URL for checkout_session and guest_checkout_session methods is: https://apix.ebay.com/buy/order/v1.

 

Important! In order to process, transmit, or store card holder data, you must comply with the Payment Card Industry Data Security Standards (PCI DSS). See Order API for information about PCI compliance.

 

The Order API supports two flows, one for a guest checkout and one for an eBay member checkout:

Guest and Member Checkout Flows

 

Tip: To test the entire checkout flow, you might need a ‘test’ credit card. You can generate a credit card number using http://www.getcreditcardnumbers.com.

 

Note: Personal data, such as seller's name, buyer's name and address, etc. have been anonymized in the requests and the responses, per eBay policy.

 

initiateGuestCheckoutSession method request (guest)

For a guest checkout session, you use the Order API and pass in the items and their quantity, the buyer’s name, and the shipping and payment information.

POST https://apix.ebay.com/buy/order/v1/guest_checkout_session/initiate
{
  "contactEmail": "testEmail@someSite.com",
  "contactFirstName": "Test",
  "contactLastName": "Buyer",
  "shippingAddress": {
    "recipient": "Test Buyer",
    "phoneNumber": 9999999999,
    "addressLine1": "123 Some Street",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "postalCode": "95134",
    "country": "US"
  },
  "lineItemInputs": [
    {
      "quantity": 1,
      "itemId": "v1|190006102824|0"
    }
  ]
}

 

initiateCheckoutSession method request (eBay member)

For an eBay member checkout, you pass in the items and their quantity and the shipping information. This method verifies that the eBay member has a linked valid PayPal account. If there is a problem or the eBay member wants to pay by credit card, use the updatePaymentInfo method to add their payment choice.

Note: By default, eBay member checkout is not supported in the eBay sandbox environment. For developers that apply for and are granted permission to use the eBay Buy APIs in production, the member checkout capability will also be enabled in the sandbox. For more information about applying for access and eligibility requirements, see Production eligibility requirements.


initiateCheckoutSession method request (eBay member)
POST https://apix.ebay.com/buy/order/v1/checkout_session/initiate

{
  "shippingAddress": {
    "addressLine1": "123 Some Street",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "postalCode": "95134",
    "country": "US",
    "recipient": "Test Buyer",
    "phoneNumber": "9999999999"
  },
  "lineItemInputs": [
    {
      "quantity": 1,
      "itemId": "v1|190006102824|0"
    }
  ]
}

The initiateCheckoutSession method creates a checkout session that your application uses to process the shopper’s payment. It returns information about the item, order, shipping, payment methods, and a checkout session ID (highlighted in yellow), which is used by the placeOrder method.

initiateCheckoutSession method response (eBay member)
{
  "checkoutSessionId": "5016712327",
  "expirationDate": "2036-08-11T23:03:18.501Z",
  "lineItems": [
    {
      "itemId": "v1|190006102824|0",
      "title": "Samsung Galaxy Note 4 SM-N910U Gold 5.7\" QHD, 32GB, 16MP",
      "shortDescription": "New Samsung Galaxy Note 4 SM-N910U Gold",
      "image": {
        "imageUrl": "https://i.ebayimg..."
      },
      "seller": {
        "username": "weSellPhones"
      },
      "quantity": 1,
      "lineItemId": "5195728827",
      "baseUnitPrice": {
        "value": 456.99,
        "currency": "USD"
      },
      "shippingOptions": [
        {
          "selected": true,
          "shippingOptionId": "5274330495",
          "shippingServiceCode": "USPS Standard",
          "shippingCarrierCode": "USPS",
          "minEstimatedDeliveryDate": "2016-08-15T07:00:00.000Z",
          "maxEstimatedDeliveryDate": "2016-08-23T07:00:00.000Z",
          "baseDeliveryCost": {
            "value": 0,
            "currency": "USD"
          }
        },
        {
          "selected": false,
          "shippingOptionId": "5274330507",
          "shippingServiceCode": "FedEx Express",
          "shippingCarrierCode": "FedEx",
          "minEstimatedDeliveryDate": "2016-08-15T07:00:00.000Z",
          "maxEstimatedDeliveryDate": "2016-08-23T07:00:00.000Z",
          "baseDeliveryCost": {
            "value": 4.99,
            "currency": "USD"
          }
        }
      ],
      "netPrice": {
        "value": 456.99,
        "currency": "USD"
      }
    }
  ],
  "shippingAddress": {
    "addressLine1": "123 Some Street",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "postalCode": "95134",
    "country": "US",
    "recipient": "Test Buyer",
    "phoneNumber": "9999999999"
  },
  "pricingSummary": {
    "priceSubtotal": {
      "value": 456.99,
      "currency": "USD"
    },
    "priceDiscount": {
      "value": "0.00",
      "currency": "USD"
    },
    "deliveryCost": {
      "value": 0,
      "currency": "USD"
    },
    "deliveryDiscount": {
      "value": "0.00",
      "currency": "USD"
    },
    "tax": {
      "value": 0,
      "currency": "USD"
    },
    "fee": {
      "value": "0.00",
      "currency": "USD"
    },
    "adjustment": {
      "value": 0,
      "currency": "USD"
    },
    "total": {
      "value": 456.99,
      "currency": "USD"
    }
  },
  "acceptedPaymentMethods": [
    {
      "paymentMethodMessages": [
        {
          "legalMessage": "PayPal processes payments for eBay. A PayPal account isn't required."
        }
      ]
    }
  ]
}       

To create the purchase order, which starts the payment process and terminates the checkout session use the placeOrder method.

placeGuestOrder method request (guest)
POST https://apix.ebay.com/buy/order/v1/guest_checkout_session/{checkoutSessionId}/place_order
placeOrder method request (eBay member)
POST https://apix.ebay.com/buy/v1/checkout_session/{checkoutSessionId}/place_order

The placeOrder method returns the ID of the purchase order (highlighted in yellow). You should store the purchaseOrderId value so, in the future, you can retrieve the details of this purchase.

placeGuestOrder method response (guest)
{
  "purchaseOrderId": "5833850019",
  "purchaseOrderHref": "buy/order/v1/purchase_order/5833850019",
  "purchaseOrderPaymentStatus": "PAID"
}
placeOrder method response (eBay member)
{
  "purchaseOrderId": "5832216756",
  "purchaseOrderHref": "buy/order/v1/purchase_order/5832216756",
  "purchaseOrderPaymentStatus": "PAID"
}

 

Getting Order Details (Order API – eBay member)

When you need to get the details of a completed transaction, you can use the value of purchaseOrderId (highlighted in the placeOrder method response above) as a URI parameter in the getPurchaseOrder method.

getPurchaseOrder method request (eBay member)
GET https://api.ebay.com/buy/order/v1/purchase_order/5832216756

The getPurchaseOrder method returns the details of the specified purchase order.

getPurchaseOrder method response (eBay member)

The legacyReference fields enable you to use the Post Order API to manage returns and cancellations.

Note: You can use the Post Order API only for eBay member checkouts.

{
  "purchaseOrderId": "5832216756",
  "purchaseOrderCreationDate": "2016-06-21T23:29:07.000Z",
  "lineItems": [
    {
      "lineItemId": "5195728827",
      "itemId": "v1|190006102824|0",
      "title": "Samsung Galaxy Note 4 SM-N910U Gold 5.7\" QHD, 32GB, 16MP",
      "image": {
        "imageUrl": "https://...jpg"
      },
      "seller": {
        "username": "weSellPhones"
      },
      "quantity": 1,
      "netPrice": {
        "value": "456.99",
        "currency": "USD"
       },
	"lineItemPaymentStatus": "PAID",
      "lineItemStatus": "PAID",
      "shippingDetail": {
        "shippingServiceCode": "USPS Parcel Select Ground",
        "shippingCarrierCode": null,
        "minEstimatedDeliveryDate": "2016-06-24T07:00:00.487Z",
        "maxEstimatedDeliveryDate": "2016-06-29T07:00:00.487Z"
      },
        "legacyReference":{
        "legacyTransactionId": "8905715014",
        "legacyItemId": "350007217675",
        "legacyOrderId": "350007217675-8905715014!5832216756"
        }
     }
  ],
  "pricingSummary": {
    "priceSubtotal": {
      "value": "456.99",
      "currency": "USD"
    },
    "priceDiscount": {
      "value": "0.00",
      "currency": "USD"
    },
    "deliveryCost": {
      "value": "0.00",
      "currency": "USD"
    },
    "deliveryDiscount": {
      "value": "0.00",
      "currency": "USD"
    },
    "tax": {
      "value": "0.00",
      "currency": "USD"
    },
    "fee": {
      "value": "0.00",
      "currency": "USD"
    },
    "adjustment": {
      "value": "0.00",
      "currency": "USD"
    },
    "total": {
      "value": "456.99",
      "currency": "USD"
    }
  },
  "paymentInstrument": {
    "paymentMethodType": "CREDIT_CARD"
  },
  "purchaseOrderStatus": "PAID",
  "purchaseOrderPaymentStatus": "PAID",
  "shippingFulfillments": [
    {
      "shippingServiceCode": "USPS Standard",
      "minEstimatedDeliveryDate": "2016-06-24T07:00:00.000Z",
      "maxEstimatedDeliveryDate": "2016-06-29T07:00:00.000Z",
      "lineItemReferences": [
        {
          "lineItemId": "5195728827",
          "quantity": 1
        }
      ]
    }
  ],
  "shippingUserAddress": {
    "addressLine1": "123 Some Street",
    "city": "San Jose",
    "stateOrProvince": "CA",
    "postalCode": "95125",
    "country": "US",
    "recipient": "Test Buyer"
  }
}