Skip to main content

Note: This is the v2 version of the Order API which supports guest checkout payment flows. If you need to support member checkout payment flows, please use the v1_beta 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 guest checkout process. Use the Order API with the other Buy APIs to create a buying application that lets guest users buy from eBay sellers without visiting the eBay site. The Buy APIs provide the ability to purchase eBay items from your app or website.

Note: This is a (Limited Release) API available only to select developers approved by business units. For information on how to obtain access to this API in production, see the Buy APIs Requirements.

Technical overview

The Order API supports eBay guest checkout. With guest checkout, users purchase items using the Checkout with eBay widget.

There are a series of steps for completing a checkout. After the checkout is initiated, you can retrieve order details, including the shipping fulfillment status.

Tip: Refer to the Order API section of the Buying Integration Guide for details about the new Checkout with eBay widget.

This API uses the following resources:

  • guest_checkout_session – contains all of the details for a guest checkout, including:
    • Line items, each with an item identifier, payment status, net price, shipping service details, seller, and quantity
    • Pricing summary, with the cost of the items, discounts, taxes, and coupon discounts
    • Shipping address
  • guest_purchase_order – contains all of the details of a purchase order for guest checkout, including:
    • Line items purchased, each with an item identifier, shipping details, seller, price, and quantity
    • Pricing summary, with the cost of the items, discounts, taxes, and coupon discounts
    • Status of the payment and the order

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

You can change the shipping address for the order. Each order can have only one shipping address.

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

To pay for orders, eBay guests use the new Checkout with eBay widget.

Tip: Refer to the Order API section of the Buying Integration Guide for details about the new Checkout with eBay widget.

API restrictions

This section provides information about Order API restrictions.

API dependencies

The Order API is designed to be used together with the other Buy APIs to create cohesive buying applications. The identifiers used in the Order API are only compatible with the Buy APIs.

Identifier incompatibility

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 Legacy API compatibility in the Buying Integration Guide.

You can use the Order API to return the legacy order IDs.

Regional/site constraints

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. For example:

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.

Developers who require access to guest checkout methods should reach out to Developer Technical Support (DTS) and/or their Business Unit contact to request approval. Once approved for production use of the Buy APIs for a guest checkout use case, developers will then be granted access to use the guest checkout methods in the sandbox as well.

Note: Refer to the Production eligibility requirements and Order API sections of the Buying Integration Guide for more information.

Checkout session restrictions

The checkout session is created by the initiateGuestCheckoutSession method. This method returns the ID of the session, which all the other guest checkout methods in that resource pass in as a request parameter. The following are the checkout session restrictions:

  • X-EBAY-C-MARKETPLACE-ID value - All methods that affect a checkout session must use the same X-EBAY-C-MARKETPLACE-ID value that was used when the checkout session was created.

    For example, lets say you used X-EBAY-C-MARKETPLACE-ID = EBAY_US to 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-ID request header set to EBAY_US.

  • Developer App ID - The same developer App ID must be used for all methods in the resource.

Shipping restrictions

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 use of this capability must be authorized.

Rate limits

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.