Traditional API calls have two fundamental kinds of information that must be sent:

  • Data that are common to all calls in that API;
  • Data that are specific to particular calls and required in order to fulfill a call's purpose.

In some cases the data are passed in by using input fields that are defined in AbstractRequestType, while in other cases, the data are passed in through the endpoint or through an HTTP header.

Tags used in a traditional API call must exactly match the API schema and are case-sensitive.

Message IDs

Message IDs are used to associate response messages with the particular request messages that triggered them.

The correlating message ID is an optional input that an application uses to enable strict tracking of request and response messages. This is particularly important if an application has to contend with many such message pairings. The message ID value is provided in the MessageID property of a call's request payload. The value should be unique across the eBay site and cannot exceed 64 characters.

Each message ID comprises a Universally Unique IDentifier (UUID) value followed by a dash and an application-specific value:

{UUID}-{ApplicationSpecificValue}

The maximum length of a message ID is 64 characters including the UUID and hyphen.

When a MessageID value is passed in when issuing a Trading API call, the same value is returned in the CorrelationID field in the response payload. This provides the connection between a particular request and its response. The value is not read or used in any other way by eBay, and the actual value only has meaning to the application.

An application can use this information to definitively associate a particular response with the request that triggered it. For example, if an application serves multiple customers and assigns an internal identifier to each user (e.g., a customer number,) using this message ID allows the application to associate specific responses with specific customers.

Of course, an application could use a combination of these approaches, such as passing the customer identifier within the application-specific value. That would serve to both link the request and response to each other and to associate the response with a particular customer.

For example, an application might pass a value such as 9******************************B-0***1 where the characters to the left of the hyphen are a UUID and the characters to the right are an application-specific customer ID.

Many programming languages provide classes or modules that generate UUIDs.

Some calls are designed to retrieve large sets of metadata that change infrequently. To improve performance, these calls return cached responses when all available data is requested (i.e., with no filters). In these cases, the CorrelationID is not applicable. However, if an input filter is specified to reduce the amount data returned, use MessageID and CorrelationID for these metadata calls.

UUIDs

UUID values — which are also called InvocationID values — must be exactly 32 characters in length and may only include the following:

  • Numeric digits from 0 through 9
  • Letters from A through F (case insensitive)

Including a UUID value is recommended for those calls that write item data. It should also be included with supported calls to prevent the submission of duplicate data.

If a duplicate UUID value is used for a call, error code 488 will be returned and will include the following information:

  • The item ID for the item that has been previously listed with the particular UUID
  • A boolean value indicating whether the duplicate UUID value was sent by the same application

If it is not clear whether or not the call succeeded, such as when there is a network error, you can submit the same data again using the same UUID value. If the previous call did succeed, the second call will not succeed and the same data will not be submitted twice.

Several Trading API calls support the use of UUID request parameters to uniquely associate an instance of an API call with a specific application/user combination. For example, AddItem accepts an Item.UUID value as input. When executing this call, it is recommended that the same UUID value be used for both MessageID and Item.UUID.

Invocation IDs

If a duplicate Item.InvocationID is used for a call, error code 21060 is returned along with the DuplicateInvocationDetails container similar to that illustrated here:

<DuplicateInvocationDetails>
  <DuplicateInvocationID>A******************************2</DuplicateInvocationID>
  <Status>Success</Status>
  <InvocationTrackingID>9********7</InvocationTrackingID>
</DuplicateInvocationDetails>

Fields that are also included in the DuplicateInvocationDetails container are:

  • Status property indicates whether the previous call succeeded (Success) or is still in progress (InProgress)
  • InvocationTrackingID which is a call-specific tracking number

Specify an error language

An application can specify the language in which error and warning messages are returned. This is done by setting a value in the ErrorLanguage property of the request. Specify the standard RFC 3066 language identification tag for the language in which error messages should be returned. For example, specify en_US to have error messages returned in US English.

Error language is an optional input which, if not specified, defaults to US English. Refer to Global ID Values for the language identification tag to enter, as well as the associated country and eBay site ID.

Filter results

With many data retrieval calls that return multiple objects (e.g., multiple items,) you may want to reduce the volume of the response payload by reducing the number of fields, or the details within each field, that is returned in each response.

Three filter types that can be applied are:

  • DetailLevel
  • OutputSelector
  • GranularityLevel

Each of these three filters reduce the size of the response payload. For information about other ways to control the amount of data that are returned, refer to Other filter options.

Detail and granularity

Both DetailLevel or GranularityLevel have associated code types that define the enumeration values that can be used for each of these filters. The Trading API calls that can use each of the enumeration values, and how they use each value, differs with each call. Refer to DetailLevelCodeType and GranularityLevelCodeType for more information on the different filter values available. You can also read the call reference documentation for each call for more information on how these values are used for each supported API call.

Additionally:

  • GetMyMessages is the only Trading API call that requires DetailLevel be set in the request payload. For all other Trading API calls, not setting a DetailLevel may cause the response payload to be larger or smaller than it would be had a DetailLevel value been specified.
  • A DetailLevel value of ReturnAll, which is supported by all calls that support DetailLevel except GetMyMessages, will ensure that all possible and applicable data will be returned in the response. Depending on the API call and amount of data involved, setting DetailLevel to ReturnAll can affect client- and server-side performance, so developers should use this value with care.
  • Some Trading API calls support multiple DetailLevel values and, if used, the developer will include a DetailLevel field for each specified value.

  • As the field name suggests, GranularityLevel defines the granularity (or scale) of the returned details in the response. The three supported values are:

    • Coarse (fewest results)
    • Medium
    • Fine (most results)

    How these values are implemented varies by API call.

  • Only one GranularityLevel value may be set for each API call.

