fulfillment API1.11.0

getOrders

GET
/order
Use this call to search for and retrieve one or more orders based on their creation date, last modification date, or fulfillment status using the filter parameter. You can alternatively specify a list of orders using the orderIds parameter.

The returned Order objects contain information you can use to create and process fulfillments, including:
  • Information about the buyer and seller
  • Information about the order's line items
  • The plans for packaging, addressing and shipping the order
  • The status of payment, packaging, addressing, and shipping the order
  • A summary of monetary amounts specific to the order such as pricing, payments, and shipping costs


Important: In this call, the cancelStatus.cancelRequests array is returned but is always empty. Use the getOrder call instead, which returns this array fully populated with information about any cancellation requests.

Input

Resource URI (production)

GET https://api.ebay.com/sell/fulfillment/v1/order?

URI parameters

ParameterTypeDescription
orderIdsarray of stringA comma-separated list of the unique identifiers of the orders to retrieve (maximum 50). If one or more order ID values are specified through the orderIds query parameter, all other query parameters will be ignored.

Note: A new order ID format was introduced to all eBay APIs (legacy and REST) in June 2019. In REST APIs that return Order IDs, including the Fulfillment API, all order IDs are returned in the new format, but the getOrders method will accept both the legacy and new format order ID. The new format is a non-parsable string, globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. These order identifiers will be automatically generated after buyer payment, and unlike in the past, instead of just being known and exposed to the seller, these unique order identifiers will also be known and used/referenced by the buyer and eBay customer support.

Occurrence: Optional

filterarray of FilterFieldOne or more comma-separated criteria for narrowing down the collection of orders returned by this call. These criteria correspond to specific fields in the response payload. Multiple filter criteria combine to further restrict the results.

Note: Currently, filter returns data from only the last three months. If the orderIds parameter is included in the request, the filter parameter will be ignored.

