Order API (v1_beta) Overview
Note: This is the v1_beta version of the Order API which supports member checkout payment flows. If you need to support guest checkout payment flows, please use the v2 version of the Order API.
The Order API is part of the eBay Buy APIs. It is used to purchase items and track the purchase orders. The Order API supports the complete checkout process. Use the Order API with the other Buy APIs to create a buying application that lets eBay members buy from eBay sellers without visiting the eBay site. The Buy APIs provide the ability to purchase eBay items from your app or website.
The Order_v1 API supports eBay member checkout. With member checkout, signed-in eBay members use a credit card to make their purchases. The Order API lets you retrieve the purchase order information.
Order v1 API no longer supports guest checkout payment flows: the
guest_purchase_order resources and methods have been removed. If you have a use case that requires guest checkout payment flows, please use the Order v2 API instead.
There are a series of steps for completing a checkout from initiating the checkout session to placing the order. After the order is placed, you can retrieve order details, including the shipping fulfillment status.
This API uses the following resources:
- checkout_session – contains all the details for an eBay member checkout, including:
- Line items, each with item identifier, payment status, net price, shipping service details, seller, and quantity
- Pricing summary, cost of item, discounts, tax, coupon discount, add-on services, etc.
- Shipping address
- Payment method to use
- purchase_order – contains all the details of a purchase order, including:
- Line items purchased, each with item identifier, payment status, net price, shipping service details, seller, and quantity
- Shipping address used and fulfillment information
- Payment instrument used
- Pricing summary, cost of item, discounts, tax, coupon discount, etc.
- Status of the payment and the order details
Business use cases
This section outlines the high-level use cases for the Order API.
Initiate a checkout
This is the first step in the checkout process. This starts the process and creates a cart containing the items.
Update line item information
You can add or change the quantity or shipping option for any line item in the order. This lets the shopper choose the shipping cost/speed for any line item.
Update order shipping and payment information
You can change the shipping address, add-on services, or add or change the payment information for the order. Each order can have only one shipping address and one payment method.
Get checkout and order details
You can view the details for a checkout session and the processing status of an order.
Pay for the order
eBay members pay for their order using a credit card.
Handle returns and cancellations
Using the Order API, you can retrieve the legacyReference fields and then use this information with the Post Order API to create and complete an item return or an order cancellation.
This section discusses the Order API restrictions.
The Order API is designed to be used together with the other Buy APIs and Post Order API to create cohesive buying applications.
The Buy APIs identifiers for item and order do not match the identifiers used on the eBay site and in buyer emails. So you cannot use the Buy APIs identifiers with any of the eBay legacy APIs, such as Finding. For details, see the Item ID legacy API compatibility overview in the Buying Integration Guide.
You can use the Order API to return the legacy order IDs. These can then be used in the Post Order API to process item returns and order cancellations for eBay member checkouts. For details, see Handling post order tasks in the Buying Integration Guide.
For a list of the supported eBay sites for all the Buy APIs, see Buy API Support by Marketplace.
To specify the site, set the X-EBAY-C-MARKETPLACE-ID request header to the site.
X-EBAY-C-MARKETPLACE-ID = EBAY_GB
eBay Buy API, security, and sandbox requirements
Use of the eBay Buy APIs in production is restricted.
The Buy APIs are available for anyone to use in eBay's sandbox environment, except for the Order API, which is restricted.
To access restricted APIs, users must meet standard eligibility requirements, get approvals from eBay support organizations, and sign contracts with eBay.
Checkout session restrictions
The checkout session is created by the initiate checkout session methods. These methods return the ID of the session, which all the other checkout methods in that resource pass in as a request parameter. The following are the checkout session restrictions:
All methods that affect a checkout session must use the same
X-EBAY-C-MARKETPLACE-IDvalue that was used when the checkout session was created.
For example, let's say you used
X-EBAY-C-MARKETPLACE-ID = EBAY_USto create a checkout session with the ID of 123456. Any method that passes in the checkout session ID 123456, must have the
X-EBAY-C-MARKETPLACE-IDrequest header set to
Developer App ID
The same developer App ID must be used for all methods in the resource.
The only supported payment method is credit card.
Credit card declined
If a credit card is declined, that checkout session is now unusable. To place the order, you must create a new checkout session using a different credit card.
The Order API supports only domestic shipping. For example, an item purchased on the EBAY_DE marketplace can be shipped only to an address in Germany.
eBay bucks and coupons
The Order API does not support eBay Bucks. It does support coupons but the Partner must be white listed to use this capability.
The Order API limits the number of calls that can be made per day on behalf of your application. For the current application rate limits, see the eBay API Call Limits page.