API docs by Redocly

Order API (v2.1.0)

Download OpenAPI specification:Download

License: eBay API License Agreement

Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.

Note: This is a Limited Release(Limited Release) API available only to select developers approved by business units.

The Order API provides interfaces that let shoppers pay for items. It also returns payment and shipping status of the order.

guest_checkout_session

applyGuestCoupon

Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.

Limited Release(Limited Release) This method is only available to select developers approved by business units.

This method adds a coupon to an eBay guest checkout session and applies it to all the eligible items in the order.

The checkoutSessionId is passed in as a URI parameter and is required. The redemption code of the coupon is in the payload and is also required.

For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.

The URLs for this method are:

Authorizations:
Client_Credentials
path Parameters
checkoutSessionId
required
string

The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the initiateGuestCheckoutSession method.

Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details.

header Parameters
X-EBAY-C-MARKETPLACE-ID
required
string

A header that identifies the user's business context and is specified using a marketplace ID value.

Note: This header does not indicate a language preference or consumer location.

See Marketplace ID values for a list of supported values.

Request Body schema: application/json

The container for the fields used to apply a coupon to a guest checkout session.

redemptionCode
string

The redemption code of the coupon.

Maximum: One redemption code per order

Responses

Request samples

Content type
application/json
{
  • "redemptionCode": "string"
}

getGuestCheckoutSession

Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.

Limited Release(Limited Release) This method is only available to select developers approved by business units.

This method returns the details of the specified guest checkout session. The checkoutSessionId is passed in as a URI parameter and is required. This method has no request payload.

For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.

The URLs for this method are:

Authorizations:
Client_Credentials
path Parameters
checkoutSessionId
required
string

The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the initiateGuestCheckoutSession method.

Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details.

header Parameters
X-EBAY-C-MARKETPLACE-ID
required
string

A header that identifies the user's business context and is specified using a marketplace ID value.

Note: This header does not indicate a language preference or consumer location.

See Marketplace ID values for a list of supported values.

Responses

initiateGuestCheckoutSession

Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.

Limited Release(Limited Release) This method is only available to select developers approved by business units.

This method creates an eBay guest checkout session, which is the first step in performing a checkout. The method returns a checkoutSessionId that you use as a URI parameter in subsequent guest checkout methods.

Also see Negative Testing Using Stubs for information on how to emulate error conditions for this method using stubs.

TIP: To test the entire checkout flow, you might need a "test" credit card. You can generate a credit card number from http://www.getcreditcardnumbers.com.

For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.

The URLs for this method are:

Authorizations:
Client_Credentials
header Parameters
X-EBAY-C-ENDUSERCTX
string

A header that is used to specify the affiliateCampaignId, and optionally the affiliateReferenceId, to enable revenue sharing when the buyer purchases items.

TIP: See Request headers in the Buying Integration Guide for more information.

X-EBAY-C-MARKETPLACE-ID
required
string

A header that identifies the user's business context and is specified using a marketplace ID value.

Note: This header does not indicate a language preference or consumer location.

See Marketplace ID values for a list of supported values.

Request Body schema: application/json

The container for the fields used by the initiateGuestCheckoutSession method.

contactEmail
string

The buyer's email address.

Array of objects (LineItemInput)

An array used to define the line item(s) and desired quantity for an eBay guest checkout session.

Maximum: 10 line items

object (ShippingAddress)

A type that defines the fields for a shipping address. For restrictions, see Shipping restrictions.

Note: If the address cannot be validated, a warning message will be returned.

Responses

Request samples

Content type
application/json
{
  • "contactEmail": "string",
  • "lineItemInputs": [
    ],
  • "shippingAddress": {
    }
}

removeGuestCoupon

Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.

Limited Release(Limited Release) This method is only available to select developers approved by business units.

This method removes a coupon from an eBay guest checkout session. The checkoutSessionId is passed in as a URI parameter and is required. The redemption code of the coupon is specified in the payload and is also required.

For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.

The URLs for this method are:

Authorizations:
Client_Credentials
path Parameters
checkoutSessionId
required
string

The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the initiateGuestCheckoutSession method.

Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details.

header Parameters
X-EBAY-C-MARKETPLACE-ID
required
string

A header that identifies the user's business context and is specified using a marketplace ID value.

Note: This header does not indicate a language preference or consumer location.

See Marketplace ID values for a list of supported values.

Request Body schema: application/json

The container for the fields used by the removeGuestCoupon method.

redemptionCode
string

The redemption code of the coupon.

Maximum: One redemption code per order

Responses

Request samples

Content type
application/json
{
  • "redemptionCode": "string"
}

updateGuestQuantity

Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.

Limited Release(Limited Release) This method is only available to select developers approved by business units.

