eBay Trading APIVersion 1379
 

OrderType

This type is used to express the details of an order. An order may contain one or more line items (purchases) from the same buyer. Regardless of how many line items an order has, only one payment is made for the order.

The GetOrders call returns many of the fields of this type.

The GetItemTransactions and GetSellerTransactions calls will only return order-level details if the IncludeContainingOrder boolean field is included in the call request and set to true.

The AddOrder call is used to combine two or more unpaid order line items (between the same seller and buyer) into a 'Combined Invoice' order. While combining these order line items into one 'Combined Invoice' order, the seller can make adjustments to accepted payment methods, shipping details (including costs), and the total cost of the order. Sometimes, sellers will reduce the cost of shipping if one or more order line items can be shipped together in the same package.

The GetMyeBaySelling call returns order details if the seller wishes to view listings that have sold, and the GetMyeBayBuying call returns order details if the buyer wishes to view items they have won or purchased.

Types that use OrderType:

Calls that use OrderType:

Fields



AdjustmentAmount ( AmountType (double) ) [0..1]
This value indicates the dollar amount by which the buyer has adjusted the order total. Adjustments to order costs may include shipping and handling, buyer discounts, or added services. A positive amount indicates the amount is an extra charge being paid to the seller by the buyer. A negative value indicates this amount is a credit given to the buyer by the seller.
See the Field Index to learn which calls use AdjustmentAmount.

AmountPaid ( AmountType (double) ) [0..1]
This value indicates the total amount paid by the buyer for the order. This amount includes the sale price of each line item, shipping and handling charges, additional services, and any sales tax applied towards the order. This value is only returned after the buyer has paid for the order.
Note: For GetOrders only: If using Trading WSDL Version 1307 or above, the amount in this field will include sales tax. If using a Trading WSDL older than Version 1307, the amount in this field will not include sales tax. To incorporate the new logic while using a Trading WSDL that is older than 1307, developers can also use the X-EBAY-API-COMPATIBILITY-LEVEL header and set its value to 1307 or higher.
See the Field Index to learn which calls use AmountPaid.

AmountSaved ( AmountType (double) ) [0..1]
This value indicates the amount that the buyer saved on the order due to any discounts (item, shipping, promotional) applied to the purchase, or if the seller 'manually' reduced the order total. This field is always returned even when it is '0.0'.
See the Field Index to learn which calls use AmountSaved.

BundlePurchase ( boolean ) [0..1]
Not used by any call.

Reserved for future use.
See the Field Index to learn which calls use BundlePurchase.

BuyerCheckoutMessage ( string ) [0..1]
This field is returned if the buyer left a message for the seller during checkout.
See the Field Index to learn which calls use BuyerCheckoutMessage.

BuyerPackageEnclosures ( BuyerPackageEnclosuresType ) [0..1]

This container is returned in GetOrders (and other order management calls) if the 'Pay Upon Invoice' option is being offered to the buyer, and the seller is including payment instructions in the shipping package(s) for the order. The 'Pay Upon Invoice' option is only available on the Germany site.
Note: The ContainingOrder.BuyerPackageEnclosures container will stop being returned by GetItemTransactions and GetSellerTransactions on January 31, 2024.
See the Field Index to learn which calls use BuyerPackageEnclosures.

BuyerTaxIdentifier ( TaxIdentifierType ) [0..*]

This container will either consist of VAT or Codice Fiscale taxpayer identification information for the buyer.

It is required that buyers registered on the Italy site provide their Codice Fiscale ID (similar to the Social Security Number for US citizens) before buying an item on the Italy site.

On the Spain site, a Spanish seller has the option to require that Spanish buyers (registered on Spain site) provide a tax ID before checkout. This option is set by the seller at the account level. Once a Spanish buyer provides a tax ID, this tax ID is associated with his/her account, and once a tax ID is associated with the account, Spanish buyer will be asked to provide the tax ID during checkout on all eBay sites. Buyers with a registered address outside of Spain will not be asked to provide a tax ID during checkout.

This container is only returned for Spanish or Italian sellers when the buyer was asked to provide tax identifier information during checkout. A BuyerTaxIdentifier container will be returned for each tax ID that is associated with the buyer's account.
Note: The ContainingOrder.BuyerTaxIdentifier container will stop being returned by GetItemTransactions and GetSellerTransactions on January 31, 2024.
See the Field Index to learn which calls use BuyerTaxIdentifier.

BuyerUserID ( UserIDType (string) ) [0..1]
The eBay user ID of the order's buyer.
See the Field Index to learn which calls use BuyerUserID.

