Skip to main content

GET/order/{orderId}

Use this call to retrieve the contents of an order based on its unique identifier, orderId. This value was returned in the getOrders call's orders.orderId field when you searched for orders by creation date, modification date, or fulfillment status. Include the optional fieldGroups query parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees.

The returned Order object contains 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
  • A summary of applied taxes and fees, and optionally a breakdown of each

Input

Resource URI

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

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

ParameterTypeDescription
orderIdstringThis path parameter is used to specify the unique identifier of the order being retrieved.

Use the getOrders method to retrieve order IDs. Order ID values are also shown in My eBay/Seller Hub.

Note: getOrders can return orders up to two years old. Do not provide the orderId for an order created more than two years in the past.

Occurrence: Required

fieldGroupsarray of stringThis parameter lets you control what is returned in the response.

Note: The only presently supported value is TAX_BREAKDOWN. This field group adds addition fields to the response that return a breakdown of taxes and fees.

Occurrence: Optional

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.

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.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

{ /* Order */
"fulfillmentStartInstructions" : [],
"lineItems" : [
{ /* LineItem */
"sku" : "string",
"title" : "string",
}
],
"pricingSummary" :
{ /* PricingSummary */ },
}

Response fields

Output container/fieldTypeDescription
buyerBuyer

This 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

buyer.buyerRegistrationAddressExtendedContact

Buyer's contact information that includes the buyer's name, email, phone number, and address.

Occurrence: Always

buyer.buyerRegistrationAddress.companyNamestring

The 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

buyer.buyerRegistrationAddress.contactAddressAddress

This container shows the shipping address of the buyer or eBay shipping partner.

Occurrence: Always

buyer.buyerRegistrationAddress.contactAddress.addressLine1string

The first line of the street address.

Note: addressLine1 will not be returned for any order that is more than 90 days old.

Occurrence: Always

buyer.buyerRegistrationAddress.contactAddress.addressLine2string

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

Note: addressLine2 will not be returned for any order that is more than 90 days old.
Note: As of January 31, 2022, addressLine2 no longer returns EU VAT tax information. To determine line-item level VAT tax information, refer to eBayReference.

Occurrence: Conditional

buyer.buyerRegistrationAddress.contactAddress.citystring

The city of the shipping destination.

Occurrence: Always

buyer.buyerRegistrationAddress.contactAddress.countryCodeCountryCodeEnum

The 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

buyer.buyerRegistrationAddress.contactAddress.countystring

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

Occurrence: Conditional

buyer.buyerRegistrationAddress.contactAddress.postalCodestring

The 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

buyer.buyerRegistrationAddress.contactAddress.stateOrProvincestring

The 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

buyer.buyerRegistrationAddress.emailstring

This field contains the email address of the buyer. This address will be returned for up to 14 days from order creation. If an order is more than 14 days old, no address is returned.

Note: If returned, this field contains the email address of the buyer, even for Global Shipping Program shipments.

The email will not be returned for any order that is more than 90 days old.

Occurrence: Conditional

buyer.buyerRegistrationAddress.fullNamestring

The full name of the buyer or eBay shipping partner.

Note: The fullName will not be returned for any order that is more than 90 days old.

Occurrence: Always

buyer.buyerRegistrationAddress.primaryPhonePhoneNumber

The primary telephone number of the buyer or eBay shipping partner.

Note: The primaryPhone will not be returned for any order that is more than 90 days old.

Occurrence: Conditional

buyer.buyerRegistrationAddress.primaryPhone.phoneNumberstring

The primary telephone number for the shipping recipient.

Occurrence: Always

buyer.taxAddressTaxAddress

This container consists of address information that can be used by sellers for tax purpose.

Note: When using the eBay vault program, if an item is shipped to a vault, the tax address will be the vault address.

Occurrence: Always

buyer.taxAddress.citystring

The city name that can be used by sellers for tax purpose.

Occurrence: Conditional

buyer.taxAddress.countryCodeCountryCodeEnum

The country code that can be used by sellers for tax purpose, represented as a two-letter ISO 3166-1 alpha-2 country code. For example, US represents the United States, and DE represents Germany.

Occurrence: Conditional

buyer.taxAddress.postalCodestring

The postal code that can be used by sellers for tax purpose. Usually referred to as Zip codes in the US.

Occurrence: Conditional

buyer.taxAddress.stateOrProvincestring

The state name that can be used by sellers for tax purpose.

Occurrence: Conditional

buyer.taxIdentifierTaxIdentifier

This container consists of taxpayer identification information for buyers from Italy, Spain, or Guatemala. It is currently only returned for orders occurring on the eBay Italy or eBay Spain marketplaces.

Note: Currently, the taxIdentifier container is only returned in getOrder and not in getOrders. So, if a seller wanted to view a buyer's tax information for a particular order returned in getOrders, that seller would need to use the orderId value for that particular order, and then run a getOrder call against that order ID.

Occurrence: Conditional

buyer.taxIdentifier.taxpayerIdstring

This value is the unique tax ID associated with the buyer. The type of tax identification is shown in the taxIdentifierType field.

Occurrence: Conditional

buyer.taxIdentifier.taxIdentifierTypeTaxIdentifierTypeEnum

This enumeration value indicates the type of tax identification being used for the buyer. The different tax types are defined in the TaxIdentifierTypeEnum type.

Occurrence: Conditional

buyer.taxIdentifier.issuingCountryCountryCodeEnum

