order APIv1_beta.28.0

getGuestPurchaseOrder

GET
/guest_purchase_order/{purchaseOrderId}

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, and discounts and credits.

The purchaseOrderId is passed in as a URI parameter and is required. This method has no request payload.

The placeGuestOrder or method initiates the payment process, which can sometimes take a few minutes. 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.

Restrictions

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

Input

Resource URI (production)

GET https://api.ebay.com/buy/order/v1/guest_purchase_order/{purchaseOrderId}

URI parameters

ParameterTypeDescription
purchaseOrderIdstringThe unique identifier of a purchase order made by a guest buyer, for which details are to be retrieved. This value is returned by the placeGuestOrder method in the purchaseOrderId field.

The purchaseOrderId is passed in as a URI parameter and is required.

Occurrence: Required

HTTP request headers

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

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

https://api.ebay.com/oauth/api_scope/buy.proxy.guest.order

See OAuth access tokens for more information.

Output

HTTP response headers

{ /* GuestPurchaseOrder */
"lineItems" : [
{ /* OrderLineItem */
"image" :
{ /* Image */ },
"itemId" : "string",
}
],
}
Output container/fieldTypeDescription
appliedCouponsarray of CouponThe container that returns the information for the coupons that were applied in the order.

Occurrence: Conditional

appliedCoupons.redemptionCodestringThe redemption code of the coupon. Note: There can be only one redemption code per order.

Occurrence: Conditional

lineItemsarray of OrderLineItemAn array of the line items in the order.

Occurrence: Always

lineItems.authenticityVerificationAuthenticityVerificationProgramThis container 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.descriptionstringAn informational message that applies to the Authenticity Guarantee program.

Occurrence: Conditional

lineItems.authenticityVerification.outcomeReasonstringAn informational message regarding the authentication outcome of an authenticity verification inspection.
Note: This field is conditionally returned when there is information that applies to the Authenticity Guarantee program.

Occurrence: Conditional

lineItems.authenticityVerification.statusAuthenticityVerificationStatusEnumThe value in this field indicates whether the order line item has passed or failed the authenticity verification inspection, or if the inspection and/or results are still pending. The possible values returned here are PENDING, PASSED, FAILED, or INELIGIBLE.
Note: This field is conditionally returned when purchase is complete.

Occurrence: Conditional

lineItems.authenticityVerification.termsWebUrlstringThe terms and conditions that apply to the Authenticity Guarantee program.

Occurrence: Conditional

lineItems.baseUnitPriceAmountThe cost of a single item in this line item.

Occurrence: Always

lineItems.baseUnitPrice.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

lineItems.baseUnitPrice.valuestringThe monetary amount.

Occurrence: Always

lineItems.feesarray of FeeA breakdown of the fees applicable to the line item.

Occurrence: Conditional

lineItems.fees.amountAmountA container for the currency type and monetary amount of the fees associated with the line item.

Occurrence: Conditional

lineItems.fees.amount.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

lineItems.fees.amount.valuestringThe monetary amount.

Occurrence: Always

lineItems.fees.feeTypeFeeEnumThe type of fee associated with the line item.

Occurrence: Conditional

lineItems.imageImageThe URL of the item's image.

Occurrence: Always

lineItems.image.heightinteger Reserved for future use.

Occurrence: Conditional

lineItems.image.imageUrlstringThe URL of the image.

Occurrence: Conditional

lineItems.image.widthinteger Reserved for future use.

Occurrence: Conditional

lineItems.itemIdstringThe identifier of the item.

Occurrence: Always

lineItems.legacyReferenceLegacyReferenceThe 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.

Note: The Post Order API can be used only with eBay member checkouts.

Occurrence: Conditional

lineItems.legacyReference.legacyItemIdstringThe legacy ID used to identify an item.

This is used by the Post Order API Create Return Request method. This call initiates the item return process. For more information on how to use this field in the Post Order API, see Create a return request in the Buy Integration Guide.

Restriction: The Post Order API can be used only with eBay member checkouts.

Occurrence: Conditional

lineItems.legacyReference.legacyOrderIdstringThe legacy ID of the order.

This is used by the Post Order API Submit Cancellation Request method. This method initiates the item cancellation process. For more information on how to use this field in the Post Order API, see Using the Post Order API.

Restriction: The Post Order API can be used only with eBay member checkouts.

Occurrence: Conditional

lineItems.legacyReference.legacyTransactionIdstringThe legacy ID of the transaction.

This is used by the Post Order API Create Return Request call. This call initiates the item return process. For more information on how to use this field in the Post Order API, see Using the Post Order API in the Buy Integration Guide.

Restriction: The Post Order API can be used only with eBay member checkouts.

Occurrence: Conditional

lineItems.lineItemIdstringThe identifier of this line item. This is created by the initiateCheckoutSession for a member and initiateGuestCheckoutSession for a guest calls.

Occurrence: Conditional

