eBay Order API
The eBay Order API enables buyer-side checkout and order management workflows, including guest checkout sessions and order retrieval.
OpenAPI Specification
openapi: 3.0.0
info:
title: eBay Order API
description: <span class="tablenote"><b>Note:</b> The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the <a href="/api-docs/buy/order_v1/resources/methods">v1_beta version</a> of the Order API.</span><br><br><span class="tablenote"><b>Note:</b> This is a <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited" target="_blank"><img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" alt="Limited Release" title="Limited Release" />(Limited Release)</a> API available only to select developers approved by business units.</span><br><br>The Order API provides interfaces that let shoppers pay for items. It also returns payment and shipping status of the order.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v2.1.2
servers:
- url: https://apix.ebay.com{basePath}
description: Production
variables:
basePath:
default: /buy/order/v2
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /buy/order/v2
paths:
/guest_checkout_session/{checkoutSessionId}/apply_coupon:
post:
tags:
- Guest_checkout_session
description: '<span class="tablenote"><b>Note:</b> The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the <a href="/api-docs/buy/order_v1/resources/methods">v1_beta version</a> of the Order API.</span><br><div class="msgbox_important"><p class="msgbox_importantInDiv" data-mc-autonum="<b><span style="color: #dd1e31;" class="mcFormatColor">Important! </span></b>"><span class="autonumber"><span><b><span style="color: #dd1e31;" class="mcFormatColor">Important!</span></b></span></span> <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited" target="_blank"><img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" alt="Limited Release" title="Limited Release" />(Limited Release)</a> This method is only available to select developers approved by business units.</p></div><br>This method adds a coupon to an eBay guest checkout session and applies it to all the eligible items in the order.<br><br>The <b>checkoutSessionId</b> is passed in as a URI parameter and is required. The redemption code of the coupon is in the payload and is also required.<br><br>For a list of supported sites and other restrictions, see <a href="/api-docs/buy/order/overview.html#API">API Restrictions</a> in the Order API overview.'
operationId: applyGuestCoupon
parameters:
- name: checkoutSessionId
in: path
description: This path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace.<br><br>This value is returned by the <a href="/api-docs/buy/order/resources/guest_checkout_session/methods/initiateGuestCheckoutSession" target="_blank ">initiateGuestCheckoutSession</a> method.<br><br><span class="tablenote"><b>Note:</b> 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 <a href="/api-docs/buy/order/overview.html#checkout-restriction">Checkout session restrictions</a> in the Buy Integration Guide for details.</span>
required: true
schema:
type: string
- name: X-EBAY-C-MARKETPLACE-ID
in: header
description: This header identifies the eBay marketplace where the order will occur. <br><br><span class="tablenote"><b>Note:</b> For this method, this value must match the <b>X-EBAY-C-MARKETPLACE-ID</b> used when the associated checkout session was created.</span><br>See <a href="/api-docs/static/rest-request-components.html#marketpl " target="_blank ">HTTP request headers</a> for the marketplace ID values.
required: true
schema:
type: string
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
- name: X-EBAY-C-ENDUSERCTX
in: header
description: This header is used to specify the <b>deviceId</b> for the device/user attempting to make the call.<br><br>It contains an alphanumeric string that allows a payment gateway to track an API call attempt and confirm that it is a verified payment attempt by a device/user.
required: false
schema:
type: string
requestBody:
description: The container for the fields used to apply a coupon to a guest checkout session.
content:
application/json:
schema:
description: The container for the fields used to apply a coupon to a guest checkout session.
$ref: '#/components/schemas/CouponRequest'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GuestCheckoutSessionResponseV2'
'400':
description: Bad Request
x-response-codes:
errors:
'15001':
domain: API_ORDER
category: REQUEST
description: 'Missing field: {fieldName}. The indicated field is required for this request. Add the field and resubmit the call.'
'15002':
domain: API_ORDER
category: REQUEST
description: 'Invalid field: {fieldName}. The indicated field contains an invalid value. Correct the value and resubmit the call.'
'15003':
domain: API_ORDER
category: REQUEST
description: The checkout session requested does not exist.
'15025':
domain: API_ORDER
category: REQUEST
description: The App is not authorized to access this resource.
'15029':
domain: API_ORDER
category: REQUEST
description: The X-EBAY-C-MARKETPLACE-ID value {fieldValue} is invalid for this checkout session because it is different from the X-EBAY-C-MARKETPLACE-ID header value used to create the session. For all calls in this checkout session, you must use X-EBAY-C-MARKETPLACE-ID {supportedValues}.
'15032':
domain: API_ORDER
category: REQUEST
description: After using the 'initiateGuestPayment' call, you cannot make changes to the cart. If you need to change the cart, you must start over using the 'initiateGuestCheckoutSession' call.
'16002':
domain: API_ORDER
category: REQUEST
description: The coupon does not exist. The coupon was ignored and no discount was applied to this order.
'16003':
domain: API_ORDER
category: REQUEST
description: The coupon has expired. No discount was applied to this order.
'16004':
domain: API_ORDER
category: REQUEST
description: The coupon has not been activated. The coupon was ignored and no discount was applied to this order.
'16006':
domain: API_ORDER
category: REQUEST
description: The coupon code is invalid. The coupon was ignored and no discount was applied to this order.
'16022':
domain: API_ORDER
category: REQUEST
description: The coupon code is invalid. The coupon was ignored and no discount was applied to this order.
'16024':
domain: API_ORDER
category: REQUEST
description: The coupon provided could not be applied. You may proceed with this session or provide another coupon.
'403':
description: Access Forbidden
'404':
description: Resource Not Found
'409':
description: Conflict
x-response-codes:
errors:
'15019':
domain: API_ORDER
category: BUSINESS
description: To place an order, you must have at least one line item. Use the initiateCheckoutSession call to add line items (maximum of {maxLineItems}) and create a new checkout session.
'15021':
domain: API_ORDER
category: BUSINESS
description: This checkout session cannot be updated because the order has already been placed.
'15027':
domain: API_ORDER
category: BUSINESS
description: 'The value {fieldValue} is not supported for the {fieldName}. The supported values are: {supportedValues}.'
'16000':
domain: API_ORDER
category: BUSINESS
description: The coupon is not valid for any of the items in the order. The coupon was ignored and no discount was applied to this order.
'16001':
domain: API_ORDER
category: BUSINESS
description: You cannot apply multiple coupons to the same order. No discount was applied to this order.
'16005':
domain: API_ORDER
category: BUSINESS
description: The coupon requires the buyer to spend a specific monetary amount. This threshold has not been met. The coupon was ignored and no discount was applied to this order.
'16007':
domain: API_ORDER
category: BUSINESS
description: This coupon has already been used. The coupon was ignored and no discount was applied to this order.
'16008':
domain: API_ORDER
category: BUSINESS
description: This coupon is no longer valid. The coupon was ignored and no discount was applied to this order.
'16009':
domain: API_ORDER
category: BUSINESS
description: The coupon requires the buyer to spend a specific monetary amount. This threshold has not been met. The coupon was ignored and no discount was applied to this order.
'16010':
domain: API_ORDER
category: BUSINESS
description: The coupon is not valid for the currency being used by the items. The coupon was ignored and no discount was applied to this order.
'16012':
domain: API_ORDER
category: BUSINESS
description: The coupon is not valid for the {fieldName}. The coupon was ignored and no discount was applied to this order.
'16013':
domain: API_ORDER
category: BUSINESS
description: The coupon is not valid for any of the item categories in the order. The coupon was ignored and no discount was applied to this order.
'16014':
domain: API_ORDER
category: BUSINESS
description: The coupon is not valid for the selected payment method. The coupon was ignored and no discount was applied to this order.
'16015':
domain: API_ORDER
category: BUSINESS
description: The coupon is not valid for the selected shipping option. The coupon was ignored and no discount was applied to this order.
'16016':
domain: API_ORDER
category: BUSINESS
description: The coupon is valid only for items that are shipped domestically. The coupon was ignored and no discount was applied to this order.
'16017':
domain: API_ORDER
category: BUSINESS
description: The coupon is valid only for items that are shipped internationally. The coupon was ignored and no discount was applied to this order.
'16018':
domain: API_ORDER
category: BUSINESS
description: The buyer is not eligible for this coupon. The coupon was ignored and no discount was applied to this order.
'16019':
domain: API_ORDER
category: BUSINESS
description: The coupon is not valid for guest eBay checkouts. The coupon was ignored and no discount was applied to this order.
'16023':
domain: API_ORDER
category: BUSINESS
description: You cannot apply multiple coupons to the same order. The coupon was ignored and no discount was applied to this order.
'500':
description: Internal Server Error
x-response-codes:
errors:
'15000':
domain: API_ORDER
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
'16020':
domain: API_ORDER
category: APPLICATION
description: Your application is not eligible for this coupon. The coupon was ignored and no discount was applied to this order.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/buy.guest.order
/guest_checkout_session/{checkoutSessionId}:
get:
tags:
- Guest_checkout_session
description: '<span class="tablenote"><b>Note:</b> The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the <a href="/api-docs/buy/order_v1/resources/methods">v1_beta version</a> of the Order API.</span><br><div class="msgbox_important"><p class="msgbox_importantInDiv" data-mc-autonum="<b><span style="color: #dd1e31;" class="mcFormatColor">Important! </span></b>"><span class="autonumber"><span><b><span style="color: #dd1e31;" class="mcFormatColor">Important!</span></b></span></span> <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited" target="_blank"><img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" alt="Limited Release" title="Limited Release" />(Limited Release)</a> This method is only available to select developers approved by business units.</p></div><br>This method returns the details of the specified guest checkout session. The <b>checkoutSessionId</b> is passed in as a URI parameter and is required. This method has no request payload.<br><br>For a list of supported sites and other restrictions, see <a href="/api-docs/buy/order/overview.html#API">API Restrictions</a> in the Order API overview.'
operationId: getGuestCheckoutSession
parameters:
- name: checkoutSessionId
in: path
description: This path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace.<br><br>This value is returned by the <a href="/api-docs/buy/order/resources/guest_checkout_session/methods/initiateGuestCheckoutSession" target="_blank ">initiateGuestCheckoutSession</a> method.<br><br><span class="tablenote"><b>Note:</b> 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 <a href="/api-docs/buy/order/overview.html#checkout-restriction">Checkout session restrictions</a> in the Buy Integration Guide for details.</span>
required: true
schema:
type: string
- name: X-EBAY-C-MARKETPLACE-ID
in: header
description: This header identifies the eBay marketplace where the order will occur. <br><br><span class="tablenote"><b>Note:</b> For this method, this value must match the <b>X-EBAY-C-MARKETPLACE-ID</b> used when the associated checkout session was created.</span><br>See <a href="/api-docs/static/rest-request-components.html#marketpl " target="_blank ">HTTP request headers</a> for the marketplace ID values.
required: true
schema:
type: string
- name: X-EBAY-C-ENDUSERCTX
in: header
description: This header is used to specify the <b>deviceId</b> for the device/user attempting to make the call.<br><br>It contains an alphanumeric string that allows a payment gateway to track an API call attempt and confirm that it is a verified payment attempt by a device/user.
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/GuestCheckoutSessionResponseV2'
x-response-codes:
errors:
'20000':
domain: API_ORDER
category: BUSINESS
description: This order contains the item {itemId} that may be subject to certain importation permitting/licensing requirements. Please check applicable regulations for specific import restrictions in your country.
'20001':
domain: API_ORDER
category: BUSINESS
description: This item {itemId} ships via a freight carrier. For information regarding shipping, tracking, delivery, etc. check with the seller.
'400':
description: Bad Request
x-response-codes:
errors:
'15003':
domain: API_ORDER
category: REQUEST
description: The checkout session requested does not exist.
'15025':
domain: API_ORDER
category: REQUEST
description: The App is not authorized to access this resource.
'15029':
domain: API_ORDER
category: REQUEST
description: The X-EBAY-C-MARKETPLACE-ID value {fieldValue} is invalid for this checkout session because it is different from the X-EBAY-C-MARKETPLACE-ID header value used to create the session. For all calls in this checkout session, you must use X-EBAY-C-MARKETPLACE-ID {supportedValues}.
'403':
description: Access Forbidden
'404':
description: Resource Not Found
'409':
description: Conflict
x-response-codes:
errors:
'15027':
domain: API_ORDER
category: BUSINESS
description: 'The value {fieldValue} is not supported for the {fieldName}. The supported values are: {supportedValues}.'
'500':
description: Internal Server Error
x-response-codes:
errors:
'15000':
domain: API_ORDER
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/buy.guest.order
/guest_checkout_session/initiate:
post:
tags:
- Guest_checkout_session
description: '<span class="tablenote"><b>Note:</b> The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the <a href="/api-docs/buy/order_v1/resources/methods">v1_beta version</a> of the Order API.</span><br><div class="msgbox_important"><p class="msgbox_importantInDiv" data-mc-autonum="<b><span style="color: #dd1e31;" class="mcFormatColor">Important! </span></b>"><span class="autonumber"><span><b><span style="color: #dd1e31;" class="mcFormatColor">Important!</span></b></span></span> <a href="https://developer.ebay.com/api-docs/static/versioning.html#limited" target="_blank"><img src="/cms/img/docs/partners-api.svg" class="legend-icon partners-icon" alt="Limited Release" title="Limited Release" />(Limited Release)</a> This method is only available to select developers approved by business units.</p></div><br>This method creates an eBay guest checkout session, which is the first step in performing a checkout. The method returns a <b>checkoutSessionId</b> that you use as a URI parameter in subsequent guest checkout methods. <br><br><span class="tablenote"><b>Note:</b> This method also returns the <b>X-EBAY-SECURITY-SIGNATURE</b> response header, which is a token that is used to launch the Checkout with eBay widget. The Checkout with eBay widget allows eBay guests to pay for items without leaving your site. For details about the Checkout with eBay widget, see <a href="/api-docs/buy/static/api-order.html#Integrat">Integrating the Checkout with eBay button</a>. </span><br>Also see <a href="/api-docs/buy/static/ref-buy-negative-testing.html">Negative Testing Using Stubs</a> for information on how to emulate error conditions for this method using stubs.<br><br><span class="tablenote"><font color="006600"><b>TIP:</b></font> To test the entire checkout flow, you might need a "test" credit card. You can generate a credit card number from <a href="http://www.getcreditcardnumbers.com" target="_blank">http://www.getcreditcardnumbers.com</a>.</span><br>For a list of supported sites and other restrictions, see <a href="/api-docs/buy/order/overview.html#API">API Restrictions</a> in the Order API overview.'
operationId: initiateGuestCheckoutSession
parameters:
- name: X-EBAY-C-ENDUSERCTX
in: header
description: This header is used to specify the <b>deviceId</b> for the device/user attempting to make the call.<br><br>It contains an alphanumeric string that allows a payment gateway to track an API call attempt and confirm that it is a verified payment attempt by a device/user.
required: false
schema:
type: string
- name: X-EBAY-C-MARKETPLACE-ID
in: header
description: This header identifies the eBay marketplace where the order will occur.<br><br>See <a href="/api-docs/static/rest-request-components.html#marketpl " target="_blank ">HTTP request headers</a> for the marketplace ID values.
required: true
schema:
type: string
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: The container for the fields used by the <b>initiateGuestCheckoutSession</b> method.
content:
application/json:
schema:
description: The container for the fields used by the <b>initiateGuestCheckoutSession</b> method.
$ref: '#/components/schemas/CreateGuestCheckoutSessionRequestV2'
required: false
responses:
'200':
description: OK
headers:
X-EBAY-SECURITY-SIGNATURE:
schema:
type: string
description: A token that is used to launch the Checkout with eBay widget. For details about the Checkout with eBay widget, see <a href="/api-docs/buy/static/api-order.html#Integrat">Integrating the Checkout with eBay button</a>
content:
application/json:
schema:
$ref: '#/components/schemas/GuestCheckoutSessionResponseV2'
x-response-codes:
errors:
'15007':
domain: API_ORDER
category: REQUEST
description: The address provided may be incorrect. You may proceed with this address or provide a correct address.
'15043':
domain: API_ORDER
category: BUSINESS
description: The item {itemId} cannot be purchased using this API and has been removed from the cart. The purchase can be done on ebay.com.
'15055':
domain: API_ORDER
category: BUSINESS
description: The item is removed due to one or more reasons (out of stock, the desired quantity exceeds the quantity available, etc).
'20000':
domain: API_ORDER
category: BUSINESS
description: This order contains the item {itemId} that may be subject to certain importation permitting/licensing requirements. Please check applicable regulations for specific import restrictions in your country.
'20001':
domain: API_ORDER
category: BUSINESS
description: This item {itemId} ships via a freight carrier. For information regarding shipping, tracking, delivery, etc. check with the seller.
'400':
description: Bad Request
x-response-codes:
errors:
'15001':
domain: API_ORDER
category: REQUEST
description: 'Missing field: {fieldName}. The indicated field is required for this request. Add the field and resubmit the call.'
'15002':
domain: API_ORDER
category: REQUEST
description: 'Invalid field: {fieldName}. The indicated field contains an invalid value. Correct the value and resubmit the call.'
'15029':
domain: API_ORDER
category: REQUEST
description: The X-EBAY-C-MARKETPLACE-ID value {fieldValue} is invalid for this checkout session because it is different from the X-EBAY-C-MARKETPLACE-ID header value used to create the session. For all calls in this checkout session, you must use X-EBAY-C-MARKETPLACE-ID {supportedValues}.
'15048':
domain: API_ORDER
category: REQUEST
description: The value of {fieldName} is too long. For more information, see the documentation for this call.
'17002':
domain: API_ORDER
category: REQUEST
description: Invalid character(s) found in the shipping address. Please check name and shipping address fields, remove invalid character(s) and resubmit the call.
'409':
description: Conflict
x-response-codes:
errors:
'15011':
domain: API_ORDER
category: BUSINESS
description: You have exceeded the maximum number of {maxLineItems} line items. Correct the request and resubmit the call.
'15012':
domain: API_ORDER
category: BUSINESS
description: There is a limit on the quantity of this item that can be purchased. Reduce the quantity and resubmit the call.
'15013':
domain: API_ORDER
category: BUSINESS
description: The item is either out of stock, or the desired quantity exceeds the quantity available. If out of stock, please wait for seller to restock. If desired quantity exceeds available quantity, please reduce the quantity value and try again.
'15014':
domain: API_ORDER
category: BUSINESS
description: The quantity submitted for this item is invalid. Correct the quantity value and resubmit the call.
'15015':
domain: API_ORDER
category: BUSINESS
description: There is a problem with the credit card and it cannot be used to purchase items. Use the updatePaymentInfo call to change the payment information.
'15017':
domain: API_ORDER
category: BUSINESS
description: The payment for the order line items in your cart could not be processed due to issues with one or more sellers.
'15018':
domain: API_ORDER
category: BUSINESS
description: The item is not available for purchase. This can be for several reasons including the listing has ended. Remove the item and resubmit the call.
'15019':
domain: API_ORDER
category: BUSINESS
description: To place an order, you must have at least one line item. Use the initiateCheckoutSession call to add line items (maximum of {maxLineItems}) and create a new checkout session.
'15026':
domain: API_ORDER
category: BUSINESS
description: The item is not shippable to the specified shipping address.
'15027':
domain: API_ORDER
category: BUSINESS
description: 'The value {fieldValue} is not supported for the {fieldName}. The supported values are: {supportedValues}.'
'15028':
domain: API_ORDER
category: BUSINESS
description: The item {itemId} is not available for purchase because it cannot be shipped to {country}.
'15031':
domain: API_ORDER
category: BUSINESS
description: The item is not purchasable because the buyer has been blocked by the seller.
'15044':
domain: API_ORDER
category: BUSINESS
description: At least one of the items in the cart cannot be purchased using this API. The purchase can be done on eBay, through the eBay app or eBay website.
'15045':
domain: API_ORDER
category: BUSINESS
description: The item cannot be purchased because the seller is away and is not processing orders. If you are trying to purchase more than one item, you need to create a new checkout session to purchase the other items.
'15047':
domain: API_ORDER
category: BUSINESS
description: In compliance with applicable economic sanctions and trade restrictions, eBay is unavailable in your location. If you believe you are receiving this notice in error, please contact eBay's Customer Service.
'15053':
domain: API_ORDER
category: BUSINESS
description: Your desired item(s) are not available for purchase at this time. The unavailability of an item could be for any of several reasons, including the item being out of stock. Add available item(s) and resubmit the call.
'20002':
domain: API_ORDER
category: BUSINESS
description: This item {itemId} is currently unavailable to buy from the seller.
'500':
description: Internal Server Error
x-response-codes:
errors:
'15000':
domain: API_ORDER
category: APPLICATION
description: There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/buy.guest.order
/guest_checkout_session/{checkoutSessionId}/remove_coupon:
post:
tags:
- Guest_checkout_session
description: '<span class="tablenote"><b>Note:</b> The Order API (v2) currently only supports the guest payment/checkout flow. If you need to support member payment/checkout flow, use the <a href="/api-docs/buy/order_v1/resources/methods">v1_beta version</a> of the Order API.</span><br><div class="msgbox_important"><p class="msgbox_importantInDiv" data-mc-autonum="<b><span style="color: #dd1e31;" class="mcFormatColor">Important! </span></b>"><span class="autonumber"><span><b><span style="color: #dd1e31;" class="mcFormatColor">Important!</
# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ebay/refs/heads/main/openapi/ebay-order-openapi-original.yml