This two-letter code indicates the country that issued the buyer's tax ID. The country that the two-letter code represents can be found in the CountryCodeEnum type, or in the ISO 3166 standard.

Occurrence: Conditional

buyer.usernamestring

The buyer's eBay user ID.

Occurrence: Always

buyerCheckoutNotesstring

This 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

cancelStatusCancelStatus

This 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

cancelStatus.cancelledDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

cancelStatus.cancelRequestsarray of CancelRequest

This 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

cancelStatus.cancelRequests.cancelCompletedDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

cancelStatus.cancelRequests.cancelInitiatorstring

This 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

cancelStatus.cancelRequests.cancelReasonstring

The 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

cancelStatus.cancelRequests.cancelRequestedDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

cancelStatus.cancelRequests.cancelRequestIdstring

The unique identifier of the order cancellation request. This field is returned for each cancellation request.

Occurrence: Conditional

cancelStatus.cancelRequests.cancelRequestStateCancelRequestStateEnum

The current stage or condition of the cancellation request. This field is returned for each cancellation request.

Occurrence: Conditional

cancelStatus.cancelStateCancelStateEnum

The 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

creationDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

ebayCollectAndRemitTaxboolean

This field is only returned if true, and indicates that eBay will collect tax (US state-mandated sales tax, Federal and Provincial Sales Tax in Canada, 'Goods and Services' tax in Canada, Australia, and New Zealand, and VAT collected for UK and EU countries,) 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

fulfillmentHrefsarray of string

This 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

fulfillmentStartInstructionsarray of FulfillmentStartInstruction

This 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

fulfillmentStartInstructions.appointmentAppointmentDetails

This container provides information used by the installation provider concerning appointment details selected by the buyer.

Occurrence: Conditional

fulfillmentStartInstructions.appointment.appointmentEndTimestring

The date and time the appointment ends, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Required for tire installation.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2022-10-28T00:00:00.000Z

Occurrence: Conditional

fulfillmentStartInstructions.appointment.appointmentStartTimestring

The date and time the appointment begins, formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2022-10-28T00:10:00.000Z

Occurrence: Conditional

fulfillmentStartInstructions.appointment.appointmentStatusAppointmentStatusEnum

The status of the appointment.

Occurrence: Conditional

fulfillmentStartInstructions.appointment.appointmentTypeAppointmentTypeEnum

The type of appointment. MACRO appointments only have a start time (not bounded with end time). TIME_SLOT appointments have a period (both start time and end time). Required for tire installation.

Occurrence: Conditional

fulfillmentStartInstructions.appointment.appointmentWindowAppointmentWindowEnum

Appointment window for MACRO appointments.

Occurrence: Conditional

fulfillmentStartInstructions.appointment.serviceProviderAppointmentDatestring

Service provider date of the appointment (no time stamp). Returned only for MACRO appointment types.

Occurrence: Conditional

fulfillmentStartInstructions.destinationTimeZonestring

This field is reserved for internal or future use.

Occurrence: Conditional

fulfillmentStartInstructions.ebaySupportedFulfillmentboolean

This field is only returned if its value is true and indicates that the fulfillment will be shipped via eBay's Global Shipping Program, eBay International Shipping, or the Authenticity Guarantee service program.

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

Occurrence: Conditional

fulfillmentStartInstructions.finalDestinationAddressAddress

This container is only returned if the value of ebaySupportedFulfillment field is true.

This is the final destination address for a Global Shipping Program shipment or an eBay International Shipping shipment, which is usually the recipient'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 Shipments.

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

Occurrence: Conditional

fulfillmentStartInstructions.finalDestinationAddress.addressLine1string

The first line of the street address.

Note: addressLine1 will not be returned for any order that is more than 90 days old.

Occurrence: Always

fulfillmentStartInstructions.finalDestinationAddress.addressLine2string

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

Note: addressLine2 will not be returned for any order that is more than 90 days old.
Note: As of January 31, 2022, addressLine2 no longer returns EU VAT tax information. To determine line-item level VAT tax information, refer to eBayReference.

Occurrence: Conditional

fulfillmentStartInstructions.finalDestinationAddress.citystring

The city of the shipping destination.

Occurrence: Always

fulfillmentStartInstructions.finalDestinationAddress.countryCodeCountryCodeEnum

The 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

fulfillmentStartInstructions.finalDestinationAddress.countystring

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

Occurrence: Conditional

fulfillmentStartInstructions.finalDestinationAddress.postalCodestring

The 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

fulfillmentStartInstructions.finalDestinationAddress.stateOrProvincestring

The 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

fulfillmentStartInstructions.fulfillmentInstructionsTypeFulfillmentInstructionsType

The 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

fulfillmentStartInstructions.maxEstimatedDeliveryDatestring

This 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 ifthe value of the fulfillmentInstructionsType field is DIGITAL or PREPARE_FOR_PICKUP.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

fulfillmentStartInstructions.minEstimatedDeliveryDatestring

This 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 or PREPARE_FOR_PICKUP.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

fulfillmentStartInstructions.pickupStepPickupStep

This 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

fulfillmentStartInstructions.pickupStep.merchantLocationKeystring

A 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

fulfillmentStartInstructions.shippingStepShippingStep

This 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

fulfillmentStartInstructions.shippingStep.shippingCarrierCodestring

The 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

fulfillmentStartInstructions.shippingStep.shippingServiceCodestring

The 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

fulfillmentStartInstructions.shippingStep.shipToExtendedContact