This method changes the quantity of the specified line item in an eBay guest checkout session.

For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.

The URLs for this method are:

Authorizations:
Client_Credentials
path Parameters
checkoutSessionId
required
string

The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the initiateGuestCheckoutSession method.

Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details.

header Parameters
X-EBAY-C-MARKETPLACE-ID
required
string

A header that identifies the user's business context and is specified using a marketplace ID value.

Note: This header does not indicate a language preference or consumer location.

See Marketplace ID values for a list of supported values.

Request Body schema: application/json

The container for the fields used by the updateGuestQuantity method.

lineItemId
string

A unique eBay-assigned ID value that identifies a line item in a purchase order.

quantity
integer

The number of individual items ordered in this line item, as specified by the buyer.

Responses

Request samples

Content type
application/json
{
  • "lineItemId": "string",
  • "quantity": 0
}

updateGuestShippingAddress

Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.

Limited Release(Limited Release) This method is only available to select developers approved by business units.

This method changes the shipping address for the order in an eBay guest checkout session. All the line items in an order must be shipped to the same address, but the shipping method can be specific to the line item.

Note: If the address submitted cannot be validated, a warning message will be returned. This does not prevent the method from executing, but you may want to verify the address.

For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.

The URLs for this method are:

Authorizations:
Client_Credentials
path Parameters
checkoutSessionId
required
string

The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the initiateGuestCheckoutSession method.

Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details.

header Parameters
X-EBAY-C-MARKETPLACE-ID
required
string

A header that identifies the user's business context and is specified using a marketplace ID value.

Note: This header does not indicate a language preference or consumer location.

See Marketplace ID values for a list of supported values.

Request Body schema: application/json

The container for the fields used by the updateGuestShippingAddress method.

addressLine1
string

The first line of the street address where the item is being shipped.

Maximum:

  • 40 characters for AU, CA, and US marketplaces
  • 35 characters for DE and GB marketplaces
  • 50 characters for all other marketplaces

addressLine2
string

The second line of the street address where the item is being shipped. This optional field can be used for information such as 'Suite Number' or 'Apt Number'.

Maximum:

  • 40 characters for AU, CA, and US marketplaces
  • 35 characters for DE and GB marketplaces
  • 50 characters for all other marketplaces

city
string

The city of the address where the item is being shipped.

country
string

The two letter code representing the country of the address. For implementation help, refer to eBay API documentation

county
string

The county of the address where the item is being shipped.

phoneNumber
string

The phone number of the person receiving the package.

Note: It is highly recommended that when entering the phone number you include the country code.

For example, if a US phone number is 44, you would enter +144. If you do not include this code, the service will use the country specified in the country field.

You can find the country code at https://countrycode.org.

postalCode
string

The postal code of the address where the item is being shipped.

Note: This is optional when shipping to EBAY_HK (Hong Kong).

object (Recipient)

A container that defines the full name of the person receiving the purchase order.

stateOrProvince
string

The state or province of the address.

Note: For the US marketplace, this is a two-character value. For a list of valid values, see US State and Canada Province Codes.

Responses

Request samples

Content type
application/json
{
  • "addressLine1": "string",
  • "addressLine2": "string",
  • "city": "string",
  • "country": "string",
  • "county": "string",
  • "phoneNumber": "string",
  • "postalCode": "string",
  • "recipient": {
    },
  • "stateOrProvince": "string"
}

updateGuestShippingOption

Note: The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the v1_beta version of the Order API.

Limited Release(Limited Release) This method is only available to select developers approved by business units.

This method changes the shipping method for the specified line item in an eBay guest checkout session. The shipping option can be set for each line item. This gives the shopper the ability choose the cost of shipping for each line item.

For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.

The URLs for this method are:

Authorizations:
Client_Credentials
path Parameters
checkoutSessionId
required
string

The eBay-assigned session ID, for a specific eBay marketplace, that is returned by the initiateGuestCheckoutSession method.

Note: When using this ID, the X-EBAY-C-MARKETPLACE-ID value and developer App ID must be the same as that used when this guest checkout session was created. See Checkout session restrictions in the Buy Integration Guide for details.

header Parameters
X-EBAY-C-MARKETPLACE-ID
required
string

A header that identifies the user's business context and is specified using a marketplace ID value.

Note: This header does not indicate a language preference or consumer location.

See Marketplace ID values for a list of supported values.

Request Body schema: application/json

The container for the fields used by the updateGuestShippingOption method.

lineItemId
string

A unique eBay-assigned ID value that identifies the line item in a checkout session.

shippingOptionId
string

A unique ID for the selected shipping option/method.

Responses

Request samples

Content type
application/json
{
  • "lineItemId": "string",
  • "shippingOptionId": "string"
}