The available criteria are as follows:
creationdate
The time period during which qualifying orders were created (the orders.creationDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example:
  • creationdate:[2016-02-21T08:25:43.511Z..] identifies orders created on or after the given timestamp.
  • creationdate:[2016-02-21T08:25:43.511Z..2016-04-21T08:25:43.511Z] identifies orders created between the given timestamps, inclusive.
lastmodifieddate
The time period during which qualifying orders were last modified (the orders.modifiedDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.For example:
  • lastmodifieddate:[2016-05-15T08:25:43.511Z..] identifies orders modified on or after the given timestamp.
  • lastmodifieddate:[2016-05-15T08:25:43.511Z..2016-05-31T08:25:43.511Z] identifies orders modified between the given timestamps, inclusive.
Note: If creationdate and lastmodifieddate are both included, only creationdate is used.

orderfulfillmentstatus
The degree to which qualifying orders have been shipped (the orders.orderFulfillmentStatus field). In the URI, this is expressed as one of the following value combinations:
  • orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS} specifies orders for which no shipping fulfillments have been started, plus orders for which at least one shipping fulfillment has been started but not completed.
  • orderfulfillmentstatus:{FULFILLED|IN_PROGRESS} specifies orders for which all shipping fulfillments have been completed, plus orders for which at least one shipping fulfillment has been started but not completed.
Note: The values NOT_STARTED, IN_PROGRESS, and FULFILLED can be used in various combinations, but only the combinations shown here are currently supported.
Here is an example of a getOrders call using all of these filters:

GET https://api.ebay.com/sell/v1/order?
filter=creationdate:%5B2016-03-21T08:25:43.511Z..2016-04-21T08:25:43.511Z%5D,
lastmodifieddate:%5B2016-05-15T08:25:43.511Z..%5D,
orderfulfillmentstatus:%7BNOT_STARTED%7CIN_PROGRESS%7D


Note: This call requires that certain special characters in the URI query string be percent-encoded:
    [ = %5B       ] = %5D       { = %7B       | = %7C       } = %7D
This query filter example uses these codes.

Occurrence: Optional

limitstringThe number of orders to return per page of the result set. Use this parameter in conjunction with the offset parameter to control the pagination of the output.

For example, if offset is set to 10 and limit is set to 10, the call retrieves orders 11 thru 20 from the result set.

Note: This feature employs a zero-based list, where the first item in the list has an offset of 0. If the orderIds parameter is included in the request, this parameter will be ignored.

Maximum: 1000
Default: 50

Occurrence: Optional

offsetstringSpecifies the number of orders to skip in the result set before returning the first order in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.

Default: 0

Occurrence: Optional

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 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/sell.fulfillment

https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly

See OAuth access tokens for more information.

Output

HTTP response headers

{ /* OrderSearchPagedCollection */
"href" : "string",
"limit" : "integer",
"next" : "string",
"orders" : [
{ /* Order */
"buyer" :
{ /* Buyer */ },
"lineItems" : [
{ /* LineItem */
"sku" : "string",
"title" : "string",
}
],
"pricingSummary" :
{ /* PricingSummary */ },
}
],
"prev" : "string",
"total" : "integer",
}
Output container/fieldTypeDescription
hrefstringThe URI of the getOrders call request that produced the current page of the result set.

Occurrence: Conditional

limitintegerThe maximum number of orders returned per page of the result set. The limit value can be passed in as a query parameter, or if omitted, its value defaults to 50.

Note: If this is the last or only page of the result set, the page may contain fewer orders than the limit value. To determine the number of pages in a result set, divide the total value (total number of orders matching input criteria) by this limit value, and then round up to the next integer. For example, if the total value was 120 (120 total orders) and the limit value was 50 (show 50 orders per page), the total number of pages in the result set is three, so the seller would have to make three separate getOrders calls to view all orders matching the input criteria. Default: 50

Occurrence: Always

nextstringThe getOrders call URI to use if you wish to view the next page of the result set. For example, the following URI returns records 41 thru 50 from the collection of orders:

path/order?limit=10&offset=40

This field is only returned if there is a next page of results to view based on the current input criteria.

Occurrence: Conditional

offsetintegerThe number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

Occurrence: Always

ordersarray of OrderThis array contains one or more orders that are part of the current result set, that is controlled by the input criteria. The details of each order include information about the buyer, order history, shipping fulfillments, line items, costs, payments, and order fulfillment status.

By default, orders are returned according to creation date (oldest to newest), but the order will vary according to any filter that is set in request.

Occurrence: Always

orders.buyerBuyerThis container consists of information about the order's buyer. At this time, only the buyer's eBay user ID is returned, but it's possible that more buyer information can be added to this container in the future.

Occurrence: Always

orders.buyer.usernamestringThe buyer's eBay user ID.

Occurrence: Always

orders.buyerCheckoutNotesstringThis field contains any comments that the buyer left for the seller about the order during checkout process. This field is only returned if a buyer left comments at checkout time.

Occurrence: Conditional

orders.cancelStatusCancelStatusThis container consists of order cancellation information if a cancel request has been made. This container is always returned, and if no cancel request has been made, the cancelState field is returned with a value of NONE_REQUESTED, and an empty cancelRequests array is also returned.

Occurrence: Always

orders.cancelStatus.cancelledDatestringThe date and time the order was cancelled, if applicable. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

orders.cancelStatus.cancelRequestsarray of CancelRequestThis array contains details of one or more buyer requests to cancel the order.

For the getOrders call: This array is returned but is always empty.
For the getOrder call: This array is returned fully populated with information about any cancellation requests.

Occurrence: Always

orders.cancelStatus.cancelRequests.cancelCompletedDatestringThe date and time that the order cancellation was completed, if applicable. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the cancellation request has actually been approved by the seller.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

orders.cancelStatus.cancelRequests.cancelInitiatorstringThis string value indicates the party who made the initial cancellation request. Typically, either the 'Buyer' or 'Seller'. If a cancellation request has been made, this field should be returned.

Occurrence: Conditional

orders.cancelStatus.cancelRequests.cancelReasonstringThe reason why the cancelInitiator initiated the cancellation request. Cancellation reasons for a buyer might include 'order placed by mistake' or 'order won't arrive in time'. For a seller, a typical cancellation reason is 'out of stock'. If a cancellation request has been made, this field should be returned.

Occurrence: Conditional

orders.cancelStatus.cancelRequests.cancelRequestedDatestringThe date and time that the order cancellation was requested. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is returned for each cancellation request.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

orders.cancelStatus.cancelRequests.cancelRequestIdstringThe unique identifier of the order cancellation request. This field is returned for each cancellation request.

Occurrence: Conditional

orders.cancelStatus.cancelRequests.cancelRequestStateCancelRequestStateEnumThe current stage or condition of the cancellation request. This field is returned for each cancellation request.

Occurrence: Conditional

orders.cancelStatus.cancelStateCancelStateEnumThe state of the order with regard to cancellation. This field is always returned, and if there are no cancellation requests, a value of NONE_REQUESTED is returned.

Occurrence: Always

orders.creationDatestringThe date and time that the order was created. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

orders.ebayCollectAndRemitTaxbooleanThis field is only returned if true, and indicates that eBay will collect tax (US state-mandates sales tax or 'goods and services' tax in Australia or New Zealand) for at least one line item in the order, and remit the tax to the taxing authority of the buyer's residence. If this field is returned, the seller should search for one or more ebayCollectAndRemitTaxes containers at the line item level to get more information about the type of tax and the amount.

Occurrence: Conditional

orders.fulfillmentHrefsarray of stringThis array contains a list of one or more getShippingFulfillment call URIs that can be used to retrieve shipping fulfillments that have been set up for the order.

Occurrence: Conditional

orders.fulfillmentStartInstructionsarray of FulfillmentStartInstructionThis container consists of a set of specifications for fulfilling the order, including the type of fulfillment, shipping carrier and service, shipping address, and estimated delivery window. These instructions are derived from the buyer's and seller's eBay account preferences, the listing parameters, and the buyer's checkout selections. The seller can use them as a starting point for packaging, addressing, and shipping the order.

Note: Although this container is presented as an array, it currently returns only one set of fulfillment specifications. Additional array members will be supported in future functionality.

Occurrence: Always

orders.fulfillmentStartInstructions.destinationTimeZonestringThis field is reserved for internal or future use.

Occurrence: Conditional

orders.fulfillmentStartInstructions.ebaySupportedFulfillmentbooleanThis field is only returned if its value is true and indicates that the fulfillment will be shipped via eBay's Global Shipping Program.

For more information, see the Global Shipping Program help topic.

Occurrence: Conditional

orders.fulfillmentStartInstructions.finalDestinationAddressAddressThis container is only returned if the value of ebaySupportedFulfillment field is true.

This is the final destination address for a Global Shipping Program shipment, which is usually the buyer's home. Sellers should not ship directly to this address; instead they should ship this package to their international shipping provider's domestic warehouse. The international shipping provider is responsible for delivery to the final destination address.

For more information, see Addressing a Global Shipping Program Shipment.

Occurrence: Conditional

orders.fulfillmentStartInstructions.finalDestinationAddress.addressLine1stringThe first line of the street address.

Occurrence: Always

orders.fulfillmentStartInstructions.finalDestinationAddress.addressLine2stringThe second line of the street address. This field can be used for additional address information, such as a suite or apartment number. This field will be returned if defined for the shipping address.

Occurrence: Conditional

orders.fulfillmentStartInstructions.finalDestinationAddress.citystringThe city of the shipping destination.

Occurrence: Conditional

orders.fulfillmentStartInstructions.finalDestinationAddress.countryCodeCountryCodeEnumThe country of the shipping destination, represented as a two-letter ISO 3166-1 alpha-2 country code. For example, US represents the United States, and DE represents Germany.

Occurrence: Always

orders.fulfillmentStartInstructions.finalDestinationAddress.countystringThe county of the shipping destination. Counties typically, but not always, contain multiple cities or towns. This field is returned if known/available.

Occurrence: Conditional

orders.fulfillmentStartInstructions.finalDestinationAddress.postalCodestringThe postal code of the shipping destination. Usually referred to as Zip codes in the US. Most countries have postal codes, but not all. The postal code will be returned if applicable.

Occurrence: Conditional

orders.fulfillmentStartInstructions.finalDestinationAddress.stateOrProvincestringThe state or province of the shipping destination. Most countries have states or provinces, but not all. The state or province will be returned if applicable.

Occurrence: Conditional

orders.fulfillmentStartInstructions.fulfillmentInstructionsTypeFulfillmentInstructionsTypeThe enumeration value returned in this field indicates the method of fulfillment that will be used to deliver this set of line items (this package) to the buyer. This field will have a value of SHIP_TO if the ebaySupportedFulfillment field is returned with a value of true. See the FulfillmentInstructionsType definition for more information about different fulfillment types.

Occurrence: Always

orders.fulfillmentStartInstructions.maxEstimatedDeliveryDatestringThis is the estimated latest date that the fulfillment will be completed. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned if the value of the fulfillmentInstructionsType field is DIGITAL.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

orders.fulfillmentStartInstructions.minEstimatedDeliveryDatestringThis is the estimated earliest date that the fulfillment will be completed. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned if the value of the fulfillmentInstructionsType field is DIGITAL.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

orders.fulfillmentStartInstructions.pickupStepPickupStepThis container is only returned for In-Store Pickup orders, and it indicates the specific merchant's store where the buyer will pick up the order. The In-Store Pickup feature is supported in the US, Canada, UK, Germany, and Australia marketplaces.

Occurrence: Conditional

orders.fulfillmentStartInstructions.pickupStep.merchantLocationKeystringA merchant-defined unique identifier of the merchant's store where the buyer will pick up their In-Store Pickup order.

This field is always returned with the pickupStep container.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStepShippingStepThis container consists of shipping information for this fulfillment, including the shipping carrier, the shipping service option, and the shipment destination. This container is not returned if the value of the fulfillmentInstructionsType field is DIGITAL, or for In-Store Pickup orders.

For Click and Collect orders, the shipping destination will be a brick-and-mortar store where the buyer will pick up the order.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shippingCarrierCodestringThe unique identifier of the shipping carrier being used to ship the line item.

Note: The Trading API's GeteBayDetails call can be used to retrieve the latest shipping carrier and shipping service option enumeration values.

Occurrence: Always

orders.fulfillmentStartInstructions.shippingStep.shippingServiceCodestringThe unique identifier of the shipping service option being used to ship the line item.

Note: Use the Trading API's GeteBayDetails call to retrieve the latest shipping carrier and shipping service option enumeration values. When making the GeteBayDetails call, include the DetailName field in the request payload and set its value to ShippingServiceDetails. Each valid shipping service option (returned in ShippingServiceDetails.ShippingService field) and corresponding shipping carrier (returned in ShippingServiceDetails.ShippingCarrier field) is returned in response payload.

Occurrence: Always

orders.fulfillmentStartInstructions.shippingStep.shipToExtendedContactThis container consists of shipping and contact information about the individual or organization to whom the fulfillment package will be shipped.

Note: For a Global Shipping Program shipment, this is the address of the international shipping provider's domestic warehouse. The international shipping provider is responsible for delivery to the final destination address. For more information, see Addressing a Global Shipping Program Shipment.

Occurrence: Always

orders.fulfillmentStartInstructions.shippingStep.shipTo.companyNamestringThe company name associated with the buyer or eBay shipping partner. This field is only returned if defined/applicable to the buyer or eBay shipping partner.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shipTo.contactAddressAddressThis container either shows the shipping address of the buyer, the address of eBay's shipping partner (for international orders going through eBay's Global Shipping Program), or the address of a brick-and-mortar store where a buyer will pick up a Click and Collect order.