CancelReason ( token ) [0..1]
This value indicates the reason why the order cancellation was initiated. This field is only returned if an order cancellation has been initiated by the buyer or seller. Typical buyer-initiated cancellation reasons include 'OrderPlacedByMistake', 'WontArriveInTime', or 'FoundCheaperPrice'. Sellers may initiate an order cancellation on behalf of the buyer. In this scenario, the seller should state the cancellation reason as 'BuyerCancelOrder'. If the seller is cancelling an order because he/she is out of stock on an item, the seller should state the cancellation reason as 'OutOfStock'. Unfortunately, in this scenario, the seller will receive a seller defect for this cancellation reason. See CancelReasonCodeType for the complete list of enumeration values that can be returned in this field.
See the Field Index to learn which calls use CancelReason.

CancelStatus ( CancelStatusCodeType ) [0..1]
The current status for the order cancellation request (if it exists for the order). This field is only returned if a cancellation request has been made on the order, or if the order is currently going through the cancellation process, or if the order has already been cancelled.
See the Field Index to learn which calls use CancelStatus.

CheckoutStatus ( CheckoutStatusType ) [0..1]
This container indicates the current status of the order, including a timestamp that indicates the last time that the status of the order changed. For orders that have been paid for, the Status value will show as Complete.
See the Field Index to learn which calls use CheckoutStatus.

ContainseBayPlusTransaction ( boolean ) [0..1]
If true, the order contains a transaction for an item that was purchased under the eBay Plus program. eBay Plus is a premium account option for buyers, which provides benefits such as fast free domestic shipping and free returns on selected items. Top-Rated eBay sellers must opt in to eBay Plus to be able offer the program on qualifying listings. Sellers must commit to next-day delivery of those items.

Note: Currently, eBay Plus is available only to buyers in Germany and Australia.
See the Field Index to learn which calls use ContainseBayPlusTransaction.

CreatedTime ( dateTime ) [0..1]
Timestamp that indicates the date and time that the order was created.

Note: For single line item orders, this timestamp value is often the same as the CreatedDate field in the corresponding Transaction container.
See the Field Index to learn which calls use CreatedTime.

CreatingUserRole ( TradingRoleCodeType ) [0..1]
This value indicates whether a 'Combined Invoice' order was initiated/created by the buyer or by the seller. This field is only returned for Combined Invoice orders.

An AddOrder call can be used by a seller or buyer to combine two or more unpaid order line items into a 'Combined Invoice' order. Once two or more line items are successfully combined into one order, the buyer only needs to make one payment (instead of multiple payments - one for each order line item). The CreatingUserRole field is required in the AddOrder call request.

Note: Except for listings that required immediate payment, buyers also may have the opportunity to combine multiple line items (from the same seller) into a 'Combined Invoice' order through the buy/checkout flow. This may include accepted Best Offers or auctions that the buyer wins.
See the Field Index to learn which calls use CreatingUserRole.

eBayCollectAndRemitTax ( boolean ) [0..1]

This boolean field is returned as true if one or more line items in the order are subject to a tax (US sales tax or Australian Goods and Services tax) that eBay will collect and remit to the proper taxing authority on the buyer's behalf. This field is also returned if false (not subject to eBay Collect and Remit). A Transaction.eBayCollectAndRemitTaxes container is returned for any order line items subject to such a tax, and the type and amount of this tax is displayed in the Transaction.eBayCollectAndRemitTaxes.TaxDetails container.

Australian 'Goods and Services' tax (GST) is automatically charged to buyers outside of Australia when they purchase items on the eBay Australia site. Sellers on the Australia site do not have to take any extra steps to enable the collection of GST, as this tax is collected by eBay and remitted to the Australian government. For more information about Australian GST, see the Taxes and import charges help topic.

As of January 2023, buyers in all US states will automatically be charged sales tax for purchases, and the seller does not set this rate. eBay will collect and remit this sales tax to the proper taxing authority on the buyer's behalf. For more US state-level information on sales tax, see the eBay sales tax collection help topic.
Note: The ContainingOrder.eBayCollectAndRemitTax field will stop being returned by GetItemTransactions and GetSellerTransactions on January 31, 2024.
See the Field Index to learn which calls use eBayCollectAndRemitTax.

EIASToken ( string ) [0..1]
Unique identifier for the user that does not change when the eBay user name is changed. Use when an application needs to associate a new eBay user name with the corresponding eBay user.

Since a bidder's user info is anonymous, this tag will be returned only to that bidder, and to the seller of an item that the user is bidding on.
See the Field Index to learn which calls use EIASToken.