Generally, if you pass in a DetailLevel or a GranularityLevel value that is not supported by a Trading API call, the filter and its value will be ignored and an error/warning message will not be triggered.

For all calls that support DetailLevel and/or GranularityLevel, a DetailLevel and/or GranularityLevel section is added to the Detail Controls section of the call reference page. These sections contain tables which tell users exactly which fields are returned based on the DetailLevel and/or GranularityLevel values that are set.

OutputSelector

The OutputSelector filter works quite differently from DetailLevel and GranularityLevel.

With OutputSelector, a specific response container/field to return is specified using the OutputSelector field, and multiple OutputSelector fields can be defined in one call. If a container is specified, all of that container's children will also be returned. For example, if you issue a GetItem call and set the OutputSelector field to ListingDetails, all fields within the ListingDetails container are returned. Developers should read the call-specific reference documentation for an API call to get more information about using OutputSelector with that call.

The OutputSelector field is supported by many of the Trading API's Get family calls, such as GetItem, GetSellerEvents, and GetOrders.

The OutputSelector field can make the response of a Trading API call more manageable, particularly when the standard call returns a large payload. When using one or more OutputSelector fields, the output data will include only those fields that have been specified in the request. By using OutputSelector filters, you select the fields you want returned in the response. If a field is returned, that field's parent and any child fields are also returned.

An example of an application that could use an OutputSelector inclusive filter is a buying application that displays information to users that is necessary to make a purchasing decision. Using OutputSelector fields, the application could configure a GetItem call to only return the following elements:

The following XML snippet illustrates how this request may would look when the above OutputSelector values are used:

...
<ItemID>1**********6</ItemID>
<OutputSelector>PictureURL</OutputSelector>
<OutputSelector>UserID</OutputSelector>
<OutputSelector>CurrentPrice</OutputSelector>
<OutputSelector>EndTime</OutputSelector>
<OutputSelector>ViewItemURL</OutputSelector>
...

When specifying multiple fields, you can either use separate, repeating OutputSelector tags for each desired field as just illustrated above, or one OutputSelector tag may be specified with multiple field values delimited with a comma as illustrated here:

...
<ItemID>4**********7</ItemID>
<OutputSelector>PictureURL,CurrentPrice</OutputSelector>
...

Note that unspecified fields are not returned. For example, even if PaginationResult would normally be in the response, the use of one or more OutputSelector fields will prevent it from being returned unless PaginationResult is explicitly listed among the fields specified with the OutputSelector field.

For more information, refer to How to get Pagination details when OutputSelector filter is specified.

The full path of a field does not need to be specified unless the field being specified can be returned in multiple containers. If the field being specified can be returned in multiple containers (e.g., Item.ListingDetails.StartTime in GetItem call,) then specify the full path as illustrated here:

...
<ItemID>4**********7</ItemID>
<OutputSelector>Item.ListingDetails.StartTime</OutputSelector>
...

When specifying the full path, do not specify the call request type. For example, do not specify GetItemRequestType in the OutputSelector field.

If you enter a typo in the field name, an error message is returned, but if you enter an unavailable field, an error message is not returned.

An output selector cannot filter out standard fields such as Timestamp, Ack, Version, or Build from a response.

Call support

Refer to the following table for information about which Trading API calls support each type of filter:

Trading API calls that support DetailLevel Trading API calls that support OutputSelector Trading API calls that support GranularityLevel
GetAdFormatLeads GetAccount GetBidderList
GetBestOffers GetAdFormatLeads GetSellerList
GetCategories GetAllBidders  
GetCategoryFeatures GetBestOffers  
GetCategoryMappings GetBidderList  
GetFeedback GetCategories  
GetItem GetCategoryFeatures  
GetItemTransactions GetFeedback  
GetMyeBayBuying GetItem  
GetMyeBaySelling GetItemsAwaitingFeedback  
GetMyMessages GetItemShipping  
GetOrders GetItemTransactions  
GetOrderTransactions GetMemberMessages  
GetSellerEvents GetMyeBayBuying  
GetSellerList GetMyeBaySelling  
GetSellerTransactions GetMyMessages  
GetTaxTable GetNotificationPreferences  
GetUser GetOrders  
  GetOrderTransactions  
  GetSellerEvents  
  GetSellerList  
  GetSellerTransactions  

Other filter options

In addition to DetailLevel, GranularityLevel, and OutputSelector, additional filtering options can be used to fine tune the amount of data returned, including:

  • Date/time filters

    Specifying date/time ranges can limit the amount of data that is returned. For example, GetSellerList includes EndTimeFrom and EndTimeTo fields that allow the seller to retrieve only those listings that ended within the specified time range.

  • Pagination filters

    These filters specify the number of records (e.g., orders,) that are displayed per page of data. PaginationType controls the pagination of the call response by configuring the following parameters:

    • EntriesPerPage

      This value sets the number of records to return per page of data. The maximum EntriesPerPage value varies by API call

    • PageNumber

      This value sets the specific page of data to return. For example, to return the first page of data, set PageNumber = 1. To view each successive page of data, increment the PageNumber value by 1.

    Each API call that supports pagination will return the PaginationResultType container that includes the following fields:

    • TotalNumberOfEntries
    • TotalNumberOfPages

    Based on these two values, the user can adjust the EntriesPerPage and PageNumber values in the request during subsequent calls to that API.

    Refer to EntriesPerPage Field Index for a list of Trading API calls that support pagination filters.