This container consists of shipping and contact information about the individual or organization to whom the fulfillment package will be shipped.
Note: When FulfillmentInstructionsType is FULFILLED_BY_EBAY, there will be no shipTo address displayed.
Note: For Digitally Delivered Goods (DDG), this address is the same as the Buyer's Registration Address.
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 Shipments.

Occurrence: Always

fulfillmentStartInstructions.shippingStep.shipTo.companyNamestring

The 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

fulfillmentStartInstructions.shippingStep.shipTo.contactAddressAddress

This container shows the shipping address of the buyer or eBay shipping partner.

Occurrence: Always

fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.addressLine1string

The first line of the street address.

Note: addressLine1 will not be returned for any order that is more than 90 days old.

Occurrence: Always

fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.addressLine2string

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

Note: addressLine2 will not be returned for any order that is more than 90 days old.
Note: As of January 31, 2022, addressLine2 no longer returns EU VAT tax information. To determine line-item level VAT tax information, refer to eBayReference.

Occurrence: Conditional

fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.citystring

The city of the shipping destination.

Occurrence: Always

fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.countryCodeCountryCodeEnum

The 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

fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.countystring

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

Occurrence: Conditional

fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.postalCodestring

The 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

fulfillmentStartInstructions.shippingStep.shipTo.contactAddress.stateOrProvincestring

The 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

fulfillmentStartInstructions.shippingStep.shipTo.emailstring

This field contains the email address of the buyer. This address will be returned for up to 14 days from order creation. If an order is more than 14 days old, no address is returned.

Note: If returned, this field contains the email address of the buyer, even for Global Shipping Program shipments.

The email will not be returned for any order that is more than 90 days old.

Occurrence: Conditional

fulfillmentStartInstructions.shippingStep.shipTo.fullNamestring

The full name of the buyer or eBay shipping partner.

Note: The fullName will not be returned for any order that is more than 90 days old.

Occurrence: Always

fulfillmentStartInstructions.shippingStep.shipTo.primaryPhonePhoneNumber

The primary telephone number of the buyer or eBay shipping partner.

Note: The primaryPhone will not be returned for any order that is more than 90 days old.

Occurrence: Conditional

fulfillmentStartInstructions.shippingStep.shipTo.primaryPhone.phoneNumberstring

The primary telephone number for the shipping recipient.

Occurrence: Always

fulfillmentStartInstructions.shippingStep.shipToReferenceIdstring

This 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

lastModifiedDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

legacyOrderIdstring

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

Occurrence: Always

lineItemsarray of LineItem

This array contains the details for all line items that comprise the order.

Occurrence: Always

lineItems.appliedPromotionsarray of AppliedPromotion

This 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

lineItems.appliedPromotions.descriptionstring

A description of the applied sales promotion.

Occurrence: Conditional

lineItems.appliedPromotions.discountAmountAmount

The monetary amount of the sales promotion.

Occurrence: Conditional

lineItems.appliedPromotions.discountAmount.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.appliedPromotions.discountAmount.convertedFromValuestring

The 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

lineItems.appliedPromotions.discountAmount.currencyCurrencyCodeEnum

A 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

lineItems.appliedPromotions.discountAmount.valuestring

The 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

lineItems.appliedPromotions.promotionIdstring

An 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

lineItems.deliveryCostDeliveryCost

This container consists of a breakdown of all costs associated with the fulfillment of the line item.

Occurrence: Always

lineItems.deliveryCost.discountAmountAmount

The amount of any shipping discount that has been applied to the line item. This container is returned only if a shipping discount applies to the line item.

Occurrence: Conditional

lineItems.deliveryCost.handlingCostAmount

The amount of any handing cost that has been applied to the line item. This container is returned only if a handling cost applies to the line item.

Occurrence: Conditional

lineItems.deliveryCost.importChargesAmount

The 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

lineItems.deliveryCost.importCharges.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.deliveryCost.importCharges.convertedFromValuestring

The 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

lineItems.deliveryCost.importCharges.currencyCurrencyCodeEnum

A 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

lineItems.deliveryCost.importCharges.valuestring

The 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

lineItems.deliveryCost.shippingCostAmount

The 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

lineItems.deliveryCost.shippingCost.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.deliveryCost.shippingCost.convertedFromValuestring

The 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

lineItems.deliveryCost.shippingCost.currencyCurrencyCodeEnum

A 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

lineItems.deliveryCost.shippingCost.valuestring

The 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

lineItems.deliveryCost.shippingIntermediationFeeAmount

This 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, which is currently only supported in the US and UK marketplaces.

Note: The value returned for this field will always be 0.0 for line items sold in the UK marketplace.

Occurrence: Conditional

lineItems.deliveryCost.shippingIntermediationFee.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.deliveryCost.shippingIntermediationFee.convertedFromValuestring

The 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

lineItems.deliveryCost.shippingIntermediationFee.currencyCurrencyCodeEnum

A 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

lineItems.deliveryCost.shippingIntermediationFee.valuestring

The 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

lineItems.discountedLineItemCostAmount

The 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

lineItems.discountedLineItemCost.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.discountedLineItemCost.convertedFromValuestring

The 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

lineItems.discountedLineItemCost.currencyCurrencyCodeEnum

A 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

lineItems.discountedLineItemCost.valuestring

The 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

lineItems.ebayCollectAndRemitTaxesarray of EbayCollectAndRemitTax