ExtendedOrderID ( string ) [0..1]
A unique identifier for an eBay order. This identifier is globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. Note that the order ID will change for a 'non-immediate payment' order as it goes from an unpaid order to a paid order.

Note: The value in the OrderID and ExtendedOrderID fields should always be the same. The ExtendedOrderID field was added back in 2019 during a transition period where the Trading API was supporting both old and new order ID formats, and which order ID format that was returned was dependent on the compatibility level version used.
See the Field Index to learn which calls use ExtendedOrderID.

IsMultiLegShipping ( boolean ) [0..1]

If IsMultilegShipping is true, at least one order line item in the order will not be shipped directly to the buyer. Orders requiring multiple shipping legs include international orders being shipped through the Global Shipping Program or through eBay International Shipping, as well as orders subject to/eligible for the Authenticity Guarantee program. For both international shipping options, the address of the shipping logistics provider is shown in the MultiLegShippingDetails.SellerShipmentToLogisticsProvider.ShipToAddress container. Similarly, for Authenticity Guarantee orders, the authentication partner's shipping address is shown in the same container.

If an order line item is subject to the Authenticity Guarantee service, the <b>Transaction.Program</b> container will be returned.
Note: The ContainingOrder.IsMultiLegShipping field will stop being returned by GetItemTransactions and GetSellerTransactions on January 31, 2024.
See the Field Index to learn which calls use IsMultiLegShipping.

LogisticsPlanType ( token ) [0..1]

This field will be returned at the order level only if the buyer purchased a digital gift card, which is delivered by email, or if the buyer purchased an item that is enabled with the 'Click and Collect' feature.

Currently, LogisticsPlanType has two applicable values: PickUpDropOff, which indicates that the buyer selected the 'Click and Collect' option. With Click and Collect, buyers are able to purchase from thousands of sellers on the eBay UK and Australia sites, and then pick up their order from the nearest 'eBay Collection Point', including over 750 Argos stores in the UK. The Click and Collect feature is only available on the eBay UK and Australia sites; or, DigitalDelivery, which indicates that the order is a digital gift card that will be delivered to the buyer or recipient of the gift card by email.
Note: The ContainingOrder.LogisticsPlanType field will stop being returned by GetItemTransactions and GetSellerTransactions on January 31, 2024.
See the Field Index to learn which calls use LogisticsPlanType.

MonetaryDetails ( PaymentsInformationType ) [0..1]

Contains information about each monetary transaction that occurs for the order, including order payment, any refund, a credit, etc. Both the payer and payee are shown in this container.
Note: The ContainingOrder.MonetaryDetails container will stop being returned by GetItemTransactions and GetSellerTransactions on January 31, 2024.
See the Field Index to learn which calls use MonetaryDetails.

MultiLegShippingDetails ( MultiLegShippingDetailsType ) [0..1]

This container consists of details related to the first leg of an order requiring multiple shipping legs. Types of orders that require multiple shipping legs include international orders going through Global Shipping Program or eBay International Shipping, as well as orders subject to/eligible for the Authenticity Guarantee program. If the item is subject to the Authenticity Guarantee service program, the seller ships the item to the authentication partner, and if the item passes an authentication inspection, the authentication partner ships it directly to the buyer.

This container is only returned if the order has one or more order line items requiring multiple shipping legs.
Note: The ContainingOrder.MultiLegShippingDetails container will stop being returned by GetItemTransactions and GetSellerTransactions on January 31, 2024.
See the Field Index to learn which calls use MultiLegShippingDetails.

OrderID ( OrderIDType (string) ) [0..1]
A unique identifier for an eBay order. This identifier is globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. Note that the order ID will change for a 'non-immediate payment' order as it goes from an unpaid order to a paid order.

Note: The value in the OrderID and ExtendedOrderID fields should always be the same. The ExtendedOrderID field was added back in 2019 during a transition period where the Trading API was supporting both old and new order ID formats, and which order ID format that was returned was dependent on the compatibility level version used.
See the Field Index to learn which calls use OrderID.

OrderLineItemCount ( long ) [0..1]

This field indicates the total number of line items in the order. This field is returned under the ContainingOrder container of a GetItemTransactions or GetSellerTransactions call. In order for the ContainingOrder container to be returned, a user must include the IncludeContainingOrder field in the call request and set its value to true.

Note: This field is automatically returned if the user is using Version 1113 of the Trading WSDL (or newer), or if the user includes the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header and sets its value to 1113 (or newer). If a user is using a Trading WSDL older than 1113 (or is not setting the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header value to 1113 or newer), this field will not be returned.
See the Field Index to learn which calls use OrderLineItemCount.