Occurrence: Always

orders.fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.addressLine1stringThe first line of the street address.

Occurrence: Always

orders.fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.addressLine2stringThe second line of the street address. This field can be used for additional address information, such as a suite or apartment number. This field will be returned if defined for the shipping address.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.citystringThe city of the shipping destination.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.countryCodeCountryCodeEnumThe country of the shipping destination, represented as a two-letter ISO 3166-1 alpha-2 country code. For example, US represents the United States, and DE represents Germany.

Occurrence: Always

orders.fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.countystringThe county of the shipping destination. Counties typically, but not always, contain multiple cities or towns. This field is returned if known/available.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.postalCodestringThe postal code of the shipping destination. Usually referred to as Zip codes in the US. Most countries have postal codes, but not all. The postal code will be returned if applicable.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.stateOrProvincestringThe state or province of the shipping destination. Most countries have states or provinces, but not all. The state or province will be returned if applicable.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shipTo.emailstringThis field shows the email address of the buyer. The email address of a buyer will only be shown for the first two weeks after order creation. Two weeks after order creation, this field will stop getting returned.

Note: This field will always show the email address of the buyer even with a Global Shipping Program shipment.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shipTo.fullNamestringThe full name of the buyer or eBay shipping partner.

Occurrence: Always

orders.fulfillmentStartInstructions.shippingStep.shipTo.primaryPhonePhoneNumberThe primary telephone number of the buyer or eBay shipping partner.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shipTo.primaryPhone.phoneNumberThe primary telephone number for the shipping recipient.

Occurrence: Conditional