This 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
  • Federal and Provincial Sales Tax in Canada
  • 'Goods and Services' tax in Canada, Australia, New Zealand, and Jersey
  • VAT collected for the UK, EU countries, Kazakhstan, and Belarus
  • Sales & Service Tax (SST) in Malaysia
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

lineItems.ebayCollectAndRemitTaxes.amountAmount

The monetary amount of the 'Collect and Remit' tax. This currently includes:

  • US state-mandated sales tax
  • Federal and Provincial Sales Tax in Canada
  • 'Goods and Services' tax in Canada, Australia, New Zealand, and Jersey
  • VAT collected for the UK, EU countries, Kazakhstan, and Belarus
  • Sales & Service Tax (SST) in Malaysia


Note: If the corresponding taxType is STATE_SALES_TAX, PROVINCE_SALES_TAX, GST, VAT, or SST 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. 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.

Occurrence: Conditional

lineItems.ebayCollectAndRemitTaxes.amount.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.ebayCollectAndRemitTaxes.amount.convertedFromValuestring

The 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

lineItems.ebayCollectAndRemitTaxes.amount.currencyCurrencyCodeEnum

A 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

lineItems.ebayCollectAndRemitTaxes.amount.valuestring

The 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

lineItems.ebayCollectAndRemitTaxes.ebayReferenceEbayTaxReference

This container field describes the line-item level VAT tax details.

Note: As of January 31, 2022, addressLine2 no longer returns EU VAT tax information.

Occurrence: Conditional

lineItems.ebayCollectAndRemitTaxes.ebayReference.namestring

This field value is returned to indicate the VAT tax type, which will vary by country/region. This string value will be one of the following:

  • ABN: if this string is returned, the ID in the value field is an Australia tax ID
  • DDG: if this string is returned, it indicates that tax has been collected and remitted for Digitally Delivered Goods (DDG)
  • IOSS: if this string is returned, the ID in the value field is an eBay EU or UK IOSS number
  • IRD: if this string is returned, the ID in the value field is an eBay New Zealand tax ID
  • SST: if this string is returned, the ID in the value field is an eBay Malaysia taxNumber
  • OSS: if this string is returned, the ID in the value field is an eBay Germany VAT ID
  • VOEC: if this string is returned, the ID in the value field is an eBay Norway tax ID

Occurrence: Conditional

lineItems.ebayCollectAndRemitTaxes.ebayReference.valuestring

The value returned in this field is the VAT identifier number (VATIN), which will vary by country/region. This field will be returned if VAT tax is applicable for the order. The name field indicates the VAT tax type, which will vary by country/region:

  • ABN: eBay AU tax ID
  • IOSS: eBay EU IOSS number / eBay UK IOSS number
  • IRD: eBay NZ tax ID
  • OSS: eBay DE VAT ID
  • SST: eBay MY taxNumber
  • VOEC: eBay NO number

Occurrence: Conditional

lineItems.ebayCollectAndRemitTaxes.taxTypeTaxTypeEnum

The type of tax and fees that eBay will collect and remit to the taxing or fee authority. See the TaxTypeEnum type definition for more information about each tax or fee type.

Occurrence: Conditional

lineItems.ebayCollectAndRemitTaxes.collectionMethodCollectionMethodEnum

This 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

lineItems.ebayCollectedChargesEbayCollectedCharges

This container consists of a breakdown of costs that are collected by eBay from the buyer for this order.

Note: Currently, this container is returned only if eBay is directly charging the buyer for eBay shipping.

Occurrence: Conditional

lineItems.ebayCollectedCharges.ebayShippingAmount

This container consists of costs related to eBay Shipping collected by eBay from the buyer of this order.

Occurrence: Conditional

lineItems.ebayCollectedCharges.ebayShipping.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.ebayCollectedCharges.ebayShipping.convertedFromValuestring

The 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

lineItems.ebayCollectedCharges.ebayShipping.currencyCurrencyCodeEnum

A 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

lineItems.ebayCollectedCharges.ebayShipping.valuestring

The 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

lineItems.giftDetailsGiftDetails

This 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

lineItems.giftDetails.messagestring

This 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.

Note: The message will not be returned for any order that is more than 90 days old.

Occurrence: Conditional

lineItems.giftDetails.recipientEmailstring

The email address of the gift recipient. The seller will send the digital gift card to this email address.

Note: The recipientEmail will not be returned for any order that is more than 90 days old.

Occurrence: Conditional

lineItems.giftDetails.senderNamestring

The name of the buyer, which will appear on the email that is sent to the gift recipient.

Note: The senderName will not be returned for any order that is more than 90 days old.

Occurrence: Conditional

lineItems.itemLocationItemLocation

This container field describes the physical location of the order line item.

Occurrence: Conditional

lineItems.itemLocation.countryCodeCountryCodeEnum

The two-letter ISO 3166 code representing the country of the address.

Occurrence: Conditional

lineItems.itemLocation.locationstring

Indicates the geographical location of the item (along with the value in the countryCode field). This field provides city, province, state, or similar information.

Occurrence: Conditional

lineItems.itemLocation.postalCodestring

The postal code of the address.

Occurrence: Conditional

lineItems.legacyItemIdstring

The 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

lineItems.legacyVariationIdstring

The 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

lineItems.lineItemCostAmount

The 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

lineItems.lineItemCost.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.lineItemCost.convertedFromValuestring

The 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

lineItems.lineItemCost.currencyCurrencyCodeEnum

A 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

lineItems.lineItemCost.valuestring

The 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