lineItems.lineItemPaymentStatusLineItemPaymentStatusEnumAn enumeration value that indicates the payment status of this line item.

Occurrence: Always

lineItems.lineItemStatusLineItemStatusEnumAn enumeration value that indicates the fulfillment state of this line item.

Note: When there is no tracking information, this status will never change from FULFILLMENT_IN_PROGRESS because without tracking information eBay has no way of knowing if the order was delivered.

Occurrence: Conditional

lineItems.netPriceAmountThe total cost for the items in this line item taking into account the quantity and applying any seller item discounts, such as Buy 1 Get 1, and any coupon that applies to this item.

Note: This does not include any shipping discounts, shipping costs, or seller adjustments.

Occurrence: Conditional

lineItems.netPrice.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

lineItems.netPrice.valuestringThe monetary amount.

Occurrence: Always

lineItems.orderIdstringThe unique order ID for this line item. This value is the new eBay unique order ID. For details see, Easier order management with updated order numbers.

In the future, you will use this value in the Post Order API instead of the lineItems.legacyReference fields.

Maximum Length: 40 characters

Occurrence: Conditional

lineItems.promotionsarray of PromotionAn array of promotions applied to the items in this line item.

Occurrence: Conditional

lineItems.promotions.discountAmountThe discount amount on the applied promotional offer.

Occurrence: Conditional

lineItems.promotions.discount.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

lineItems.promotions.discount.valuestringThe monetary amount.

Occurrence: Always

lineItems.promotions.discountPercentagestringNote: This field is not return in the purchase order methods response.

Occurrence: Conditional

lineItems.promotions.messagestringThe text for the promotion title, which describes the promotion. For example, Buy 1 Get 1.

Occurrence: Conditional

lineItems.promotions.promotionCodestringAn identifier of the promotion that was generated by the system when the promotion was created.

Occurrence: Conditional

lineItems.promotions.promotionTypestringIndicates the kind of promotion. Some examples are: SellerDiscountedPromotionalOffer and COUPON.

Occurrence: Conditional

lineItems.quantityintegerThe number of individual items in this line item.

Occurrence: Always

lineItems.sellerSellerThe container for information about the seller offering this item, such as the seller's user name.

Occurrence: Always

lineItems.seller.feedbackPercentagestringThe percentage of the total positive feedback.

Occurrence: Always

lineItems.seller.feedbackScoreintegerThe feedback score of the seller. This value is based on the ratings from eBay members that bought items from this seller.

Occurrence: Always

lineItems.seller.sellerAccountTypestringIndicates if the seller is a business or an individual. This is determined when the seller registers with eBay. If they register for a business account, this value will be BUSINESS. If they register for a private account, this value will be INDIVIDUAL. This designation is required by the tax laws in some countries.

This field is returned only on the following sites.

EBAY_AT, EBAY_BE, EBAY_CH, EBAY_DE, EBAY_ES, EBAY_FR, EBAY_GB, EBAY_IE, EBAY_IT, EBAY_PL

Valid values:
  • BUSINESS
  • INDIVIDUAL
Code so that your app gracefully handles any future changes to this list.

Occurrence: Conditional

lineItems.seller.usernamestringThe user name created by the seller for use on eBay.

Occurrence: Conditional

lineItems.shippingDetailShippingDetailInformation about the shipping provider used for this line item.

Occurrence: Conditional

lineItems.shippingDetail.maxEstimatedDeliveryDatestringThe 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.minEstimatedDeliveryDatestringThe 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.shippingCarrierCodestringThe shipping provider, such as FedEx, or USPS for the line item.

Occurrence: Conditional

lineItems.shippingDetail.shippingServiceCodestringA name of a shipping type. For example, Priority Mail Express (provided by USPS) or FedEx International Priority (Provided by FedEx).

Occurrence: Conditional

lineItems.titlestringThe seller created title of the item.

Occurrence: Conditional

pricingSummaryPricingSummaryThe container that returns the monetary details of the order.

Occurrence: Always

pricingSummary.additionalSavingsAmountThe total amount of the coupon discounts in the purchase order.

Occurrence: Conditional

pricingSummary.additionalSavings.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.additionalSavings.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.adjustmentAdjustmentThe total amount of any seller adjustments. An adjustment can be a credit or debit. This is used to catch any monetary changes to the purchase order that are not already captured in one of the other fields.

Occurrence: Conditional

pricingSummary.adjustment.amountAmountThe container for the amount and currency of the adjustment.

Occurrence: Conditional

pricingSummary.adjustment.amount.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.adjustment.amount.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.adjustment.labelstringText that describes the adjustment.

Occurrence: Conditional

pricingSummary.deliveryCostAmountThe shipping cost for all the line items before any shipping discounts are applied.

Let's say there were 4 line items and the shipping cost for each line item is $5. One of the line items qualifies for free shipping. The deliveryCost value would be $20, which is the total cost for shipping all the line items before any discounts were appiled.

