order APIv1_beta.12.0

Order API Overview

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 users, eBay members or guests, buy from eBay sellers without visiting the eBay site. The Buy APIs provide the ability to purchase eBay items from your app or website.

Topics

Technical overview

The Order API supports eBay member checkout and guest checkout. With member checkout, signed in eBay members use PayPal to make their purchases. With guest checkout, buyers pay with credit cards, without signing in to eBay. The Order API lets you retrieve the purchase order information.

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 and guest_checkout_session – contains all the details of an eBay member or 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, etc.
  • Shipping address
  • Payment methods accepted
  • Payment method to use

proxy_guest_checkout_session - contains all the details to support purchasing items through a vault service provider (VSP), such as Braintree.

  • 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, etc.
  • Shipping address
  • Payment methods accepted
  • 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

guest_purchase_order – contains all the details of a purchase order for guest checkout, including:

  • Line items purchased, each with item identifier, shipping, details, seller, price, and quantity
  • Pricing summary, cost of item, discounts, tax, coupon discount, etc.
  • Status of the payment and the order

Business use cases

When used with the Buy APIs, the Order API lets you to pay for eBay items off the eBay platform and track your orders. This section outlines the high-level use cases for the Order API. Note: These use cases support both eBay guest and eBay member orders.

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 information

You can add or change the shipping address or 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 and processing status of a checkout session or order.

Pay for the order

To pay for orders, eBay members can use any payment method associated with their linked PayPal Account or a credit card. eBay guests can use a credit card, which will be processed by PayPal or they purchase items through a vault service provider (VSP), such as Braintree, and through integration with PayPal's checkout.js.

Handle returns and cancellations (eBay member checkout only)

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.

API restrictions

Please note the following constraints for the Order API.

API dependencies

The Order API is designed to be used together with the other Buy APIs and Post Order API 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 Trading and Finding. But 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.

Regional/site constraints

The Order API is currently supported on the following eBay sites:

  • EBAY-DE - eBay Germany (ebay.de)
  • EBAY-GB - eBay Great Britain (ebay.co.uk)
  • EBAY-US - eBay USA (ebay.com)

eBay Buy API and security requirements

Although the eBay Buy APIs are available for anyone to use in eBay's sandbox environment, use of the APIs in production is restricted. Users must meet standard eligibility requirements, get approvals from eBay support organizations, and sign contracts with eBay and PayPal to access the Buy APIs in production.

Also in order to process, transmit or store card holder data you must comply with the Payment Card Industry Data Security Standards (PCI DSS).

See Production eligibility requirements and Order API for information about production and PCI compliance.

Checkout session restrictions

The checkout session is created by the initiateCheckoutSession or initiateGuestCheckoutSession methods. These methods return the ID of the session, which all the other checkout methods 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 100008000651370. Any method that passes in the checkout session ID 100008000651370, must have the X-EBAY-C-MARKETPLACE-ID request header set to EBAY-US.
  • 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 and with a new payment method.

eBay bucks and coupons

The Order API does not eBay Bucks. It does support coupons but the Partner must be whitelisted to use this capibility.

proxy_guest_checkout_session resource requirement/restrictions

The following are requirements and restrictions that apply only to the proxy_guest_checkout_session resource:

  • Partners must integrate with a payment vault service provider (VSP), such as Braintree.
  • The proxy_guest_checkout_session resource supports the VSP payment flow. This payment flow is supported only for the EBAY-US marketplace.

initiateGuestPayment method requirement

The initiateGuestPayment method requires Partners to integrate with PayPal's checkout.js on the client side.