order APIv1_beta.27.0

placeGuestOrder

POST
/guest_checkout_session/{checkoutSessionId}/place_order

This method creates the purchase order, pays for the items, and terminates the specified guest checkout session. The checkoutSessionId is passed in as a URI parameter and is required.

To meet security requirements for payments, the URLs for this method are:

  • Production URL: https://apix.ebay.com/buy/order/v1
  • Sandbox URL: https://apix.sandbox.ebay.com/buy/order/v1

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

Request headers

This method requires specific request headers. For details see, HTTP request headers section.

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 initiateGuestCheckoutSession method.

Input

Resource URI (production)

POST https://apix.ebay.com/buy/order/v1/guest_checkout_session/{checkoutSessionId}/place_order

URI parameters

ParameterTypeDescription
checkoutSessionIdstringThe 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 what was used when this checkout session was created. See Checkout session restrictions in the Buy Integration Guide.

Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

This method also requires the following headers:

X-EBAY-C-ENDUSERCTX with the risk correlation ID. This ID is generated during the PayPal library integration.

For example:
   X-EBAY-C-ENDUSERCTX: deviceId=riskCorrelationId

Note: If you are an eBay Network Partner you must also include the affiliateCampaignId and optionally affiliateReferenceId in the X-EBAY-C-ENDUSERCTX header in order to be paid for selling eBay items. For details see, Request headers.

For example:
   X-EBAY-C-ENDUSERCTX: deviceId=riskCorrelationId,affiliateCampaignId=ePNCampaignId,affiliateReferenceId=referenceId

OAuth scope

This request requires an access token created with the client credentials 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.guest.order

See OAuth access tokens for more information.

Input container/fieldTypeDescription
marketingTermsarray of MarketingTermsThe container for the marketing channels, the types of messages the buyer can choose to receive and the field to indicate whether the buyer wants to receive marketing materials from eBay.

These fields are required for all marketplaces.

See Marketing Consent Notice for details.

Occurrence: Required

marketingTerms.marketingChannelsarray of MarketingChannelEnumAn enumeration value representing the available marketing channels.

Valid Values: EMAIL

Required: You must always pass in all the values, even if marketingTermsAccepted is set to false. See the Samples for an example.

Occurrence: Required

marketingTerms.marketingTermsAcceptedbooleanA boolean that indicates whether the buyer wants to receive marketing messages.

Occurrence: Required

marketingTerms.marketingTypesarray of MarketingTypeEnumAn enumeration value representing the available types of marketing messages.

Valid Values:
  • OFFER
  • PROMOTION
  • SURVEY
Required: You must always pass in all these values, even if marketingTermsAccepted is set to false. See the Samples for an example.

Occurrence: Required

Output

HTTP response headers

Output container/fieldTypeDescription
purchaseOrderHrefstringThe URI of the purchase order.

Occurrence: Conditional

purchaseOrderIdstringA 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.

Note: If there is a problem with the payment information, the purchase order ID will be returned and the PurchaseOrderPaymentStatusEnum field will return FAILED.

Occurrence: Conditional

purchaseOrderPaymentStatusPurchaseOrderPaymentStatusEnumAn enumeration value that indicates the payment status for the purchase order.

Occurrence: Conditional

warningsarray of ErrorDetailV3An array of warning messages.

Occurrence: Conditional

warnings.categorystringThis string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Always

warnings.domainstringThe name of the primary system where the error occurred. This is relevant for application errors.

Occurrence: Always

warnings.errorIdintegerA 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.inputRefIdsarray of stringAn array of reference IDs that identify the specific request elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.longMessagestringA detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

warnings.messagestringA description of the condition that caused the error or warning.

Occurrence: Always

warnings.outputRefIdsarray of stringAn array of reference IDs that identify the specific response elements most closely associated to the error or warning, if any.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3An 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.namestringThis is the name of input field that caused an issue with the method request.

Occurrence: Conditional

warnings.parameters.valuestringThis is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstringThe 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.

StatusMeaning
200OK
400Bad Request
403Access Forbidden
404Resource Not Found
409Conflict
500Internal Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
15000API_ORDERAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
15003API_ORDERREQUESTThe checkout session requested does not exist.
15004API_ORDERREQUESTIf this is a eBay member checkout, this error indicates that the buyer does not have a PayPal account linked to their eBay account. If this is a guest checkout, this indicates that the buyer's credit card information is missing. In both cases, submit the buyer's credit card information.
15012API_ORDERBUSINESSThere is a limit on the quantity of this item that can be purchased. Reduce the quantity and resubmit the call.
15019API_ORDERBUSINESSTo 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.
15020API_ORDERBUSINESSDuring the checkout process the item has been changed. Create a new checkout session for this item using the initiateCheckoutSession call.
15023API_ORDERBUSINESSThe 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.
15024API_ORDERBUSINESSThere is a problem with the buyer's payment method. Please check or provide another payment method for this order.
15025API_ORDERREQUESTThe App is not authorized to access this resource.
15027API_ORDERBUSINESSThe value {fieldValue} is not supported for the {fieldName}. The supported values are: {supportedValues}.
15029API_ORDERREQUESTThe 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}.
15030API_ORDERBUSINESSTo place the order, the user must have accepted the PayPal User Agreement and Privacy Policy. If they have explicitly accepted these, pass in true in the paymentTermsAccepted field. For more information, see the documentation for this call.
15033API_ORDERREQUESTThe payment cannot be processed because the payment information is invalid. You will need to create a new checkout session and submit corrected payment information.
15045API_ORDERBUSINESSThe 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.
15046API_ORDERREQUESTOne or more of the mandatory values is missing for marketingChannels and/or marketingTypes. For help, refer to the placeGuestOrder call documentation.
15049API_ORDERBUSINESSThere is some issue with this payment. Contact eBay developer support for assistance.
17000API_ORDERBUSINESSThe 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.

CodeDomainCategoryMeaning
15005API_ORDERBUSINESSSome of the line items were not purchased. Use the Order API getPurchaseOrder call to check the payment status of each line item.
15006API_ORDERBUSINESSThe 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 a guest checkout. Be sure to store this ID because it is passed as a URI parameter in the getGuestPurchaseOrder call.

Input

The input is the checkoutSessionId and the marketing consent fields based on what the buyer has indicated. For details see Marketing consent requirement.
POST
https://apix.ebay.com/buy/order/v1/guest_checkout_session/v1|5018578757|63iqkv_LQQy/place_order

Output

The output is the purchase order ID, the purchase order URL, and order payment status.