GET/guest_purchase_order/{purchaseOrderId}
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) This method is only available to select developers approved by business units.
This method retrieves the details about a specific guest purchase order. It returns the line items, including purchase order status, dates created and modified, item quantity and listing data, payment and shipping information, and prices, taxes, discounts and credits.
The purchaseOrderId is passed in as a URI parameter and is required.
Note: The purchaseOrderId value is returned in the call-back URL that is sent through the new eBay pay widget. For more information about eBay managed payments and the new Order API payment flow, see Order API in the Buying Integration Guide.
You can use this method to not only get the details of a purchase order, but to check the value of the purchaseOrderPaymentStatus field to determine if the order has been paid for. If the order has been paid for, this field will return PAID.
For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com
URI parameters
| Parameter | Type | Description |
|---|---|---|
| purchaseOrderId | string | The unique identifier of a purchase order made by a guest buyer, for which details are to be retrieved. Note: This value is returned in the response URL that is sent through the new eBay pay widget. For more information about eBay managed payments and the new Order API payment flow, see Order API in the Buying 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.
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. 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: Conditional |
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.
Request payload
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 |
|---|---|---|
| lineItems | array of OrderLineItemV2 | An array of line items in the order. Occurrence: Always |
| lineItems.authenticityVerification | AuthenticityVerificationProgram | A container that is returned for orders that are eligible for eBay's Authenticity Guarantee program. The seller ships Authenticity Guarantee program items to the authentication partner instead of the buyer. If the item is successfully authenticated, the authenticator will ship the item to the buyer. Occurrence: Conditional |
| lineItems.authenticityVerification.description | string | An informational message that applies to the Authenticity Guarantee program. Occurrence: Conditional |
| lineItems.authenticityVerification.outcomeReason | string | An informational message regarding the authentication outcome of an Authenticity Guarantee verification inspection. Occurrence: Conditional |
| lineItems.authenticityVerification.status | AuthenticityVerificationStatusEnum | An enumerated value that indicates whether the order line item has passed or failed the Authenticity Guarantee verification inspection, or whether the inspection and/or results are still pending.
Occurrence: Conditional |
| lineItems.authenticityVerification.termsWebUrl | string | The terms and conditions that apply to the Authenticity Guarantee program. Occurrence: Conditional |
| lineItems.baseUnitPrice | Amount | The cost of a single quantity of the line item. Occurrence: Always |
| lineItems.baseUnitPrice.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| lineItems.baseUnitPrice.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| lineItems.fees | array of Fee | A breakdown of the fees applicable to the line item. Occurrence: Conditional |
| lineItems.fees.amount | Amount | A container for the currency type and monetary amount of the fee associated with the line item. Occurrence: Conditional |
| lineItems.fees.amount.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| lineItems.fees.amount.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| lineItems.fees.feeType | FeeEnum | The type of fee associated with the line item. Occurrence: Conditional |
| lineItems.image | Image | An eBay-assigned URL of the item image. Occurrence: Always |
| lineItems.image.imageUrl | string | The URL for the image. Occurrence: Always |
| lineItems.itemId | string | The eBay identifier of an item. This ID is returned by the Browse and Feed API methods. Occurrence: Always |
| lineItems.itemOnHold | boolean | When this value is Occurrence: Conditional |
| lineItems.legacyReference | LegacyReference | A container that returns fields to support using the Post Order API for returns and cancellations. For information about what is returned in these fields and how to use the Post Order API, see Using the Post Order API. Occurrence: Conditional |
| lineItems.legacyReference.legacyItemId | string | The legacy ID used to identify an item. Occurrence: Conditional |
| lineItems.legacyReference.legacyOrderId | string | The legacy ID of the order. Occurrence: Conditional |
| lineItems.legacyReference.legacyTransactionId | string | The legacy ID of the transaction. Occurrence: Conditional |
| lineItems.lineItemId | string | A unique eBay-assigned ID value that identifies a line item in a checkout session. This is created by the initiateGuestCheckoutSession. Occurrence: Always |
| lineItems.lineItemPaymentStatus | LineItemPaymentStatusEnum | An enumeration value that indicates the payment status of the line item. Occurrence: Always |
| lineItems.lineItemStatus | LineItemStatusEnum | An enumeration value that indicates the fulfillment state of this line item. Occurrence: Always |
| lineItems.netPrice | Amount | The total cost for the line item, taking into account the quantity, any seller item discounts, and any coupon that applies. Occurrence: Always |
| lineItems.netPrice.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| lineItems.netPrice.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| lineItems.orderId | string | The unique order ID for the line item. Occurrence: Conditional |
| lineItems.promotions | array of Promotion | An array of promotions applied to the line item. Occurrence: Conditional |
| lineItems.promotions.discount | Amount | The details regarding the monetary value of the promotional discount. Occurrence: Conditional |
| lineItems.promotions.discount.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| lineItems.promotions.discount.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| lineItems.promotions.message | string | The text for the promotion title, which describes the promotion. Occurrence: Conditional |
| lineItems.promotions.promotionType | string | The kind of promotion. Some examples are: Occurrence: Conditional |
| lineItems.quantity | integer | The quantity ordered for the line item. Occurrence: Always |
| lineItems.seller | Seller | A container for information about the seller offering this item, such as the seller's user name. Occurrence: Always |
| lineItems.seller.username | string | The user name created by the seller for use on eBay. Occurrence: Always |
| lineItems.shippingDetail | ShippingDetail | A container for information about the shipping details of the order. Occurrence: Conditional |
| lineItems.shippingDetail.maxEstimatedDeliveryDate | string | The end of the date range in which the purchase order is expected to be delivered to the shipping address (final destination). Occurrence: Conditional |
| lineItems.shippingDetail.minEstimatedDeliveryDate | string | The beginning of the date range in which the purchase order is expected to be delivered to the shipping address (final destination). Occurrence: Conditional |
| lineItems.shippingDetail.shippingCarrierCode | string | The shipping provider for the line item, such as FedEx or USPS. Occurrence: Conditional |
| lineItems.shippingDetail.shippingServiceCode | string | The name of the shipping service option. For example, Priority Mail Express (provided by USPS) or FedEx International Priority (Provided by FedEx). Occurrence: Conditional |
| lineItems.taxDetails | array of TaxDetail | A container for the tax information for the line item. Occurrence: Conditional |
| lineItems.taxDetails.includedInPrice | boolean | A field that indicates whether tax was applied for the cost of the item and its shipping. Occurrence: Conditional |
| lineItems.taxDetails.taxJurisdiction | TaxJurisdiction | A container that returns the tax jurisdiction information. Occurrence: Conditional |
| lineItems.taxDetails.taxJurisdiction.region | Region | The region of the tax jurisdiction. Occurrence: Conditional |
| lineItems.taxDetails.taxJurisdiction.region.regionName | string | A localized text string that indicates the name of the region. Taxes are generally charged at the state/province level, or at the country level in the case of VAT tax. Occurrence: Conditional |
| lineItems.taxDetails.taxJurisdiction.region.regionType | RegionTypeEnum | An enumeration value that indicates the type of region for the tax jurisdiction.
Occurrence: Conditional |
| lineItems.taxDetails.taxJurisdiction.taxJurisdictionId | string | The identifier of the tax jurisdiction. Occurrence: Conditional |
| lineItems.taxDetails.taxType | TaxType | A field that indicates the type of tax that may be collected for the item. Occurrence: Conditional |
| lineItems.title | string | The seller-created title of the item. Occurrence: Conditional |
| pricingSummary | PricingSummary | A container that breaks down the costs for the order, including total cost, shipping cost, tax, fees, and any discounts. Occurrence: Always |
| pricingSummary.additionalSavings | Amount | The total amount of the coupon discounts in the purchase order. Occurrence: Conditional |
| pricingSummary.additionalSavings.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.additionalSavings.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.adjustment | Adjustment | The total amount of any seller adjustments. An adjustment can be a credit or debit. This is used to catch any monetary changes to the order that are not already captured in one of the other fields. Occurrence: Always |
| pricingSummary.adjustment.amount | Amount | The container that returns the amount and currency of an adjustment. Occurrence: Always |
| pricingSummary.adjustment.amount.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.adjustment.amount.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.adjustment.label | string | The text indicating what the adjustment was for. Occurrence: Always |
| pricingSummary.deliveryCost | Amount | The delivery cost for all of the line items, after any delivery discounts are applied. Occurrence: Always |
| pricingSummary.deliveryCost.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.deliveryCost.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.deliveryDiscount | Amount | The total amount of the order delivery discounts for all of the line items, such as free shipping. Occurrence: Conditional |
| pricingSummary.deliveryDiscount.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.deliveryDiscount.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.fee | Amount | The total amount of any fees for all the line items in the order, such as a recycling fee. Occurrence: Always |
| pricingSummary.fee.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.fee.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.importCharges | Amount | The sum of all Global Shipping Program import charges, for all the line items in the order. Occurrence: Conditional |
| pricingSummary.importCharges.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.importCharges.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.importTax | ImportTax | The type of import tax applicable to the order, and the total amount of tax for all line items in the order. Occurrence: Conditional |
| pricingSummary.importTax.amount | Amount | The total amount of import tax for all line items of an order. Occurrence: Conditional |
| pricingSummary.importTax.amount.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.importTax.amount.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.importTax.importTaxType | ImportTaxTypeEnum | An enumeration value that indicates the type of import tax applicable to the order. Currently, the only applicable import tax is the Goods and Services tax (indicated with Occurrence: Conditional |
| pricingSummary.priceDiscount | Amount | The total discount amount for all line items in the order. Occurrence: Always |
| pricingSummary.priceDiscount.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.priceDiscount.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.priceSubtotal | Amount | The total cost for all line items in the order, taking into account the item quantity, but before adding taxes and delivery costs, or applying discounts, fees, and adjustments. Occurrence: Always |
| pricingSummary.priceSubtotal.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.priceSubtotal.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.tax | Amount | The total amount of taxes for all line items in the order. Occurrence: Always |
| pricingSummary.tax.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.tax.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.total | Amount | The total cost of the order, which includes: (priceSubtotal - priceDiscount) + deliveryCost + tax +/- adjustment + fee + importCharges - additionalSavings. Occurrence: Always |
| pricingSummary.total.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| pricingSummary.total.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| purchaseOrderCreationDate | string | The creation date of the purchase order. Occurrence: Always |
| purchaseOrderId | string | The unique identifier of the purchase order. Occurrence: Always |
| purchaseOrderPaymentStatus | PurchaseOrderPaymentStatusEnum | A container that returns the payment status for the purchase order. Occurrence: Always |
| purchaseOrderStatus | PurchaseOrderStatusEnum | An enumeration value that indicates the current status of the buyer's payment and any refund that applies to the purchase order. Occurrence: Always |
| refundedAmount | Amount | The total amount of any refunds for the purchase order. Occurrence: Conditional |
| refundedAmount.currency | CurrencyCodeEnum | The currency used in the monetary transaction. Generally, this is the currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| refundedAmount.value | string | The amount of the currency specified in the currency field. The value of the currency defaults to the standard currency used by the country of the eBay site offering the item. Occurrence: Conditional |
| warnings | array of ErrorDetailV3 | A container for any 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: Conditional |
| warnings.domain | string | The name of the primary system where the error occurred. This is relevant for application errors. Occurrence: Conditional |
| 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: Conditional |
| 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 what must be done to correct the problem. Occurrence: Conditional |
| warnings.message | string | A description of the condition that caused the error or warning. Occurrence: Conditional |
| 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 | The name of the input field that caused an issue with the method request. Occurrence: Conditional |
| warnings.parameters.value | string | 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 |
| 403 | Access Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 16001 | API_ORDER | APPLICATION | There was a problem with an eBay internal system or process. Contact eBay developer support for assistance. |
| 16002 | API_ORDER | REQUEST | The purchase order ID was not found. |
| 16003 | API_ORDER | REQUEST | Access to the purchase order is not authorized. |
Warnings
This call has no warnings.
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: Get the Details of a Guest Purchase Order
This sample returns the details for the specified guest purchase order.
Input
The input is the purchaseOrderId URI parameter. There is no payload with this request.
GEThttps://api.ebay.com/buy/order/v2/guest_purchase_order/2*************2
Output
The output shows that the specified purchase order contained one line item. The total cost of the item was 102.00 (pricingSummary.total) and the purchase order was paid for but as not been shipped ( purchaseOrderPaymentStatus = PAID and purchaseOrderStatus = PENDING).