This call retrieves the details about a specific eBay member 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 call has no request payload.
The placeOrder call initiates the payment process, which can sometimes take a few minutes. You can use this call 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.
This call also returns the legacyItemId, legacyTransactionId, and legacyOrderId fields. The values in these fields enable eBay partners to use the Post Order API for eBay member checkouts, to process a return or cancellation. For more information, see Post order tasks in the Buy Integration Guide.
Restrictions
For a list of supported sites and other restrictions, see API Restrictions in the Order API overview.
Input
Resource URI (production)
URI parameters
| Parameter | Type | Description |
|---|---|---|
| purchaseOrderId | string | The unique identifier of a purchase order made by an eBay Member, for which details are to be retrieved. This value is returned by the placeOrder call in the purchaseOrderId field. The purchaseOrderId is passed in as a URI parameter and is required. Occurrence: Required |
HTTP request headers
OAuth scope
This request requires an access token created with the authorization code grant flow, using one scope from the following list:
https://api.ebay.com/oauth/api_scope/buy.order.readonly
https://api.ebay.com/oauth/api_scope/buy.order
See Oauth access tokens for more information.
Output
| Output container/field | Type | Description |
|---|---|---|
| lineItems | array of LineItem | The type that defines the fields for the line items in the purchase order. Occurrence: Always |
| lineItems.image | Image | The URL of the item's image. Occurrence: Always |
| lineItems.image.height | integer | Reserved for future use. Occurrence: Conditional |
| lineItems.image.imageUrl | string | The URL of the image. Occurrence: Conditional |
| lineItems.image.width | integer | Reserved for future use. Occurrence: Conditional |
| lineItems.itemId | string | The identifier of the item. Occurrence: Always |
| lineItems.legacyReference | LegacyReference | The container that returns fields to support using the Post Order API for returns and cancellations. Note: The Post Order API can be used only with eBay member checkouts. Occurrence: Conditional |
| lineItems.legacyReference.legacyItemId | string | The legacy ID used to identify an item. 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 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.legacyOrderId | string | The legacy ID of the order. This is used by the Post Order API Submit Cancellation Request call. This call initiates the item cancellation process. For more information on how to use this field in the Post Order API, see Create a cancellation request. Restriction: The Post Order API can be used only with eBay member checkouts. Occurrence: Conditional |
| lineItems.legacyReference.legacyTransactionId | string | The 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 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.lineItemId | string | The identifier of this line item. This is created by the initiateCheckoutSession for a member and initiateGuestCheckoutSession for a guest calls. Occurrence: Conditional |
| lineItems.lineItemPaymentStatus | LineItemPaymentStatusEnum | An enumeration value that indicates the payment status of this line item. Occurrence: Always |
| lineItems.lineItemStatus | LineItemStatusEnum | An enumeration value that indicates the state of this line item. Occurrence: Conditional |
| lineItems.netPrice | Amount | The 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. Note : This does not include any shipping discounts, shipping costs, or seller adjustments. Occurrence: Conditional |
| lineItems.netPrice.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| lineItems.netPrice.value | string | The monetary amount. Occurrence: Always |
| lineItems.quantity | integer | The number of individual items in this line item. Occurrence: Always |
| lineItems.seller | Seller | The 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 | Information about the shipping provider used for this line item. 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. 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. Occurrence: Conditional |
| lineItems.shippingDetail.shippingCarrierCode | string | The shipping provider, such as FedEx, or USPS for the line item. Occurrence: Conditional |
| lineItems.shippingDetail.shippingServiceCode | string | A name of a shipping type. For example, Priority Mail Express (provided by USPS) or FedEx International Priority (Provided by FedEx). Occurrence: Conditional |
| lineItems.title | string | The seller created title of the item. Occurrence: Conditional |
| paymentInstrument | PaymentInstrument | List of payment methods that can be used for the purchase order. Currently only CREDIT_CARD is supported. Occurrence: Conditional |
| paymentInstrument.brand | PaymentMethodBrand | The name of the credit card company (brand). Occurrence: Conditional |
| paymentInstrument.brand.logoImage | Image | The URL of the image of the credit card company (brand). Occurrence: Conditional |
| paymentInstrument.brand.logoImage.height | integer | Reserved for future use. Occurrence: Conditional |
| paymentInstrument.brand.logoImage.imageUrl | string | The URL of the image. Occurrence: Conditional |
| paymentInstrument.brand.logoImage.width | integer | Reserved for future use. Occurrence: Conditional |
| paymentInstrument.brand.paymentMethodBrandType | PaymentMethodBrandEnum | An enumeration value that indicates the credit card company (brand). Occurrence: Conditional |
| paymentInstrument.paymentMethodType | PaymentMethodTypeEnum | An enumeration value that indicates the method of payment, such as credit card. Occurrence: Conditional |
| pricingSummary | PricingSummary | The container for the details of the grand total of the order. 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 purchase order that are not already captured in one of the other fields. Occurrence: Conditional |
| pricingSummary.adjustment.amount | Amount | The container for the amount and currency of the adjustment. Occurrence: Conditional |
| pricingSummary.adjustment.amount.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| pricingSummary.adjustment.amount.value | string | The monetary amount. Occurrence: Always |
| pricingSummary.adjustment.label | string | Text that describes the adjustment. Occurrence: Conditional |
| pricingSummary.deliveryCost | Amount | The 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 items is $5. One of the line items qualifies for free shipping ($5) and two line items qualify for a Buy 1 Get 1 offer ($6 & $15 free item) discount. The deliveryCost value would be 20 ($5 x 4 items), which is the total cost for shipping all the line items before discounts. Occurrence: Conditional |
| pricingSummary.deliveryCost.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| pricingSummary.deliveryCost.value | string | The monetary amount. Occurrence: Always |
| pricingSummary.deliveryDiscount | Amount | The total amount of the shipping discounts for the all line items, which include promotional shipping discounts, such as free shipping if you buy two or more. 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 ($5) and two line items qualify for a Buy 1 Get 1 offer ($6 & $15 free item) discount. 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.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| pricingSummary.deliveryDiscount.value | string | The monetary amount. Occurrence: Always |
| pricingSummary.fee | Amount | The total amount of any fees for all the line items, such as a recycling fee. Occurrence: Conditional |
| pricingSummary.fee.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| pricingSummary.fee.value | string | The monetary amount. Occurrence: Always |
| pricingSummary.priceDiscount | Amount | The total amount of all the item specific discounts for all line items, such as Buy 1 Get 1 free discounts. 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 ($5) and two line items qualify for a Buy 1 Get 1 offer ($6 & $15 free item) discount. The priceDiscount value would be 21, which is the total of the two Buy 1 Get 1 discounts ($6 + $15). Note: This will always be a negative number. Occurrence: Conditional |
| pricingSummary.priceDiscount.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| pricingSummary.priceDiscount.value | string | The monetary amount. Occurrence: Always |
| pricingSummary.priceSubtotal | Amount | The total amount for all the line items before adding in taxes, shipping costs, and seller adjustments and subtracting promotional and shipping discounts. Occurrence: Conditional |
| pricingSummary.priceSubtotal.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| pricingSummary.priceSubtotal.value | string | The monetary amount. Occurrence: Always |
| pricingSummary.tax | Amount | The total amount of the taxes for all the line items. Occurrence: Conditional |
| pricingSummary.tax.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| pricingSummary.tax.value | string | The monetary amount. Occurrence: Always |
| pricingSummary.total | Amount | The total of the purchase order. total = priceSubtotal + baseDeliveryCost + tax + deliveryDiscounts + priceDiscount + adjustment. Note: deliveryDiscounts and priceDiscount are negative numbers. Occurrence: Conditional |
| pricingSummary.total.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| pricingSummary.total.value | string | The monetary amount. Occurrence: Always |
| purchaseOrderCreationDate | string | This timestamp indicates the date and time when the purchase order was created. Occurrence: Always |
| purchaseOrderId | string | The unique identifier of the purchase order. This value was returned in the purchaseOrderId field by the placeOrder for a member and placeGuestOrder for a guest calls. Occurrence: Always |
| purchaseOrderPaymentStatus | PurchaseOrderPaymentStatusEnum | An enumeration value that indicates the status of the payment for the purchase order. Occurrence: Conditional |
| purchaseOrderStatus | PurchaseOrderStatusEnum | The container for the current status of the buyer's payment and any refund that applies to the purchase order. Occurrence: Conditional |
| refundedAmount | Amount | Refund Amount for purchase order Occurrence: Conditional |
| refundedAmount.currency | CurrencyCodeEnum | A three letter ISO 4217 code specifying the currency of the monetary amount. Occurrence: Always |
| refundedAmount.value | string | The monetary amount. Occurrence: Always |
| shippingAddress | ShippingAddress | The shipping address for the purchase order. Occurrence: Conditional |
| shippingAddress.addressLine1 | string | The first line of the street address where the item is being shipped. Occurrence: Conditional |
| shippingAddress.addressLine2 | string | The second line of the street address where the item is being shipped. This optional field can be used for information such as 'Suite Number' or 'Apt Number'. Occurrence: Conditional |
| shippingAddress.city | string | The city of the address where the item is being shipped. Occurrence: Conditional |
| shippingAddress.country | CountryCodeEnum | The two letter code representing the country of the address. Restrictions: Currently, the only country supported for a shipping address is US. Occurrence: Conditional |
| shippingAddress.county | string | The county of the address where the item is being shipped. Occurrence: Conditional |
| shippingAddress.phoneNumber | string | The phone number of the person receiving the package. Occurrence: Conditional |
| shippingAddress.postalCode | string | The postal code of the address where the item is being shipped. Occurrence: Conditional |
| shippingAddress.recipient | string | Name of the person receiving the package. Occurrence: Conditional |
| shippingAddress.stateOrProvince | string | The state or province of the address where the item is being shipped. Occurrence: Conditional |
| shippingFulfillments | array of ShippingFulfillment | An array of the shipping providers and the purchase order delivery details. Occurrence: Conditional |
| shippingFulfillments.actualDeliveryDate | string | The date the purchase order was delivered. Occurrence: Conditional |
| shippingFulfillments.lineItemReferences | array of LineItemReference | Type the defines the fields for the line item ID and the quantity. Occurrence: Conditional |
| shippingFulfillments.lineItemReferences.lineItemId | string | A unique eBay-assigned ID value to identify the line item in a purchase order. Occurrence: Always |
| shippingFulfillments.lineItemReferences.quantity | integer | The number of individual items ordered for this line item, as specified by the buyer. Occurrence: Always |
| shippingFulfillments.maxEstimatedDeliveryDate | string | The end of the date range in which the purchase order is expected to be delivered to the shipping address. Occurrence: Conditional |
| shippingFulfillments.minEstimatedDeliveryDate | string | The beginning of the date range in which the purchase order is expected to be delivered to the shipping address. Occurrence: Conditional |
| shippingFulfillments.shipmentTrackingNumber | string | The shipping provider number associated with the purchase order that can be used to track the package. Occurrence: Conditional |
| shippingFulfillments.shipmentTrackingUrl | string | The URL of the shipping provider's shipment tracking page. Occurrence: Conditional |
| shippingFulfillments.shippedDate | string | The date the seller gave the purchase order to the shipping provider. Occurrence: Conditional |
| shippingFulfillments.shippingCarrierCode | string | A name of the shipping provider, such as FedEx, or USPS. Occurrence: Conditional |
| shippingFulfillments.shippingServiceCode | string | A name of a shipping type. For example, Priority Mail Express (provided by USPS) or FedEx International Priority (Provided by FedEx). Occurrence: Conditional |
| warnings | array of ErrorDetailV3 | An array of warning messages. These type of errors do not prevent the call from executing but should be checked. Occurrence: Conditional |
| warnings.category | string | Identifies the type of error. Occurrence: Conditional |
| warnings.domain | string | Name for the primary system where the error occurred. This is relevant for application errors. Occurrence: Conditional |
| warnings.errorId | integer | A unique number to identify the error. Occurrence: Conditional |
| warnings.inputRefIds | array of string | An array of request elements most closely associated to the error. Occurrence: Conditional |
| warnings.longMessage | string | A more detailed explanation of the error. Occurrence: Conditional |
| warnings.message | string | Information on how to correct the problem, in the end user's terms and language where applicable. Occurrence: Conditional |
| warnings.outputRefIds | array of string | An array of request elements most closely associated to the error. Occurrence: Conditional |
| warnings.parameters | array of ErrorParameterV3 | An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned. Occurrence: Conditional |
| warnings.parameters.name | string | The object of the error. Occurrence: Conditional |
| warnings.parameters.value | string | The value of the object. Occurrence: Conditional |
| warnings.subdomain | string | Further 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.
| Status | Meaning |
|---|---|
| 200 | OK |
| 403 | Access Forbidden |
| 404 | Not Found |
| 500 | Internal Server Error |
Error codes
| 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. |
Samples
Note:
Personal data, such as seller's name, buyer's name and address, etc. have been anonymized in the request and the response, per eBay policy.
New to making API calls? Please see Making a Call.
Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.
Sample 1: Get the Details of an eBay Member Purchase Order
Input
Output
CREDIT_CARD, purchaseOrderPaymentStatus = PAID).