OrderStatus ( OrderStatusCodeType ) [0..1]
This enumeration value indicates the current status of the order.
See the Field Index to learn which calls use OrderStatus.

PaidTime ( dateTime ) [0..1]
Timestamp indicating the date and time of order payment. This field is not returned until payment has been made by the buyer.

This time is specified in GMT (not Pacific time). See API data types section of the Making a Trading API call guide for information about converting between GMT and other time zones.
See the Field Index to learn which calls use PaidTime.

PaymentHoldStatus ( PaymentHoldStatusCodeType ) [0..1]
This field indicates the type and/or status of a payment hold on the item. It is always returned for GetOrders, even if there are no payment holds (in which case, an enumeration value of None is shown).
Note: For the GetItemTransactions and GetOrders calls, this field is only returned to the seller of the order; this field is not returned for the buyer or third party. Note: This field will stop being returned by GetItemTransactions and GetSellerTransactions on January 31, 2024.
See the Field Index to learn which calls use PaymentHoldStatus.

PaymentMethods ( BuyerPaymentMethodCodeType ) [0..*]
In GetOrders and OrderReport, a PaymentMethods field will appear for each payment method available to the buyer for the order's purchase. However, once the buyer pays for the order, any and all of these PaymentMethods fields will stop being returned, and instead, the actual payment method used will be returned in the PaymentMethod field of the CheckoutStatus container.

In an AddOrder call, the seller can use one or more PaymentMethods fields to override whatever available payment methods were already defined for each individual line item.

Note: For AddOrder, the seller can only specify offline payment methods (if offline payment is supported for the listing), as eBay now controls all electronic payment methods avaialable to buyers, and sellers have no control over these payment methods.
See the Field Index to learn which calls use PaymentMethods.

PickupDetails ( PickupDetailsType ) [0..1]
Container consisting of an array of PickupOptions containers. Each PickupOptions container consists of the pickup method and its priority. The priority of each pickup method controls the order (relative to other pickup methods) in which the corresponding pickup method will appear in the View Item and Checkout page.

For GetOrders, this container is always returned prior to order payment if the seller created/revised/relisted the item with the EligibleForPickupInStore and/or EligibleForPickupDropOff flag in the call request set to 'true'. If and when the In-Store pickup method (US only) or 'Click and Collect' pickup method (UK and Australia only) is selected by the buyer and payment for the order is made, this container will no longer be returned in the response, and will essentially be replaced by the PickupMethodSelected container.

Note: A seller must be eligible for the In-Store Pickup feature or Click and Collect feature to list an item that is eligible for In-Store Pickup or Click and Collect. At this time, the In-Store Pickup and Click and Collect features are generally only available to large retail merchants, and can only be applied to multiple-quantity, fixed-price listings.
See the Field Index to learn which calls use PickupDetails.

PickupMethodSelected ( PickupMethodSelectedType ) [0..1]
Container consisting of details related to the selected pickup method, including the pickup method type, the merchant's store ID, the status of the pickup, and the pickup reference code (if provided by merchant).

This container is only returned when the buyer has selected the In-Store Pickup or Click and Collect option and has paid for the order. All fields in the PickupMethodSelected container are static, except for the PickupStatus field, which can change states based on the notifications that a merchant sends to eBay through the Inbound Notifications API.

Note: A seller must be eligible for the In-Store Pickup or Click and Collect feature to list an item that is eligible for these features. At this time, the In-Store Pickup and Click and Collect features are generally only available to large retail merchants, and can only be applied to multiple-quantity, fixed-price listings.
See the Field Index to learn which calls use PickupMethodSelected.

RefundAmount ( AmountType (double) ) [0..1]
The amount of the refund due to, or already issued to the buyer for the order. This field is only returned in GetMyeBaySelling if a buyer refund is due, or was issued for the order.
See the Field Index to learn which calls use RefundAmount.

RefundStatus ( string ) [0..1]
This string value indicates the result of a seller's refund to the buyer. Its value are 'Success', 'Failure' or 'Pending'. This field is only returned in GetMyeBaySelling if the buyer has received a refund from the seller, or is due to receive a refund.
See the Field Index to learn which calls use RefundStatus.

SellerEIASToken ( string ) [0..1]
This is a unique identifier for the seller that does not change when the eBay user name is changed. This is useful when an application needs to associate a new eBay user name with the corresponding eBay user.

Note: For the GetOrders call, this field is only returned to the seller of the order; this field is not returned for the buyer or third party.
See the Field Index to learn which calls use SellerEIASToken.

SellerEmail ( string ) [0..1]
The email address of the seller involved in the order. The email address of the seller is only returned if it is the same seller making the call.