lineItems.lineItemFulfillmentInstructionsLineItemFulfillmentInstructions

This 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

lineItems.lineItemFulfillmentInstructions.destinationTimeZonestring

This field is reserved for internal or future use.

Occurrence: Conditional

lineItems.lineItemFulfillmentInstructions.guaranteedDeliveryboolean

Although this field is still returned, it can be ignored since eBay Guaranteed Delivery is no longer a supported feature on any marketplace. This field may get removed from the schema in the future.

Occurrence: Always

lineItems.lineItemFulfillmentInstructions.maxEstimatedDeliveryDatestring

The 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. 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

lineItems.lineItemFulfillmentInstructions.minEstimatedDeliveryDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

lineItems.lineItemFulfillmentInstructions.shipByDatestring

The 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. 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Always

lineItems.lineItemFulfillmentInstructions.sourceTimeZonestring

This field is reserved for internal or future use.

Occurrence: Conditional

lineItems.lineItemFulfillmentStatusLineItemFulfillmentStatusEnum

This enumeration value indicates the current fulfillment status of the line item.

Occurrence: Always

lineItems.lineItemIdstring

This 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

lineItems.linkedOrderLineItemsarray of LinkedOrderLineItem

An array of one or more line items related to the corresponding order, but not a part of that order. Details include the order ID, line item ID, and title of the linked line item, the seller of that item, item specifics, estimated delivery times, and shipment tracking (if available).

Occurrence: Conditional

lineItems.linkedOrderLineItems.lineItemAspectsarray of NameValuePair

This array contains the complete set of items aspects for the linked line item. For example:

"lineItemAspects": [
{
"name": "Tire Type",
"value": "All Season"
},

...

{
"name": "Car Type",
"value": "Performance"
}
]
Note: All item specifics for the listing are returned. The name/value pairs returned are in the language of the linked line item's listing site, which may vary from the seller's language.

Occurrence: Conditional

lineItems.linkedOrderLineItems.lineItemAspects.namestring

The text representing the name of the aspect for the name-value pair. For example, color, or Tire Type.

Occurrence: Conditional

lineItems.linkedOrderLineItems.lineItemAspects.valuestring

The value of the aspect for the name-value pair. For example, red, or All Season.

Occurrence: Conditional

lineItems.linkedOrderLineItems.lineItemIdstring

The unique identifier of the linked order line item.

Occurrence: Conditional

lineItems.linkedOrderLineItems.maxEstimatedDeliveryDatestring

The end of the date range in which the linked line item is expected to be delivered to the shipping address.

Occurrence: Conditional

lineItems.linkedOrderLineItems.minEstimatedDeliveryDatestring

The beginning of the date range in which the linked line item is expected to be delivered to the shipping address.

Occurrence: Conditional

lineItems.linkedOrderLineItems.orderIdstring

The unique identifier of the order to which the linked line item belongs.

Occurrence: Conditional

lineItems.linkedOrderLineItems.sellerIdstring

The eBay user ID of the seller who sold the linked line item. For example, the user ID of the tire seller.

Occurrence: Conditional

lineItems.linkedOrderLineItems.shipmentsarray of TrackingInfo

An array containing any shipment tracking information available for the linked line item.

Occurrence: Conditional

lineItems.linkedOrderLineItems.shipments.shipmentTrackingNumberstring

This string value represents the shipment tracking number of the package.

Occurrence: Conditional

lineItems.linkedOrderLineItems.shipments.shippingCarrierCodestring

This string value represents the shipping carrier used to ship the package.

Occurrence: Conditional

lineItems.linkedOrderLineItems.titlestring

The listing title of the linked line item.

Note: The Item ID value for the listing will be returned in this field instead of the actual title if this particular listing is on-hold due to an eBay policy violation.

Occurrence: Conditional

lineItems.listingMarketplaceIdMarketplaceIdEnum

The unique identifier of the eBay marketplace where the line item was listed.

Occurrence: Always

lineItems.propertiesLineItemProperties

Contains information about the eBay programs, if any, under which the line item was listed.

Occurrence: Always

lineItems.properties.buyerProtectionboolean

A value of true indicates that the line item is covered by eBay's Buyer Protection program.

Occurrence: Always

lineItems.properties.fromBestOfferboolean

This 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

lineItems.properties.soldViaAdCampaignboolean

This 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

lineItems.purchaseMarketplaceIdMarketplaceIdEnum

The 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

lineItems.quantityinteger

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

Occurrence: Always

lineItems.refundsarray of LineItemRefund

This 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

lineItems.refunds.amountAmount

This 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.

Note: The refund amount shown is the seller's net amount received from the sale/transaction. eBay-collected tax will not be included in this amount, so the actual amount of the buyer's refund may be higher than this value.

Occurrence: Conditional

lineItems.refunds.amount.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.refunds.amount.convertedFromValuestring

The 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

lineItems.refunds.amount.currencyCurrencyCodeEnum

A 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

lineItems.refunds.amount.valuestring

The 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

lineItems.refunds.refundDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

lineItems.refunds.refundIdstring

Unique 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.

Occurrence: Conditional

lineItems.refunds.refundReferenceIdstring

This field is reserved for internal or future use.

Occurrence: Conditional

lineItems.skustring

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

lineItems.soldFormatSoldFormatEnum

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

Occurrence: Always

lineItems.taxesarray of Tax

Contains 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.

Occurrence: Always

lineItems.taxes.amountAmount

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

Occurrence: Conditional

