POST/checkout_session/{checkoutSessionId}/place_order
This method creates the purchase order, pays for the items, and terminates the specified eBay member checkout session. The checkoutSessionId is passed in as a URI parameter and is required. Although there is not a request payload, for this method you must pass in { } in the request body.
Also see Negative Testing Using Stubs for information on how to emulate error conditions for this method using stubs.
Restrictions
For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
Note: If the credit card is declined, the checkout session is unusable. You will need to create a new checkout session for the order using the initiateCheckoutSession method.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the apix.ebay.com root URI with apix.sandbox.ebay.com
URI parameters
| Parameter | Type | Description |
|---|---|---|
| checkoutSessionId | string | This path parameter specifies the unique eBay-assigned session identifier for a specific eBay marketplace. This value 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. Occurrence: Required |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
| Header | Type | Description |
|---|---|---|
| X-EBAY-C-ENDUSERCTX | string | This header is used to specify the deviceId for the device/user attempting to make the call. 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. Occurrence: Conditional |
| X-EBAY-C-MARKETPLACE-ID | string | This header identifies the eBay marketplace where the order will occur. Note: For this method, this value must match the X-EBAY-C-MARKETPLACE-ID used when the associated checkout session was created. See HTTP request headers for the marketplace ID values. Occurrence: Required |
OAuth scope
This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/buy.order
eBayUser
See OAuth access tokens for more information.
Request payload
Note: Although there is not a request payload, for this method you must pass in { } in the request body.
This call has no payload.
Request fields
This call has no field definitions.
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
| Output container/field | Type | Description |
|---|---|---|
| purchaseOrderHref | string | The URI of the purchase order. Occurrence: Conditional |
| purchaseOrderId | string | A unique identifier of the purchase order. When a checkout session completes, a purchase order ID is generated but this does not indicate that the item has been paid for. Occurrence: Conditional |
| purchaseOrderPaymentStatus | PurchaseOrderPaymentStatusEnum | An enumeration value that indicates the payment status for the purchase order. Occurrence: Conditional |
| warnings | array of ErrorDetailV3 | An array of warning messages. Occurrence: Conditional |
| warnings.category | string | This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors. Occurrence: Always |
| warnings.domain | string | The name of the primary system where the error occurred. This is relevant for application errors. Occurrence: Always |
| warnings.errorId | integer | A unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. Occurrence: Always |
| warnings.inputRefIds | array of string | An array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any. Occurrence: Conditional |
| warnings.longMessage | string | A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem. Occurrence: Conditional |
| warnings.message | string | A description of the condition that caused the error or warning. Occurrence: Always |
| warnings.outputRefIds | array of string | An array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any. Occurrence: Conditional |
| warnings.parameters | array of ErrorParameterV3 | An array of warning and error messages that return one or more variables contextual information about the error or warning. This is often the field or value that triggered the error or warning. Occurrence: Conditional |
| warnings.parameters.name | string | This is the name of input field that caused an issue with the method request. Occurrence: Conditional |
| warnings.parameters.value | string | This is the actual value that was passed in for the element specified in the name field. Occurrence: Conditional |
| warnings.subdomain | string | The name of the subdomain in which the error or warning occurred. Occurrence: NA |
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
| Status | Meaning |
|---|---|
| 200 | OK |
| 400 | Bad Request |
| 403 | Access Forbidden |
| 404 | Resource Not Found |
| 409 | Conflict |
| 500 | Internal Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 15000 | API_ORDER | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
| 15003 | API_ORDER | REQUEST | The checkout session requested does not exist. |
| 15004 | API_ORDER | REQUEST | The buyer's credit card information is missing. Please submit the buyer's credit card information using updatePaymentInfo method. |
| 15012 | API_ORDER | BUSINESS | There is a limit on the quantity of this item that can be purchased. Reduce the quantity and resubmit the call. |
| 15019 | API_ORDER | BUSINESS | 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. |
| 15020 | API_ORDER | BUSINESS | During the checkout process the item has been changed. Create a new checkout session for this item using the initiateCheckoutSession call. |
| 15023 | API_ORDER | BUSINESS | The payment cannot be processed due to an issue with the funding source, such as insufficient funds, or invalid payment details, such as card number or billing address error. To complete this order, use the appropriate initiate checkout session call to create a new session and either provide a new payment method or correct the payment details. |
| 15024 | API_ORDER | BUSINESS | There is a problem with the buyer's payment method. Please check or provide another payment method for this order. |
| 15025 | API_ORDER | REQUEST | The App is not authorized to access this resource. |
| 15027 | API_ORDER | BUSINESS | The value {fieldValue} is not supported for the {fieldName}. The supported values are: {supportedValues}. |
| 15029 | API_ORDER | REQUEST | 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}. |
| 15045 | API_ORDER | BUSINESS | 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. |
| 17000 | API_ORDER | BUSINESS | The payment cannot be processed due to a payment processor issue, such as invalid incentive, funding or financing issue, etc |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 15005 | API_ORDER | BUSINESS | Some of the line items were not purchased. Use the Order API getPurchaseOrder call to check the payment status of each line item. |
| 15006 | API_ORDER | BUSINESS | The order has already been placed for the checkout session submitted and no modifications can be made. Use the Order API getPurchaseOrder call to get the purchase order details. |
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Place the Order
This call generates the purchase order ID and starts the process that pays for the line items for an eBay member checkout. Be sure to store this ID because it is passed as a URI parameter in the getPurchaseOrder call.
Input
The input is the checkoutSessionId.
Note: Although there is not a request payload, for this call you must pass in { } in the request body.
POSThttps://apix.ebay.com/buy/order/v1/checkout_session/1*************0/place_order
Output
The output is the purchase order ID, the purchase order URL, and order payment status.