orders.fulfillmentStartInstructions.shippingStep.shipToReferenceIdstringThis is the unique identifer of the Global Shipping Program (GSP) shipment. This field is only returned if the line item is being shipped via GSP (the value of the fulfillmentStartInstructions.ebaySupportedFulfillment field will be true. The international shipping provider uses the shipToReferenceId value as the primary reference number to retrieve the relevant details about the buyer, the order, and the fulfillment, so the shipment can be completed.

Sellers must include this value on the shipping label immediately above the street address of the international shipping provider.

Example: "Reference #1234567890123456"

Note: This value is the same as the ShipToAddress.ReferenceID value returned by the Trading API's GetOrders call.

Occurrence: Conditional

orders.lastModifiedDatestringThe date and time that the order was last modified. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

orders.legacyOrderIdstringThe unique identifier of the order in legacy format, as traditionally used by the Trading API (and other legacy APIs). Both the orderId field and this field are always returned.

Note: In June 2019, Order IDs in REST APIs transitioned to a new format. For the Trading and other legacy APIs, by using version control/compatibility level, users have the option of using the older legacy order ID format, or they can migrate to the new order ID format, which is the same order ID format being used by REST APIs. Although users of the Trading API (and other legacy APIs) can now transition to the new order ID format, this legacyOrderId field will still return order IDs in the old format to distinguish between the old and new order IDs.

Occurrence: Always

orders.lineItemsarray of LineItemThis array contains the details for all line items that comprise the order.

Occurrence: Always

orders.lineItems.appliedPromotionsarray of AppliedPromotionThis array contains information about one or more sales promotions or discounts applied to the line item. It is always returned, but will be returned as an empty array if no special sales promotions or discounts apply to the order line item.

Occurrence: Always

orders.lineItems.appliedPromotions.descriptionstringA description of the applied sales promotion.

Occurrence: Conditional

orders.lineItems.appliedPromotions.discountAmountAmountThe monetary amount of the sales promotion.

Occurrence: Conditional

orders.lineItems.appliedPromotions.discountAmount.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.appliedPromotions.discountAmount.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.appliedPromotions.discountAmount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.appliedPromotions.discountAmount.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.lineItems.appliedPromotions.promotionIdstringAn eBay-generated unique identifier of the sales promotion.

Multiple types of sales promotions are available to eBay Store owners, including order size/volume discounts, shipping discounts, special coupons, and price markdowns. Sales promotions can be managed through the Marketing tab of Seller Hub in My eBay, or by using the Trading API's SetPromotionalSale call or the Marketing API's createItemPromotion method.

Occurrence: Conditional

orders.lineItems.deliveryCostDeliveryCostThis container consists of a breakdown of all costs associated with the fulfillment of the line item.

Occurrence: Always

orders.lineItems.deliveryCost.importChargesAmountThe amount of any import charges applied to international shipping of the line item. This container is only returned if import charges apply to the line item.

Occurrence: Conditional

orders.lineItems.deliveryCost.importCharges.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.deliveryCost.importCharges.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.deliveryCost.importCharges.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.deliveryCost.importCharges.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.lineItems.deliveryCost.shippingCostAmountThe total cost of shipping all units of the line item. This container is always returned even when the shipping cost is free, in which case the value field will show 0.0 (dollars).

Occurrence: Always

orders.lineItems.deliveryCost.shippingCost.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.deliveryCost.shippingCost.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.deliveryCost.shippingCost.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.deliveryCost.shippingCost.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.lineItems.deliveryCost.shippingIntermediationFeeAmountThis field shows the fee due to eBay's international shipping provider for a line item that is being shipped through the Global Shipping Program. This container is only returned for line items being shipped internationally through the Global Shipping Program.

Occurrence: Conditional

orders.lineItems.deliveryCost.shippingIntermediationFee.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.deliveryCost.shippingIntermediationFee.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.deliveryCost.shippingIntermediationFee.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.deliveryCost.shippingIntermediationFee.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.lineItems.discountedLineItemCostAmountThe cost of the line item after applying any discounts. This container is only returned if the order line item was discounted through a promotion.

Occurrence: Conditional

orders.lineItems.discountedLineItemCost.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.discountedLineItemCost.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.discountedLineItemCost.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.discountedLineItemCost.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.lineItems.ebayCollectAndRemitTaxesarray of EbayCollectAndRemitTaxThis container will be returned if the order line item is subject to a 'Collect and Remit' tax that eBay will collect and remit to the proper taxing authority on the buyer's behalf. 'Collect and Remit' tax includes US state-mandated sales tax and 'Goods and Services' tax (collected in Australia and New Zealand). The amount of this tax is shown in the amount field, and the type of tax is shown in the taxType field.

eBay will display the tax type and amount during checkout in accordance with the buyer's address, and handle collection and remittance of the tax without requiring the seller to take any action.

Occurrence: Conditional

orders.lineItems.ebayCollectAndRemitTaxes.amountAmountThe monetary amount of the 'Collect and Remit' tax, which includes US state-mandated sales tax and 'Goods and Services' tax in Australia and New Zealand.

Note: If the corresponding taxType is GST or STATE_SALES_TAX and the lineItems.taxes container also appears for this line item with the same tax amount, the order is subject to 'eBay Collect and Remit' tax, and a change in logic is rolling out at the beginning of November 2019. For orders that are subject to 'eBay Collect and Remit' tax, the tax amount in this field will be included in the lineItems.total, paymentSummary.payments.amount, paymentSummary.totalDueSeller, and pricingSummary.total fields.

Sellers should be aware that the sales tax that the buyer pays for the order will initially be included when the order funds are distributed to their PayPal account, but that PayPal will pull out the sales tax amount shortly after the payment clears, and will distribute the sales tax to the appropriate taxing authority. Previous to this change, PayPal would strip out the 'Collect and Remit' tax before distributing order funds to the seller's account.

This logic change does not apply to sellers opted in to eBay managed payments, and any 'Collect and Remit' tax is fully handled by eBay, and the proceeds of this tax is never distributed through seller payouts. Also, for sellers opted in to eBay managed payments, the lineItems.taxes array is returned empty.

Occurrence: Conditional

orders.lineItems.ebayCollectAndRemitTaxes.amount.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.ebayCollectAndRemitTaxes.amount.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.ebayCollectAndRemitTaxes.amount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.ebayCollectAndRemitTaxes.amount.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.lineItems.ebayCollectAndRemitTaxes.taxTypeTaxTypeEnumThe type of tax that eBay will collect and remit to the taxing authority. See the TaxTypeEnum type definition for more information about each tax type.

Occurrence: Conditional

orders.lineItems.ebayCollectAndRemitTaxes.collectionMethodCollectionMethodEnumThis field indicates the collection method used to collect the 'Collect and Remit' tax for the order. This field is always returned for orders subject to 'Collect and Remit' tax, and its value is always NET.

Note: Although the collectionMethod field is returned for all orders subject to 'Collect and Remit' tax, the collectionMethod field and the CollectionMethodEnum type are not currently of any practical use, although this field may have use in the future. If and when the logic of this field is changed, this note will be updated and a note will also be added to the Release Notes.

Occurrence: Conditional

orders.lineItems.giftDetailsGiftDetailsThis container consists of information that is needed by the seller to send a digital gift card to the buyer, or recipient of the digital gift card. This container is only returned and applicable for digital gift card line items.

Occurrence: Conditional

orders.lineItems.giftDetails.messagestringThis field contains the gift message from the buyer to the gift recipient. This field is only returned if the buyer of the gift included a message for the gift.

Occurrence: Conditional

orders.lineItems.giftDetails.recipientEmailstringThe email address of the gift recipient. The seller will send the digital gift card to this email address.

Occurrence: Always

orders.lineItems.giftDetails.senderNamestringThe name of the buyer, which will appear on the email that is sent to the gift recipient.

Occurrence: Always

orders.lineItems.legacyItemIdstringThe eBay-generated legacy listing item ID of the listing. Note that the unique identifier of a listing in REST-based APIs is called the listingId instead.

Occurrence: Always

orders.lineItems.legacyVariationIdstringThe unique identifier of a single variation within a multiple-variation listing. This field is only returned if the line item purchased was from a multiple-variation listing.

Occurrence: Conditional

orders.lineItems.lineItemCostAmountThe selling price of the line item before applying any discounts. The value of this field is calculated by multiplying the single unit price by the number of units purchased (value of the quantity field).

Occurrence: Always

orders.lineItems.lineItemCost.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.lineItemCost.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.lineItemCost.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.lineItemCost.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.lineItems.lineItemFulfillmentInstructionsLineItemFulfillmentInstructionsThis container consists of information related to shipping dates and expectations, including the 'ship-by date' and expected delivery windows that are based on the seller's stated handling time and the shipping service option that will be used. These fields provide guidance on making sure expected delivery dates are made, whether the order is a eBay Guaranteed Delivery order or a non-guaranteed delivery order.

Occurrence: Always

orders.lineItems.lineItemFulfillmentInstructions.destinationTimeZonestringThis field is reserved for internal or future use.

Occurrence: Conditional

orders.lineItems.lineItemFulfillmentInstructions.guaranteedDeliverybooleanThis field is returned as true if the order line item is qualified for eBay Guaranteed Delivery, or false if it is not eligible. Only domestic shipments are available for eBay Guaranteed Delivery. At this time, eBay Guaranteed Delivery is only available to a select number of sellers on the US and Australia sites.

There are two different eBay Guaranteed Delivery options - 'Handling time' option and 'Door-to-Door' option. With both options, the seller is commiting to getting the order delivered to the buyer within three business days after purchase.

With the 'Handling time' option, the seller's stated handling time for a listing must be 'same-day' or '1-day', and at least one of the available shipping service options should have a shipping time that guarantees that the buyer receives the order on time. With this option, eBay will set the 'ship-by date' and expected delivery window for the seller, and the seller should just make sure they physically ship the order by the shipToDate.

With the 'Door-to-door' option, the seller must create regional shipping rate tables (with shipping costs and delivery times based on destination regions), and then apply these regional shipping rates/delivery times to the listing.

If a 'Door-to-door' order does not arrive on time, the seller must refund the buyer the full shipping cost (if any), and the buyer also has the option of returning the item for a full refund, and the seller will also have to pay the return shipping cost. With 'Handling time' option, as long as the seller meets the stated handling time, and ships using the correct shipping service option, eBay will refund the buyer the shipping cost and pay for return shipping label (if buyer wants to return item) if the order arrives after the expected delivery time.

For more information on the details and requirements of eBay Guaranteed Delivery, see the Offering eBay Guaranteed Delivery help topic.

This field will always be returned regardless of whether the listing site offers eBay Guaranteed Delivery or if the seller is opted in to the feature.

Occurrence: Always

orders.lineItems.lineItemFulfillmentInstructions.maxEstimatedDeliveryDatestringThe estimated latest date and time that the buyer can expect to receive the line item based on the seller's stated handling time and the transit times of the available shipping service options. If the listing is eligible for eBay Guaranteed Delivery (value of guaranteedDelivery field is true, the seller must pay extra attention to this date, as a failure to deliver by this date/time can result in a 'Late shipment' seller defect, and can affect seller level and Top-Rated Seller status. In addition to the seller defect, buyers will be eligible for a shipping cost refund, and will also be eligible to return the item for a full refund (with no return shipping charge) if they choose.

Note: This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

orders.lineItems.lineItemFulfillmentInstructions.minEstimatedDeliveryDatestringThe estimated earliest date and time that the buyer can expect to receive the line item based on the seller's stated handling time and the transit times of the available shipping service options.

Note: This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

orders.lineItems.lineItemFulfillmentInstructions.shipByDatestringThe latest date and time by which the seller should ship line item in order to meet the expected delivery window. This timestamp will be set by eBay based on time of purchase and the seller's stated handling time. If the listing is eligible for eBay Guaranteed Delivery (value of guaranteedDelivery field is true, the seller must pay extra attention to this date, as a failure to physically ship the line item by this date/time can result in a 'Late shipment' seller defect, and can affect seller level and Top-Rated Seller status. In addition to the seller defect, buyers will be eligible for a shipping cost refund, and will also be eligible to return the item for a full refund (with no return shipping charge) if they choose.

Note: This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

orders.lineItems.lineItemFulfillmentInstructions.sourceTimeZonestringThis field is reserved for internal or future use.

Occurrence: Conditional

orders.lineItems.lineItemFulfillmentStatusLineItemFulfillmentStatusEnumThis enumeration value indicates the current fulfillment status of the line item.

Occurrence: Always

orders.lineItems.lineItemIdstringThis is the unique identifier of an eBay order line item. This field is created as soon as there is a commitment to buy from the seller.

Occurrence: Always

orders.lineItems.listingMarketplaceIdMarketplaceIdEnumThe unique identifier of the eBay marketplace where the line item was listed.

Occurrence: Always

orders.lineItems.propertiesLineItemPropertiesContains information about the eBay programs, if any, under which the line item was listed.

Occurrence: Always

orders.lineItems.properties.buyerProtectionbooleanA value of true indicates that the line item is covered by eBay's Buyer Protection program.

Occurrence: Always

orders.lineItems.properties.fromBestOfferbooleanThis field is only returned if true and indicates that the purchase occurred by the buyer and seller mutually agreeing on a Best Offer amount. The Best Offer feature can be set up for any listing type, but if this feature is set up for an auction listing, it will no longer be available once a bid has been placed on the listing.

Occurrence: Conditional

orders.lineItems.properties.soldViaAdCampaignbooleanThis field is only returned if true and indicates that the line item was sold as a result of a seller's ad campaign.

Occurrence: Conditional

orders.lineItems.purchaseMarketplaceIdMarketplaceIdEnumThe unique identifier of the eBay marketplace where the line item was listed. Often, the listingMarketplaceId and the purchaseMarketplaceId identifier are the same, but there are occasions when an item will surface on multiple eBay marketplaces.

Occurrence: Always

orders.lineItems.quantityintegerThe number of units of the line item in the order. These are represented as a group by a single lineItemId.

Occurrence: Always

orders.lineItems.refundsarray of LineItemRefundThis array is always returned, but is returned as an empty array unless the seller has submitted a partial or full refund to the buyer for the order. If a refund has occurred, the refund amount and refund date will be shown for each refund.

Occurrence: Always

orders.lineItems.refunds.amountAmountThis field shows the refund amount for a line item. This field is only returned if the buyer is due a refund for the line item.

Occurrence: Conditional

orders.lineItems.refunds.amount.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.refunds.amount.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.refunds.amount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.refunds.amount.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.lineItems.refunds.refundDatestringThe date and time that the refund was issued for the line item. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the refund has been issued.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

orders.lineItems.refunds.refundIdstringUnique identifier of a refund that was initiated for an order's line item through the issueRefund method. If the issueRefund method was used to issue a refund at the order level, this identifier is returned at the order level instead (paymentSummary.refunds.refundId field).

A refundId value is returned in the response of the issueRefund method, and this same value will be returned in the getOrder and getOrders responses for pending and completed refunds. The issueRefund method can only be used for eBay managed payment orders.

Occurrence: Conditional

orders.lineItems.refunds.refundReferenceIdstringThis field is reserved for internal or future use.

Occurrence: Conditional

orders.lineItems.skustringSeller-defined Stock-Keeping Unit (SKU). This inventory identifier must be unique within the seller's eBay inventory. SKUs are optional when listing in the legacy/Trading API system, but SKUs are required when listing items through the Inventory API model.

Occurrence: Conditional

orders.lineItems.soldFormatSoldFormatEnumThe eBay listing type of the line item. The most common listing types are AUCTION and FIXED_PRICE.

Occurrence: Always

orders.lineItems.taxesarray of TaxContains a list of taxes applied to the line item, if any. This array is always returned, but will be returned as empty if no taxes are applicable to the line item, or if only eBay 'Collect and Remit' tax is applicable.

Occurrence: Always

orders.lineItems.taxes.amountAmountThe monetary amount of the tax. The taxes array is always returned for each line item in the order, but this amount container will only be returned when the line item is subject to any type of tax.

Occurrence: Conditional

orders.lineItems.taxes.amount.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.taxes.amount.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.taxes.amount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.taxes.amount.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.lineItems.titlestringThe title of the listing.

Occurrence: Always

orders.lineItems.totalAmountThis is the total price that the buyer must pay for the line item after all costs (item cost, delivery cost, taxes) are added, minus any discounts and/or promotions.

Note: Beginning in early November 2019, for orders that are subject to 'eBay Collect and Remit' tax, which includes US state-mandated sales tax and 'Good and Services' tax in Australia and New Zealand, the 'Collect and Remit' tax amount for the order will be included in this total value.

To determine if 'Collect and Remit' taxes were added into this total value, the user can check for the corresponding lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for this line item in the response with a taxType value of STATE_SALES_TAX (in US) or GST (in Australia or New Zealand), the 'Collect and Remit' tax amount that the buyer paid is in this amount.

Sellers should be aware that the 'Collect and Remit' tax that the buyer pays for the order will initially be included when the order funds are distributed to their PayPal account, but that PayPal will pull out the 'Collect and Remit' tax amount shortly after the payment clears, and will distribute the tax to the appropriate taxing authority. Previous to this change, PayPal would strip out the 'Collect and Remit' tax before distributing order funds to the seller's account.

This logic change does not apply to sellers who are in eBay managed payments, so the amount in this field will never reflect any 'Collect and Remit' tax, even if the order is subject to 'Collect and Remit' tax.

Occurrence: Always

orders.lineItems.total.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.lineItems.total.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.lineItems.total.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.lineItems.total.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.orderFulfillmentStatusOrderFulfillmentStatusThe degree to which fulfillment of the order is complete. See the OrderFulfillmentStatus type definition for more information about each possible fulfillment state.

Occurrence: Always

orders.orderIdstringThe unique identifier of the order. Both the legacyOrderId field (traditionally used by Trading and other legacy APIS) and this field are always returned.

Note: In June 2019, Order IDs in REST APIs transitioned to a new format. For the Trading and other legacy APIs, by using version control/compatibility level, users have the option of using the older legacy order ID format, or they can migrate to the new order ID format, which is the same order ID format being used by REST APIs. The new format is a non-parsable string, globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. These order identifiers are automatically generated after buyer payment, and unlike in the past, instead of just being known and exposed to the seller, these unique order identifiers will also be known and used/referenced by the buyer and eBay customer support.

Occurrence: Always

orders.orderPaymentStatusOrderPaymentStatusEnumThe enumeration value returned in this field indicates the current payment status of an order, or in case of a refund request, the current status of the refund. See the OrderPaymentStatusEnum type definition for more information about each possible payment/refund state.

Occurrence: Always

orders.paymentSummaryPaymentSummaryThis container consists of detailed payment information for the order, including buyer payment for the order, refund information (if applicable), and seller payment holds (if applicable).

Occurrence: Always

orders.paymentSummary.paymentsarray of PaymentThis array consists of payment information for the order, including payment status, payment method, payment amount, and payment date. This array is always returned, although some of the fields under this container will not be returned until payment has been made.

Occurrence: Always

orders.paymentSummary.payments.amountAmountThe total amount due from, or paid by the buyer for the order (depending on the payment status).

Note: Beginning in early November 2019, for orders that are subject to 'eBay Collect and Remit' tax, which includes US state-mandated sales tax and 'Good and Services' tax in Australia and New Zealand, the 'Collect and Remit' tax amount for the order will be included in this amount.value field (and in the amount.convertedFromValue field if currency conversion is applicable).

To determine if 'Collect and Remit' taxes were added into these amount fields, the user can check for the lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with a taxType value of STATE_SALES_TAX (in US) or GST (in Australia or New Zealand), the 'Collect and Remit' tax amount that the buyer paid are in these amounts.

Sellers should be aware that the 'Collect and Remit' tax that the buyer pays for the order will initially be included when the order funds are distributed to their PayPal account, but that PayPal will pull out the 'Collect and Remit' tax amount shortly after the payment clears, and will distribute the tax to the appropriate taxing authority. Previous to this change, PayPal would strip out the 'Collect and Remit' tax before distributing order funds to the seller's account.

This logic change does not apply to sellers who are in eBay managed payments, so the amount in this field will never reflect any 'Collect and Remit' tax, even if the order is subject to 'Collect and Remit' tax.

Occurrence: Always

orders.paymentSummary.payments.amount.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.paymentSummary.payments.amount.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.paymentSummary.payments.amount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.paymentSummary.payments.amount.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.paymentSummary.payments.paymentDatestringThe date and time that the payment was received by the seller. This field will not be returned if buyer has yet to pay for the order. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

orders.paymentSummary.payments.paymentHoldsarray of PaymentHoldThis container is only returned if eBay is temporarily holding the seller's funds for the order. If a payment hold has been placed on the order, this container includes the reason for the payment hold, the expected release date of the funds into the seller's account, the current state of the hold, and as soon as the payment hold has been released, the actual release date.

Occurrence: Conditional

orders.paymentSummary.payments.paymentHolds.expectedReleaseDatestringThe date and time that the payment being held is expected to be released to the seller. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field will be returned if known by eBay.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

orders.paymentSummary.payments.paymentHolds.holdAmountAmountThe monetary amount of the payment being held. This field is always returned with the paymentHolds array.

Occurrence: Conditional

orders.paymentSummary.payments.paymentHolds.holdAmount.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.paymentSummary.payments.paymentHolds.holdAmount.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.paymentSummary.payments.paymentHolds.holdAmount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.paymentSummary.payments.paymentHolds.holdAmount.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.paymentSummary.payments.paymentHolds.holdReasonstringThe reason that the payment is being held. A seller's payment may be helf for a number of reasons, including when the seller is new, the seller's level is below standard, or if a return case or 'Significantly not as described' case is pending against the seller. This field is always returned with the paymentHolds array.

Occurrence: Conditional

orders.paymentSummary.payments.paymentHolds.holdStatestringThe current stage or condition of the hold. This field is always returned with the paymentHolds array.

Applicable values:
  • HELD
  • HELD_PENDING
  • NOT_HELD
  • RELEASE_CONFIRMED
  • RELEASE_FAILED
  • RELEASE_PENDING
  • RELEASED

Occurrence: Conditional

orders.paymentSummary.payments.paymentHolds.releaseDatestringThe date and time that the payment being held was actually released to the seller. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the seller's payment is actually released into the seller's account.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

orders.paymentSummary.payments.paymentHolds.sellerActionsToReleasearray of SellerActionsToReleaseA list of one or more possible actions that the seller can take to expedite the release of the payment hold.

Occurrence: Conditional

orders.paymentSummary.payments.paymentHolds.sellerActionsToRelease.sellerActionToReleasestringA possible action that the seller can take to expedite the release of a payment hold. A sellerActionToRelease field is returned for each possible action that a seller may take. Possible actions may include providing shipping/tracking information, issuing a refund, providing refund information, contacting customer support, etc.

Occurrence: Conditional

orders.paymentSummary.payments.paymentMethodPaymentMethodTypeEnumThe payment method used by the buyer to pay for the order.

Occurrence: Always

orders.paymentSummary.payments.paymentReferenceIdstringThis field shows the unique identifier of the buyer's payment for the order.

Occurrence: Always

orders.paymentSummary.payments.paymentStatusPaymentStatusEnumThe enumeration value returned in this field indicates the status of the buyer's payment for the order. See the PaymentStatusEnum type definition for more information on the possible payment states.

Occurrence: Always

orders.paymentSummary.refundsarray of OrderRefundThis array is always returned, but is returned as an empty array unless the seller has submitted a partial or full refund to the buyer for the order. If a refund has occurred, the refund amount and refund date will be shown for each refund.

Occurrence: Always

orders.paymentSummary.refunds.amountAmountThe monetary amount of the refund. This container is always returned for each refund.

Occurrence: Conditional

orders.paymentSummary.refunds.amount.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.paymentSummary.refunds.amount.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.paymentSummary.refunds.amount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.paymentSummary.refunds.amount.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.paymentSummary.refunds.refundDatestringThe date and time that the refund was issued. This timestamp is in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. This field is not returned until the refund has been issued.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

orders.paymentSummary.refunds.refundIdstringUnique identifier of a refund that was initiated for an order through the issueRefund method. If the issueRefund method was used to issue one or more refunds at the line item level, these refund identifiers are returned at the line item level instead (lineItems.refunds.refundId field).

A refundId value is returned in the response of the issueRefund method, and this same value will be returned in the getOrders and getOrders responses for pending and completed refunds. The issueRefund method can only be used for eBay managed payment orders. For other refunds, see the refundReferenceId field.

Occurrence: Conditional

orders.paymentSummary.refunds.refundReferenceIdstringThe eBay-generated unique identifier for the refund. This field is not returned until the refund has been issued.

Occurrence: Conditional

orders.paymentSummary.refunds.refundStatusRefundStatusEnumThis enumeration value indicates the current status of the refund to the buyer. This container is always returned for each refund.

Occurrence: Conditional

orders.paymentSummary.totalDueSellerAmountThis is the total price that the buyer must pay for the entire order after all costs (item cost, delivery cost, taxes) are added for all line items, minus any discounts and/or promotions for any of the line items. Note that this value is subject to change before payment is actually made by the buyer (if the paymentStatus value was PENDING or FAILED), or if a partial or full refund occurs with the order.

Note: Beginning in early November 2019, for orders that are subject to 'eBay Collect and Remit' tax, which includes US state-mandated sales tax and 'Good and Services' tax in Australia and New Zealand, the 'Collect and Remit' tax amount for the order will be included in this totalDueSeller value.

To determine if 'Collect and Remit' taxes were added into this totalDueSeller value, the user can check for the lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with a taxType value of STATE_SALES_TAX (in US) or GST (in Australia or New Zealand), the 'Collect and Remit' tax amount that the buyer paid is in this amount.

Sellers should be aware that the 'Collect and Remit' tax that the buyer pays for the order will initially be included when the order funds are distributed to their PayPal account, but that PayPal will pull out the 'Collect and Remit' tax amount shortly after the payment clears, and will distribute the tax to the appropriate taxing authority. Previous to this change, PayPal would strip out the 'Collect and Remit' tax before distributing order funds to the seller's account.

This logic change does not apply to sellers who are in eBay managed payments, so the amount in this field will never reflect any 'Collect and Remit' tax, even if the order is subject to 'Collect and Remit' tax.

Occurrence: Always

orders.paymentSummary.totalDueSeller.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.paymentSummary.totalDueSeller.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.paymentSummary.totalDueSeller.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.paymentSummary.totalDueSeller.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.pricingSummaryPricingSummaryThis container consists of a summary of cumulative costs and charges for all line items of an order, including item price, price adjustments, sales taxes, delivery costs, and order discounts.

Occurrence: Always

orders.pricingSummary.adjustmentAmountThis container shows the total amount of any adjustments that were applied to the cost of the item(s) in the order. This amount does not include shipping, discounts, fixed fees, or taxes.

This container is only returned if price adjustments were made to the order after the initial transaction/commitment to buy occurred.

Occurrence: Conditional

orders.pricingSummary.adjustment.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.pricingSummary.adjustment.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.pricingSummary.adjustment.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.pricingSummary.adjustment.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.pricingSummary.deliveryCostAmountThis container shows the total cost of delivering the order to the buyer, before any shipping/delivery discount is applied.

Occurrence: Always

orders.pricingSummary.deliveryCost.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.pricingSummary.deliveryCost.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.pricingSummary.deliveryCost.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.pricingSummary.deliveryCost.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.pricingSummary.deliveryDiscountAmountThis container shows the total amount of delivery discounts (including shipping discounts) that apply to the order. This should be a negative real number.

This container is only returned if delivery discounts are being applied to the order.

Occurrence: Conditional

orders.pricingSummary.deliveryDiscount.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.pricingSummary.deliveryDiscount.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.pricingSummary.deliveryDiscount.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.pricingSummary.deliveryDiscount.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.pricingSummary.feeAmountThis container shows the total amount of any special fees applied to the order, such as a tire recycling fee or an electronic waste fee.

This container is only returned if special fees are being applied to the order.

Occurrence: Conditional

orders.pricingSummary.fee.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.pricingSummary.fee.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.pricingSummary.fee.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.pricingSummary.fee.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.pricingSummary.priceDiscountSubtotalAmountThis container shows the total amount of all item price discounts (including promotions) that apply to the order and reduce its cost to the buyer. This should be a negative real number.

This container is only returned if special discounts are being applied to the order.

Occurrence: Conditional

orders.pricingSummary.priceDiscountSubtotal.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.pricingSummary.priceDiscountSubtotal.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.pricingSummary.priceDiscountSubtotal.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.pricingSummary.priceDiscountSubtotal.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.pricingSummary.priceSubtotalAmountThis container shows the cumulative costs of of all units of all line items in the order, before any discount is applied.

Occurrence: Always

orders.pricingSummary.priceSubtotal.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.pricingSummary.priceSubtotal.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.pricingSummary.priceSubtotal.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.pricingSummary.priceSubtotal.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.pricingSummary.taxAmountThis container shows the total amount of tax for the order. To calculate the tax percentage rate, divide this value by the value of the total field.

This container is only returned if any type of tax (sales tax, tax on shipping, tax on handling, import tax, etc.) is applied to the order.

Occurrence: Conditional

orders.pricingSummary.tax.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.pricingSummary.tax.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.pricingSummary.tax.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.pricingSummary.tax.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.pricingSummary.totalAmountThe total cost of the order after adding all line item costs, delivery costs, sales tax, and special fees, and then subtracting all special discounts and price adjustments.

Note: Beginning in early November 2019, for orders that are subject to 'eBay Collect and Remit' tax, which includes US state-mandated sales tax and 'Good and Services' tax in Australia and New Zealand, the 'Collect and Remit' tax amount for the order will be included in this total value.

To determine if 'Collect and Remit' taxes were added into this total value, the user can check for the lineItems.ebayCollectAndRemitTaxes and the lineItems.taxes containers in the response. If both of these containers appear for one or more line items in the response with a taxType value of STATE_SALES_TAX (in US) or GST (in Australia or New Zealand), the 'Collect and Remit' tax amount that the buyer paid is in this amount.

Sellers should be aware that the 'Collect and Remit' tax that the buyer pays for the order will initially be included when the order funds are distributed to their PayPal account, but that PayPal will pull out the 'Collect and Remit' tax amount shortly after the payment clears, and will distribute the tax to the appropriate taxing authority. Previous to this change, PayPal would strip out the 'Collect and Remit' tax before distributing order funds to the seller's account.

This logic change does not apply to sellers who are in eBay managed payments, so the amount in this field will never reflect any 'Collect and Remit' tax, even if the order is subject to 'Collect and Remit' tax.

Occurrence: Always

orders.pricingSummary.total.convertedFromCurrencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the convertedFromValue field. This value is required or returned only if currency conversion/localization is required, and represents the pre-conversion currency.

Occurrence: Conditional

orders.pricingSummary.total.convertedFromValuestringThe monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is required or returned only if currency conversion/localization is required. The value field contains the converted amount of this value, in the currency specified by the currency field.

Occurrence: Conditional

orders.pricingSummary.total.currencyCurrencyCodeEnumA three-letter ISO 4217 code that indicates the currency of the amount in the value field. If currency conversion/localization is required, this is the post-conversion currency of the amount in the value field.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Always

orders.pricingSummary.total.valuestringThe monetary amount, in the currency specified by the currency field. If currency conversion/localization is required, this value is the converted amount, and the convertedFromValue field contains the amount in the original currency.

Required in the amount type.

Occurrence: Always

orders.salesRecordReferencestringAn eBay-generated identifier that is used to identify and manage orders through the Selling Manager and Selling Manager Pro tools. This order identifier can also be found on the Orders grid page and in the Sales Record pages in Seller Hub. A salesRecordReference number is only generated and returned at the order level, and not at the order line item level.

In cases where the seller does not have a Selling Manager or Selling Manager Pro subscription nor access to Seller Hub, this field may not be returned.

Occurrence: Conditional

orders.sellerIdstringThe unique eBay user ID of the seller who sold the order.

Occurrence: Always

prevstringThe getOrders call URI for the previous result set. For example, the following URI returns orders 21 thru 30 from the collection of orders:

path/order?limit=10&offset=20

This field is only returned if there is a previous page of results to view based on the current input criteria.

Occurrence: Conditional

totalintegerThe total number of orders in the results set based on the current input criteria.

Note: If no orders are found, this field is returned with a value of 0.

Occurrence: Always

warningsarray of ErrorDetailV3This array is returned if one or more errors or warnings occur with the call request.

Occurrence: Conditional

warnings.categorystringThe context or source of this error or warning.

Occurrence: Conditional

warnings.domainstringThe name of the domain containing the service or application. For example, sell is a domain.

Occurrence: Conditional

warnings.errorIdintegerA positive integer that uniquely identifies the specific error condition that occurred. Your application can use these values as error code identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.inputRefIdsarray of stringA list of one or more specific request elements (if any) associated with the error or warning. The format of these strings depends on the request payload format. For JSON, use JSONPath notation.

Occurrence: Conditional

warnings.longMessagestringAn expanded version of the message field.

Maximum length: 200 characters

Occurrence: Conditional

warnings.messagestringA message about the error or warning which is device agnostic and readable by end users and application developers. It explains what the error or warning is, and how to fix it (in a general sense). If applicable, the value is localized to the end user's requested locale.

Maximum length: 50 characters

Occurrence: Conditional

warnings.outputRefIdsarray of stringA list of one or more specific response elements (if any) associated with the error or warning. The format of these strings depends on the request payload format. For JSON, use JSONPath notation.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3Contains a list of name/value pairs that provide additional information concerning this error or warning. Each item in the list is an input parameter that contributed to the error or warning condition.

Occurrence: Conditional

warnings.parameters.namestringThis is the name of input field that caused an issue with the call request.

Occurrence: Conditional

warnings.parameters.valuestringThis is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

warnings.subdomainstringThe name of the domain's subsystem or subdivision. For example, fulfillment is a subdomain in the sell domain.

Occurrence: Conditional

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
200Success
400Bad Request
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
30500API_FULFILLMENTAPPLICATIONSystem error
30700API_FULFILLMENTREQUESTInvalid filter name: {<i>fieldname</i>}
30800API_FULFILLMENTREQUESTInvalid filter value {<i>fieldvalue</i>} for filter {<i>fieldname</i>}
30810API_FULFILLMENTREQUESTInvalid date format
30820API_FULFILLMENTREQUESTStart date is missing
30830API_FULFILLMENTREQUESTStart date must be within 90 days of end date and current date.
30840API_FULFILLMENTREQUESTStart date should be before end date
30850API_FULFILLMENTREQUESTStart and end dates can't be in the future
30900API_FULFILLMENTREQUESTExceeded maximum number of order IDs (the current limit is <code>50</code>)
31000API_FULFILLMENTREQUESTInvalid offset: {<i>offsetvalue</i>}
31100API_FULFILLMENTREQUESTInvalid limit: {<i>limitvalue</i>}

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: Search for Your Orders

This sample retrieves all of a seller's orders created after the specified date.

Input

Use the filter=creationdate parameter to filter by creation date range. You can optionally include limit and offset parameters to paginate the returned collection.
GET
https://api.ebay.com/sell/fulfillment/v1/order?filter=creationdate:%5B2016-09-29T15:05:43.026Z..%5D&limit=50&offset=0

Output

A successful call returns the OrderSearchPagedCollection container with one or more orders objects.