lineItems.taxes.amount.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.taxes.amount.convertedFromValuestring

The 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

lineItems.taxes.amount.currencyCurrencyCodeEnum

A 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

lineItems.taxes.amount.valuestring

The 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

lineItems.taxes.taxTypeTaxTypeEnum

Tax type. This field is only available when fieldGroups is set to TAX_BREAKDOWN. If the order has fees, a breakdown of the fees is also provided.

Occurrence: Conditional

lineItems.titlestring

The title of the listing.

Note: The Item ID value for the listing will be returned in this field instead of the actual title if this particular listing is on-hold due to an eBay policy violation.

Occurrence: Always

lineItems.totalAmount

This 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: For orders that are subject to 'eBay Collect and Remit' tax, the 'Collect and Remit' tax amount for the order will be included in this total value only when the fieldGroups query parameter is set to TAX_BREAKDOWN. If the fieldGroups query parameter is not set to TAX_BREAKDOWN, 'Collect and Remit' will not be added into 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 one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is in this amount:

  • STATE_SALES_TAX: US state-mandated sales tax
  • PROVINCE_SALES_TAX: Provincial Sales Tax in Canada
  • GST: 'Goods and Services' tax in Canada, Australia, and New Zealand
  • VAT: VAT collected for UK and EU countries

Occurrence: Always

lineItems.total.convertedFromCurrencyCurrencyCodeEnum

A 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

lineItems.total.convertedFromValuestring

The 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

lineItems.total.currencyCurrencyCodeEnum

A 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

lineItems.total.valuestring

The 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

lineItems.variationAspectsarray of NameValuePair

An array of aspect name-value pairs that identifies the specific variation of a multi-variation listing. This array can contain multiple name-value pairs, such as color:blue and size:large, and will only be returned for orders created from a multiple-variation listing.

Occurrence: Conditional

lineItems.variationAspects.namestring

The text representing the name of the aspect for the name-value pair. For example, color, or Tire Type.

Occurrence: Conditional

lineItems.variationAspects.valuestring

The value of the aspect for the name-value pair. For example, red, or All Season.

Occurrence: Conditional

orderFulfillmentStatusOrderFulfillmentStatus

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

Occurrence: Always

orderIdstring

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

Occurrence: Always

orderPaymentStatusOrderPaymentStatusEnum

The 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

paymentSummaryPaymentSummary

This 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

paymentSummary.paymentsarray of Payment

This 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

paymentSummary.payments.amountAmount

The amount that seller receives for the order via the payment method mentioned in Payment.paymentMethod.

Note: For orders that are subject to 'eBay Collect and Remit' tax, which includes US state-mandated sales tax, Federal and Provincial Sales Tax in Canada, 'Good and Services' tax in Canada, Australia, and New Zealand, and VAT collected for UK or EU, 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 this totalDueSeller 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 one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is included in this amount:

  • STATE_SALES_TAX: US
  • PROVINCE_SALES_TAX: Provincial Sales Tax in Canada
  • GST: Canada, Australia, and New Zealand
  • VAT: UK and EU countries

Occurrence: Always

paymentSummary.payments.amount.convertedFromCurrencyCurrencyCodeEnum

A 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

paymentSummary.payments.amount.convertedFromValuestring

The 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

paymentSummary.payments.amount.currencyCurrencyCodeEnum

A 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

paymentSummary.payments.amount.valuestring

The 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

paymentSummary.payments.paymentDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

paymentSummary.payments.paymentHoldsarray of PaymentHold

This 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

paymentSummary.payments.paymentHolds.expectedReleaseDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

paymentSummary.payments.paymentHolds.holdAmountAmount

The monetary amount of the payment being held. This field is always returned with the paymentHolds array.

Occurrence: Conditional

paymentSummary.payments.paymentHolds.holdAmount.convertedFromCurrencyCurrencyCodeEnum

A 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

paymentSummary.payments.paymentHolds.holdAmount.convertedFromValuestring

The 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

paymentSummary.payments.paymentHolds.holdAmount.currencyCurrencyCodeEnum

A 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

paymentSummary.payments.paymentHolds.holdAmount.valuestring

The 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

paymentSummary.payments.paymentHolds.holdReasonstring

The reason that the payment is being held. A seller's payment may be held 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

paymentSummary.payments.paymentHolds.holdStatestring

The 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

paymentSummary.payments.paymentHolds.releaseDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

paymentSummary.payments.paymentHolds.sellerActionsToReleasearray of SellerActionsToRelease

A list of one or more possible actions that the seller can take to expedite the release of the payment hold.

Occurrence: Conditional

paymentSummary.payments.paymentHolds.sellerActionsToRelease.sellerActionToReleasestring

A 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

paymentSummary.payments.paymentMethodPaymentMethodTypeEnum

The payment method used to pay for the order. See the PaymentMethodTypeEnum type for more information on the payment methods.

Occurrence: Always

paymentSummary.payments.paymentReferenceIdstring

This field is only returned if payment has been made by the buyer, and the paymentMethod is ESCROW. This field contains a special ID for ESCROW.

Occurrence: Conditional

paymentSummary.payments.paymentStatusPaymentStatusEnum

The enumeration value returned in this field indicates the status of the payment for the order. See the PaymentStatusEnum type definition for more information on the possible payment states.

Occurrence: Always

paymentSummary.refundsarray of OrderRefund

This 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

paymentSummary.refunds.amountAmount

