order APIv2.0.0

getGuestPurchaseOrder

GET
/guest_purchase_order/{purchaseOrderId}
Note: This version of the Order API (v2) currently only supports the guest payment flow for eBay managed payments. To view the v1_beta version of the Order API, which includes both member and guest checkout payment flows, refer to the Order_v1 API documentation.

Limited Release(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.

The URLs for this method are:
  • Production URL: https://api.ebay.com/buy/order/v2/guest_purchase_order/{purchaseOrderId}
  • Sandbox URL: https://api.sandbox.ebay.com/buy/order/v2/guest_purchase_order/{purchaseOrderId}

Input

Resource URI (production)

GET https://api.ebay.com/buy/order/v2/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.

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.

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.

Output

HTTP response headers

{ /* GuestPurchaseOrderV2 */
"lineItems" : [
{ /* OrderLineItemV2 */
"image" :
{ /* Image */ },
"itemId" : "string",
"seller" :
{ /* Seller */ },
}
],
}
Output container/fieldTypeDescription
lineItemsarray of OrderLineItemV2An array of line items in the order.

Occurrence: Always

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

Occurrence: Conditional

lineItems.authenticityVerification.outcomeReasonstringAn informational message regarding the authentication outcome of an Authenticity Guarantee verification inspection.

Note: This field is conditionally returned when there is information that applies to the Authenticity Guarantee program.

Occurrence: Conditional

lineItems.authenticityVerification.statusAuthenticityVerificationStatusEnumAn 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.

Note: This field is conditionally returned when the purchase is complete.

Valid Values:
  • PENDING
  • PASSED
  • FAILED
  • INELIGIBLE

Occurrence: Conditional

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

Occurrence: Conditional

lineItems.baseUnitPriceAmountThe cost of a single quantity of the line item.

Note: The price includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB) to see VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Always

lineItems.baseUnitPrice.currencyCurrencyCodeEnumThe 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.valuestringThe 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.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 fee associated with the line item.

Occurrence: Conditional

lineItems.fees.amount.currencyCurrencyCodeEnumThe 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.valuestringThe 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.feeTypeFeeEnumThe type of fee associated with the line item.

Occurrence: Conditional

lineItems.imageImageAn eBay-assigned URL of the item image.

Occurrence: Always

lineItems.image.imageUrlstringThe URL for the image.

Occurrence: Always

lineItems.itemIdstringThe eBay identifier of an item. This ID is returned by the Browse and Feed API methods.

Occurrence: Always

lineItems.legacyReferenceLegacyReferenceA 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.lineItemIdstringA unique eBay-assigned ID value that identifies a line item in a checkout session. This is created by the initiateGuestCheckoutSession.

Occurrence: Always

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

Occurrence: Always

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

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

Occurrence: Always

lineItems.netPriceAmountThe total cost for the line item, taking into account the quantity, any seller item discounts, and any coupon that applies.

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

Occurrence: Always

lineItems.netPrice.currencyCurrencyCodeEnumThe 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.valuestringThe 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.orderIdstringThe unique order ID for the line item.

Maximum Length: 40 characters

Occurrence: Conditional

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

Occurrence: Conditional

lineItems.promotions.discountAmountThe details regarding the monetary value of the promotional discount.

Note: eBay Bucks are not supported.

Occurrence: Conditional

lineItems.promotions.discount.currencyCurrencyCodeEnumThe 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.valuestringThe 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.messagestringThe text for the promotion title, which describes the promotion.

Occurrence: Conditional

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

Occurrence: Conditional

lineItems.quantityintegerThe quantity ordered for the line item.

Occurrence: Always

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

Occurrence: Always

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

Occurrence: Always

lineItems.shippingDetailShippingDetailA container for information about the shipping details of the order.

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 for the line item, such as FedEx or USPS.

Occurrence: Conditional

lineItems.shippingDetail.shippingServiceCodestringThe name of the shipping service option. For example, Priority Mail Express (provided by USPS) or FedEx International Priority (Provided by FedEx).

Occurrence: Conditional

lineItems.taxDetailsarray of TaxDetailA container for the tax information for the line item.

Occurrence: Conditional

lineItems.taxDetails.includedInPricebooleanA field that indicates whether tax was applied for the cost of the item and its shipping.

Occurrence: Conditional

lineItems.taxDetails.taxJurisdictionTaxJurisdictionA container that returns the tax jurisdiction information.

Occurrence: Conditional

lineItems.taxDetails.taxJurisdiction.regionRegionThe region of the tax jurisdiction.

Occurrence: Conditional

lineItems.taxDetails.taxJurisdiction.region.regionNamestringA 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.regionTypeRegionTypeEnumAn enumeration value that indicates the type of region for the tax jurisdiction.

