order APIv1_beta.12.0

getPurchaseOrder

GET
/purchase_order/{purchaseOrderId}

This method 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 method has no request payload.

The placeOrder 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.

This method 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)

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

URI parameters

ParameterTypeDescription
purchaseOrderIdstringThe 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 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 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

HTTP response headers

{ /* PurchaseOrder */ }
Output container/fieldTypeDescription
appliedCouponsarray of CouponThe container that returns the information for the coupons that were applied in the checkout session.

Occurrence: Conditional

appliedCoupons.redemptionCodestringThe coupon redemption code.

Occurrence: Conditional

lineItemsarray of LineItemThe type that defines the fields for the line items in the purchase order.

Occurrence: Always

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.

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 method 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 Create a cancellation request.

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 method. This method 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.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 state of this line item.

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.

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.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.usernamestringThe user name created by the seller for use on eBay.

Occurrence: Always

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.

Occurrence: Conditional

lineItems.shippingDetail.minEstimatedDeliveryDatestringThe beginning of the date range in which the purchase order is expected to be delivered to the shipping address.

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

paymentInstrumentPaymentInstrumentList of payment methods that can be used for the purchase order. Currently only CREDIT_CARD is supported.

Occurrence: Conditional

paymentInstrument.brandPaymentMethodBrandThe name of the credit card company (brand).

Occurrence: Conditional

paymentInstrument.brand.logoImageImageThe URL of the image of the credit card company (brand).

Occurrence: Conditional

paymentInstrument.brand.logoImage.heightinteger Reserved for future use.

Occurrence: Conditional

paymentInstrument.brand.logoImage.imageUrlstringThe URL of the image.

Occurrence: Conditional

paymentInstrument.brand.logoImage.widthinteger Reserved for future use.

Occurrence: Conditional

paymentInstrument.brand.paymentMethodBrandTypePaymentMethodBrandEnumAn enumeration value that indicates the credit card company (brand).

Occurrence: Conditional

paymentInstrument.paymentMethodTypePaymentMethodTypeEnumAn enumeration value that indicates the method of payment, such as credit card.

Occurrence: Conditional

pricingSummaryPricingSummaryThe container for the details of the grand total of the order.

Occurrence: Conditional

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 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.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 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.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.priceDiscountAmountThe 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.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 before adding in taxes, shipping costs, and seller adjustments and subtracting promotional and shipping discounts.

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 + 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

purchaseOrderCreationDatestringThis timestamp indicates the date and time when the purchase order was created.

Occurrence: Always

purchaseOrderIdstringThe 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

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

Occurrence: Conditional

purchaseOrderStatusPurchaseOrderStatusEnumThe container for the current status of the buyer's payment and any refund that applies to the purchase order.

Occurrence: Conditional

refundedAmountAmountRefund Amount for 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

shippingAddressShippingAddressThe shipping address for the purchase order.

Occurrence: Conditional

shippingAddress.addressLine1stringThe first line of the street address where the item is being shipped.

Occurrence: Conditional

shippingAddress.addressLine2stringThe 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.citystringThe city of the address where the item is being shipped.

Occurrence: Conditional

shippingAddress.countryCountryCodeEnumThe two letter code representing the country of the address.

Restrictions: Currently, the only country supported for a shipping address is US.

Occurrence: Conditional

shippingAddress.countystringThe county of the address where the item is being shipped.

Occurrence: Conditional

shippingAddress.phoneNumberstringThe phone number of the person receiving the package.

Occurrence: Conditional

shippingAddress.postalCodestringThe postal code of the address where the item is being shipped.

Occurrence: Conditional

shippingAddress.recipientstringName of the person receiving the package.

Occurrence: Conditional

shippingAddress.stateOrProvincestringThe state or province of the address where the item is being shipped.

Occurrence: Conditional

shippingFulfillmentsarray of ShippingFulfillmentAn array of the shipping providers and the purchase order delivery details.

Occurrence: Conditional

shippingFulfillments.actualDeliveryDatestringThe date the purchase order was delivered.

Occurrence: Conditional

shippingFulfillments.lineItemReferencesarray of LineItemReferenceType the defines the fields for the line item ID and the quantity.

Occurrence: Conditional

shippingFulfillments.lineItemReferences.lineItemIdstringA unique eBay-assigned ID value to identify the line item in a purchase order.

Occurrence: Always

shippingFulfillments.lineItemReferences.quantityintegerThe number of individual items ordered for this line item, as specified by the buyer.

Occurrence: Always

shippingFulfillments.maxEstimatedDeliveryDatestringThe end of the date range in which the purchase order is expected to be delivered to the shipping address.

Occurrence: Conditional

shippingFulfillments.minEstimatedDeliveryDatestringThe beginning of the date range in which the purchase order is expected to be delivered to the shipping address.

Occurrence: Conditional

shippingFulfillments.shipmentTrackingNumberstringThe shipping provider number associated with the purchase order that can be used to track the package.

Occurrence: Conditional

shippingFulfillments.shipmentTrackingUrlstringThe URL of the shipping provider's shipment tracking page.

Occurrence: Conditional

shippingFulfillments.shippedDatestringThe date the seller gave the purchase order to the shipping provider.

Occurrence: Conditional

shippingFulfillments.shippingCarrierCodestringA name of the shipping provider, such as FedEx, or USPS.

Occurrence: Conditional

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

Occurrence: Conditional

warningsarray of ErrorDetailV3An array of warning messages. These type of errors do not prevent the call from executing but should be checked.

Occurrence: Conditional

warnings.categorystringIdentifies the type of error.

Occurrence: Conditional

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

Occurrence: Conditional

warnings.errorIdintegerA unique number to identify the error.

Occurrence: Conditional

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

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

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.

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 an eBay Member Purchase Order

This sample returns the details for the specified eBay Member 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/purchase_order/5710372010

Output

The output shows that the specified purchase order contained two line items. The total cost of the items was 20 (pricingSummary.total) and the purchase order was paid for using a credit card (paymentInstrument.paymentMethodType = CREDIT_CARD, purchaseOrderPaymentStatus = PAID).