This field shows the refund amount for an order. This container is always returned for each refund.

Note: The refund amount shown is the seller's net amount received from the sale/transaction. eBay-collected tax will not be included in this amount, so the actual amount of the buyer's refund may be higher than this value.

Occurrence: Conditional

paymentSummary.refunds.amount.convertedFromCurrencyCurrencyCodeEnum

A 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

paymentSummary.refunds.amount.convertedFromValuestring

The 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

paymentSummary.refunds.amount.currencyCurrencyCodeEnum

A 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

paymentSummary.refunds.amount.valuestring

The 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

paymentSummary.refunds.refundDatestring

The 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]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2015-08-04T19:09:02.768Z

Occurrence: Conditional

paymentSummary.refunds.refundIdstring

Unique 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. For other refunds, see the refundReferenceId field.

Occurrence: Conditional

paymentSummary.refunds.refundReferenceIdstring

The eBay-generated unique identifier for the refund. This field is not returned until the refund has been issued.

Occurrence: Conditional

paymentSummary.refunds.refundStatusRefundStatusEnum

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

Occurrence: Conditional

paymentSummary.totalDueSellerAmount

This is the total price that the seller receives 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: For orders that are subject to 'eBay Collect and Remit' tax, 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 corresponding 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 the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is included in this amount:

  • STATE_SALES_TAX: US
  • PROVINCE_SALES_TAX: Provincial Sales Tax in Canada
  • GST: Canada, Australia, and New Zealand
  • VAT: VAT collected for UK and EU countries

Occurrence: Always

paymentSummary.totalDueSeller.convertedFromCurrencyCurrencyCodeEnum

A 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

paymentSummary.totalDueSeller.convertedFromValuestring

The 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

paymentSummary.totalDueSeller.currencyCurrencyCodeEnum

A 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

paymentSummary.totalDueSeller.valuestring

The 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

pricingSummaryPricingSummary

This 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

pricingSummary.adjustmentAmount

This 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

pricingSummary.adjustment.convertedFromCurrencyCurrencyCodeEnum

A 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

pricingSummary.adjustment.convertedFromValuestring

The 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

pricingSummary.adjustment.currencyCurrencyCodeEnum

A 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

pricingSummary.adjustment.valuestring

The 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

pricingSummary.deliveryCostAmount

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

Occurrence: Always

pricingSummary.deliveryCost.convertedFromCurrencyCurrencyCodeEnum

A 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

pricingSummary.deliveryCost.convertedFromValuestring

The 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

pricingSummary.deliveryCost.currencyCurrencyCodeEnum

A 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

pricingSummary.deliveryCost.valuestring

The 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

pricingSummary.deliveryDiscountAmount

This 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

pricingSummary.deliveryDiscount.convertedFromCurrencyCurrencyCodeEnum

A 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

pricingSummary.deliveryDiscount.convertedFromValuestring

The 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

pricingSummary.deliveryDiscount.currencyCurrencyCodeEnum

A 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

pricingSummary.deliveryDiscount.valuestring

The 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

pricingSummary.feeAmount

This 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 returned if special fees are being applied to the order and if the fieldGroups is set to TAX_BREAKDOWN.

Occurrence: Conditional

pricingSummary.fee.convertedFromCurrencyCurrencyCodeEnum

A 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

pricingSummary.fee.convertedFromValuestring

The 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

pricingSummary.fee.currencyCurrencyCodeEnum

A 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

pricingSummary.fee.valuestring

The 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

pricingSummary.priceDiscountAmount

This 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

pricingSummary.priceDiscount.convertedFromCurrencyCurrencyCodeEnum

A 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

pricingSummary.priceDiscount.convertedFromValuestring

The 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

pricingSummary.priceDiscount.currencyCurrencyCodeEnum

A 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

pricingSummary.priceDiscount.valuestring

The 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

pricingSummary.priceSubtotalAmount

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

Occurrence: Always

pricingSummary.priceSubtotal.convertedFromCurrencyCurrencyCodeEnum

A 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

pricingSummary.priceSubtotal.convertedFromValuestring

The 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

pricingSummary.priceSubtotal.currencyCurrencyCodeEnum

A 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

pricingSummary.priceSubtotal.valuestring

The 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

pricingSummary.taxAmount

This 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

pricingSummary.tax.convertedFromCurrencyCurrencyCodeEnum

A 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

pricingSummary.tax.convertedFromValuestring

The 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

pricingSummary.tax.currencyCurrencyCodeEnum

A 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

pricingSummary.tax.valuestring

The 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

pricingSummary.totalAmount

The 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: For orders that are subject to 'eBay Collect and Remit' tax, the 'Collect and Remit' tax amount for the order will be included in this total value only when the fieldGroups query parameter is set to TAX_BREAKDOWN. If the fieldGroups query parameter is not set to TAX_BREAKDOWN, 'Collect and Remit' will not be added into 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 one or more line items in the response with the following taxType values, the 'Collect and Remit' tax amount that the buyer paid is included in this amount:

  • STATE_SALES_TAX: US state-mandated sales tax
  • PROVINCE_SALES_TAX: Provincial Sales Tax in Canada
  • GST: 'Good and Services' tax in Canada, Australia, and New Zealand
  • VAT: VAT collected for UK and EU countries

Occurrence: Always

pricingSummary.total.convertedFromCurrencyCurrencyCodeEnum

A 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

pricingSummary.total.convertedFromValuestring

The 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

pricingSummary.total.currencyCurrencyCodeEnum