Valid Values:
  • STATE_OR_PROVINCE
  • COUNTRY

Occurrence: Conditional

lineItems.taxDetails.taxJurisdiction.taxJurisdictionIdstringThe identifier of the tax jurisdiction.

Occurrence: Conditional

lineItems.taxDetails.taxTypeTaxTypeA field that indicates the type of tax that may be collected for the item.

Occurrence: Conditional

lineItems.titlestringThe seller-created title of the item.

Occurrence: Conditional

pricingSummaryPricingSummaryA container that breaks down the costs for the order, including total cost, shipping cost, tax, fees, and any discounts.

Occurrence: Always

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

Occurrence: Conditional

pricingSummary.additionalSavings.currencyCurrencyCodeEnumThe 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.valuestringThe 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.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 order that are not already captured in one of the other fields.

Occurrence: Always

pricingSummary.adjustment.amountAmountThe container that returns the amount and currency of an adjustment.

Occurrence: Always

pricingSummary.adjustment.amount.currencyCurrencyCodeEnumThe 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.valuestringThe 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.labelstringThe text indicating what the adjustment was for.

Occurrence: Always

pricingSummary.deliveryCostAmountThe delivery cost for all of the line items, after any delivery discounts are applied.

For example, there are four line items, and the delivery cost for each line item is $5. One of the line items qualifies for free delivery. The deliveryCost would be $15, which is the total cost for delivering all of the line items after the discount is applied.

Note: The cost includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB) to see VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Always

pricingSummary.deliveryCost.currencyCurrencyCodeEnumThe 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.valuestringThe 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.deliveryDiscountAmountThe total amount of the order delivery discounts for all of the line items, such as free shipping.

Occurrence: Conditional

pricingSummary.deliveryDiscount.currencyCurrencyCodeEnumThe 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.valuestringThe 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.feeAmountThe total amount of any fees for all the line items in the order, such as a recycling fee.

Occurrence: Always

pricingSummary.fee.currencyCurrencyCodeEnumThe 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.valuestringThe 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.importChargesAmountThe sum of all Global Shipping Program import charges, for all the line items in the order.

Occurrence: Conditional

pricingSummary.importCharges.currencyCurrencyCodeEnumThe 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.valuestringThe 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.importTaxImportTaxThe 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.currencyCurrencyCodeEnumThe 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.valuestringThe 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.importTaxTypeImportTaxTypeEnumAn 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 GST). The Goods and Services tax is only applicable to orders for the eBay Australia marketplace.

Occurrence: Conditional

pricingSummary.priceDiscountAmountThe total discount amount for all line items in the order.

For example, there are four line items in the order. Two of the line items qualify for a Buy 1, Get 1 offer, which is a $6 and a $15 discount. The priceDiscount value returned would be 21, which is the total of the two discounts.

Note: Delivery discount amounts, if applicable, are not reflected in the value returned in this field.

Occurrence: Always

pricingSummary.priceDiscount.currencyCurrencyCodeEnumThe 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.valuestringThe 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.priceSubtotalAmountThe 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.

Note: The price includes the value-added tax (VAT) for applicable jurisdictions when requested from supported marketplaces. In this case, users must pass the X-EBAY-C-MARKETPLACE-ID request header specifying the supported marketplace (such as EBAY_GB) to see VAT-inclusive pricing. For more information on VAT, refer to VAT Obligations in the EU.

Occurrence: Always

pricingSummary.priceSubtotal.currencyCurrencyCodeEnumThe 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.valuestringThe 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.taxAmountThe total amount of taxes for all line items in the order.

Occurrence: Always

pricingSummary.tax.currencyCurrencyCodeEnumThe 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.valuestringThe 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.totalAmountThe total cost of the order, which includes: (priceSubtotal - priceDiscount) + deliveryCost + tax +/- adjustment + fee + importCharges - additionalSavings.

Occurrence: Always

pricingSummary.total.currencyCurrencyCodeEnumThe 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.valuestringThe 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

purchaseOrderCreationDatestringThe creation date of the purchase order.

Occurrence: Always

purchaseOrderIdstringThe unique identifier of the purchase order.

Occurrence: Always

purchaseOrderPaymentStatusPurchaseOrderPaymentStatusEnumA container that returns the payment status 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.currencyCurrencyCodeEnumThe 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.valuestringThe 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

warningsarray of ErrorDetailV3A container for any 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: Conditional

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

Occurrence: Conditional

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: Conditional

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 what must be done to correct the problem.

Occurrence: Conditional

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

Occurrence: Conditional

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.namestringThe name of the input field that caused an issue with the method request.

Occurrence: Conditional

warnings.parameters.valuestringThe 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
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. There is no payload with this request.
GET
https://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).