Note: For the GetOrders calls, this field is only returned to the seller of the order; this field is not returned to the buyer or to a third party.
See the Field Index to learn which calls use SellerEmail.

SellerUserID ( UserIDType (string) ) [0..1]
This is the eBay user ID of the order's seller.
See the Field Index to learn which calls use SellerUserID.

ShippedTime ( dateTime ) [0..1]
Timestamp indicating the date and time of order shipment. This field is not returned until shipment tracking is provided for all line items in the order, or if the order has been marked as 'shipped' by the seller.

This time is specified in GMT (not Pacific time). See API data types section of the Making a Trading API call guide for information about converting between GMT and other time zones.
See the Field Index to learn which calls use ShippedTime.

ShippingAddress ( AddressType ) [0..1]
This container shows the shipping address for the order.

Note: For an Authenticity Guarantee program shipment, this is the address of the authenticator's warehouse. The authenticator is responsible for delivery to the buyer's shipping address.

Note: For transactions completed offline, the shipping address detail may be empty.

Note: For In-Store Pickup and Click and Collect orders, this is the address of the merchant's store where the buyer will pick up the order.

Note: For eBay Vault scenarios: GetOrders and GetItemTransactions calls, mock address details are returned for:

- Vault to vault orders: Buyer and Seller View

- Ship to vault orders: Mock addresses are returned for the Buyer View (only); the address returned for the Seller View will be the authenticator's address.

- Vault in-hand submission orders: the address returned for the Buyer View will be the authenticator's address.

The following address details are returned for mock addresses:

 <ShippingAddress> 
 <Name>eBay Vault</Name>
 <AddressID>Invalid Request</AddressID>
 <AddressOwner>eBay</AddressOwner>
 <AddressUsage>Invalid</AddressUsage>
 <CityName>Invalid Request</CityName>
 <Country>US</Country>
 <CountryName>Invalid Request</CountryName>
 <ExternalAddressID>Invalid Request</ExternalAddressID>
 <Phone>Invalid Request</Phone>
 <PostalCode>Invalid Request</PostalCode>
 <StateOrProvince>Invalid Request</StateOrProvince>
 <Street1>Invalid Request</Street1>
 <Street2></Street2>
</ShippingAddress>

See the Field Index to learn which calls use ShippingAddress.

ShippingDetails ( ShippingDetailsType ) [0..1]
Container consisting of order-level shipping details. More shipping-related details can be found at the line item level for each line item in the order.

In an AddOrder call, the seller can use the ShippingDetails container to make adjustments to shipping details, including the available shipping service options and shipping cost. Sometimes, sellers will reduce the cost of shipping if one or more order line items can be shipped together in the same package.
See the Field Index to learn which calls use ShippingDetails.

ShippingServiceSelected ( ShippingServiceOptionsType ) [0..1]
Container consisting of details about the domestic or international shipping service selected by the buyer for delivery of the order. Note that more shipping service information may be returned at the order line item level in the Transaction.ShippingServiceSelected container.
See the Field Index to learn which calls use ShippingServiceSelected.

Subtotal ( AmountType (double) ) [0..1]
The cumulative item cost for all line items in the order. This value does not take into account any shipping/handling costs, sales tax costs, or any discounts. For a single line item order, the amount in this field should be the same as the amount in the Transaction.TransactionPrice field. For a multiple line item order, the amount in this field should equal the cumulative amount of each Transaction.TransactionPrice fields for each order line item.
See the Field Index to learn which calls use Subtotal.

Total ( AmountType (double) ) [0..1]
The Total amount shows the total cost for the order, including total item cost (shown in Subtotal field), shipping charges (shown in ShippingServiceSelected.ShippingServiceCost field), and sales tax (shown in SalesTax.SalesTaxAmount field).
Note: For GetOrders only: If using Trading WSDL Version 1307 or above, the amount in this field will include sales tax. If using a Trading WSDL older than Version 1307, the amount in this field will not include sales tax. To incorporate the new logic while using a Trading WSDL that is older than 1307, developers can also use the X-EBAY-API-COMPATIBILITY-LEVEL header and set its value to 1307 or higher.
In an AddOrder call, the seller can pass in the Total amount for the 'Combined Invoice' order, and this is what the buyer will be expected to pay for the order.
See the Field Index to learn which calls use Total.

TransactionArray ( TransactionArrayType ) [0..1]
Container consisting of one or more line items that comprise an order. The data for each order line item in the order is stored in a separate Transaction container.

Under the TransactionArray container in an AddOrder call, a seller or buyer specifies two or more (up to 40) order line items into a 'Combined Invoice' order.
See the Field Index to learn which calls use TransactionArray.