Occurrence: Conditional

pricingSummary.deliveryCost.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.deliveryCost.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.deliveryDiscountAmountThe total amount of the order shipping discounts for the all line items, such as free shipping.

Let's say there were 4 line items and the shipping cost for each line items is $5. One of the line items qualifies for free shipping. The deliveryDiscounts value would be 5, which is the value of the free shipping discount.

Note: This will always be a negative number.

Occurrence: Conditional

pricingSummary.deliveryDiscount.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.deliveryDiscount.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.feeAmountThe total amount of any fees for all the line items, such as a recycling fee.

Occurrence: Conditional

pricingSummary.fee.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.fee.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.importChargesAmountThe sum of the Global Shipping Program import charges for all line items.

Occurrence: Conditional

pricingSummary.importCharges.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.importCharges.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.importTaxImportTaxThis container provides 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.amountAmountThe total amount of import tax for all line items of an order.

Occurrence: Conditional

pricingSummary.importTax.amount.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.importTax.amount.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.importTax.importTaxTypeImportTaxTypeEnumThis enumeration value indicates the type of import tax applicable to the order. Currently, the only applicable import tax is 'Goods and Services' tax (indicated with GST). 'Goods and Services' tax is only applicable to orders on the eBay Australia marketplace.

Occurrence: Conditional

pricingSummary.priceDiscountAmountThe total amount of all the item discounts for all line items, such as Buy 1 Get 1 free.

Let's say there were 4 line items. One of the line items qualifies for free shipping, which is $5 and two items qualify for a Buy 1 Get 1 offer, which is a $6 and a $15 discount. The priceDiscount value would be 21, which is the total of the two Buy 1 Get 1 discounts. The shipping discount is not included. It is returned in the deliveryDiscount field.

Note: This will always be a negative number.

Occurrence: Conditional

pricingSummary.priceDiscount.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.priceDiscount.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.priceSubtotalAmountThe total amount for all the line items taking into account the item quantity but before adding in taxes and shipping costs, or applying discounts, fees, and adjustments.

Occurrence: Conditional

pricingSummary.priceSubtotal.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.priceSubtotal.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.taxAmountThe total amount of the taxes for all the line items.

Occurrence: Conditional

pricingSummary.tax.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.tax.valuestringThe monetary amount.

Occurrence: Always

pricingSummary.totalAmountThe total of the purchase order.

total = priceSubtotal + baseDeliveryCost + tax + importCharges + deliveryDiscounts + priceDiscount + adjustment.

Note: deliveryDiscounts and priceDiscount are negative numbers.

Occurrence: Conditional

pricingSummary.total.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

pricingSummary.total.valuestringThe monetary amount.

Occurrence: Always

purchaseOrderCreationDatestringThe creation date of the purchase order.

Occurrence: Always

purchaseOrderIdstringThe unique identifier of the purchase order. This value was returned in the purchaseOrderId field by the placeGuestOrder method.

Occurrence: Always

purchaseOrderPaymentStatusPurchaseOrderPaymentStatusEnumThe container for the status of the payment for the purchase order.

Occurrence: Always

purchaseOrderStatusPurchaseOrderStatusEnumAn enumeration value that indicates the current status of the buyer's payment and any refund that applies to the purchase order.

Occurrence: Always

refundedAmountAmountThe total amount of any refunds for the purchase order.

Occurrence: Conditional

refundedAmount.currencyCurrencyCodeEnumA three letter ISO 4217 code specifying the currency of the monetary amount.

Occurrence: Always

refundedAmount.valuestringThe monetary amount.

Occurrence: Always

warningsarray of ErrorDetailV3The container for any warning messages.

Occurrence: Conditional

warnings.categorystringIdentifies the type of error.

Occurrence: Always

warnings.domainstringName for the primary system where the error occurred. This is relevant for application errors.

Occurrence: Always

warnings.errorIdintegerA unique number to identify the error.

Occurrence: Always

warnings.inputRefIdsarray of stringAn array of request elements most closely associated to the error.

Occurrence: Conditional

warnings.longMessagestringA more detailed explanation of the error.

Occurrence: Conditional

warnings.messagestringInformation on how to correct the problem, in the end user's terms and language where applicable.

Occurrence: Always

warnings.outputRefIdsarray of stringAn array of request elements most closely associated to the error.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.

Occurrence: Conditional

warnings.parameters.namestringThe object of the error.

Occurrence: Conditional

warnings.parameters.valuestringThe value of the object.

Occurrence: Conditional

warnings.subdomainstringFurther helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.

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
403Access Forbidden
404Not Found
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
16001API_ORDERAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
16002API_ORDERREQUESTThe purchase order ID was not found.
16003API_ORDERREQUESTAccess to the purchase order is not authorized.

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, which is returned by the Checkout API placeOrder call. There is no payload with this request.
GET
https://api.ebay.com/buy/order/v1/guest_purchase_order/210000000557302

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