A 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

pricingSummary.total.valuestring

The 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

programProgram

This container is returned for orders that are eligible for eBay's Authenticity Guarantee service. The seller ships Authenticity Guarantee service items to the authentication partner instead of the buyer. The authenticator address is found in the fulfillmentStartInstructions.shippingStep.shipTo container. If the item is successfully authenticated, the authenticator will ship the item to the buyer.

Occurrence: Conditional

program.authenticityVerificationPostSaleAuthenticationProgram

This field is returned when the third-party authenticator performs the authentication verification inspection on the order line item. Different values will be returned based on whether the item passed or failed the authentication verification inspection.

Occurrence: Conditional

program.authenticityVerification.outcomeReasonAuthenticityVerificationReasonEnum

This field indicates the result of the authenticity verification inspection on an order line item. This field is not returned when the status value of the order line item is PENDING or PASSED. The possible values returned here are NOT_AUTHENTIC, NOT_AS_DESCRIBED, CUSTOMIZED, MISCATEGORIZED, or NOT_AUTHENTIC_NO_RETURN.

Occurrence: Conditional

program.authenticityVerification.statusAuthenticityVerificationStatusEnum

The value in this field indicates whether the order line item has passed or failed the authenticity verification inspection, or if the inspection and/or results are still pending. The possible values returned here are PENDING, PASSED, FAILED, or PASSED_WITH_EXCEPTION.

Occurrence: Conditional

program.ebayShippingEbayShipping

This container is returned only if the order is an eBay shipping order. It consists of a field that indicates the provider of a shipping label for this order.

Occurrence: Conditional

program.ebayShipping.shippingLabelProvidedBystring

This field contains the shipping label provider. If EBAY, this order is managed by eBay shipping and a free shipping label by eBay is downloadable by the seller via the eBay website.

Occurrence: Conditional

program.ebayVaultEbayVaultProgram

This field provides information about the eBay vault program that has been selected for an order. This is returned only for those items that are eligible for the eBay Vault Program.

Occurrence: Conditional

program.ebayVault.fulfillmentTypeEbayVaultFulfillmentTypeEnum

This field specifies how an eBay vault order will be fulfilled. Supported options are:

  • Seller to Vault: the order will be shipped by the seller to an authenticator.
  • Vault to Vault: the order will be shipped from an eBay vault to the buyer's vault.
  • Vault to Buyer: the order will be shipped from an eBay vault to the buyer's shipping address.

Occurrence: Conditional

program.ebayInternationalShippingEbayInternationalShipping

This container is returned if the order is being fulfilled through eBay International Shipping.

Occurrence: Conditional

program.ebayInternationalShipping.returnsManagedBystring

The value returned in this field indicates the party that is responsible for managing returns of the order line item.

Valid value: EBAY

Occurrence: Conditional

program.fulfillmentProgramEbayFulfillmentProgram

This field provides details about an order line item being handled by eBay fulfillment. It is only returned for paid orders being fulfilled by eBay or an eBay fulfillment partner.

Occurrence: Conditional

program.fulfillmentProgram.fulfilledBystring

The value returned in this field indicates the party that is handling fulfillment of the order line item.

Valid value: EBAY

Occurrence: Conditional

salesRecordReferencestring

An 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

sellerIdstring

The unique eBay user ID of the seller who sold the order.

Occurrence: Always

totalFeeBasisAmountAmount

This is the cumulative base amount used to calculate the final value fees for each order. The final value fees are deducted from the seller payout associated with the order. Final value fees are calculated as a percentage of order cost (item cost + shipping cost) and the percentage rate can vary by eBay category.

Occurrence: Always

totalFeeBasisAmount.convertedFromCurrencyCurrencyCodeEnum

A 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

totalFeeBasisAmount.convertedFromValuestring

The 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

totalFeeBasisAmount.currencyCurrencyCodeEnum

A 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

totalFeeBasisAmount.valuestring

The 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

totalMarketplaceFeeAmount

This is the cumulative fees accrued for the order and deducted from the seller payout.

Occurrence: Conditional

totalMarketplaceFee.convertedFromCurrencyCurrencyCodeEnum

A 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

totalMarketplaceFee.convertedFromValuestring

The 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

totalMarketplaceFee.currencyCurrencyCodeEnum

A 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

totalMarketplaceFee.valuestring

The 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

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
404Not Found
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
30500API_FULFILLMENTAPPLICATIONSystem error
32100API_FULFILLMENTREQUESTInvalid order ID: {orderId}
32800API_FULFILLMENTREQUESTInvalid field group: {fieldGroup}

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Get an Order

This sample retrieves a seller's order corresponding to the provided order ID. The retrieved order includes a summary of taxes and fees.

Input

Use the orderid parameter to retrieve a specific order.

GEThttps://api.ebay.com/sell/fulfillment/v1/order/1********7

Output

A successful call returns one Order container.

Sample 2: Get an Order with Tax and Fee Breakdown

This sample retrieves a seller's order corresponding to the provided order ID. In addition to the summary of taxes and fees, a breakdown of tax and fee values is included.

Input

Use the orderid parameter to retrieve a specific order and include the fieldGroups parameter set to TAX_BREAKDOWN to return a breakdown of the taxes and fees values in taxes.

GEThttps://api.ebay.com/sell/fulfillment/v1/order/1********7?fieldGroups=TAX_BREAKDOWN

Output

A successful call returns one Order container with a breakdown of taxes and fees in taxes.