Overview of the API Schema

This section introduces the major components that are available in the Trading API schema.


Message Types

Core Components

Base Components

Release Versions

Interoperability Considerations

Message Types

When you make a call, you send a request message to eBay and eBay returns a response message. The message types enable your application to execute common tasks that a seller would perform on eBay, such as listing items.

All the message types derive from these abstract base request and response types:

The abstract base types define fields that are standard for all calls (but not all fields in these types are used by all calls). Below are some examples of the fields in these base types:

The base request and response types for each call (e.g., AddItemRequestType and AddItemResponseType for the AddItem call) are derived from the abstract request/response types. The base request and response types define context-specific business data that is applicable for the particular call. For example, AddItemRequestType specifies that it takes an Item object in the request payload, and AddItemResponseType specifies that it returns multiple fields, including the newly created ItemID and Fees.

The naming convention we use for the base request and response type names is the name of the call followed by "Request" or "Response":

callnameRequest, callnameResponse

The figures below illustrate the request and response content models.

In the ebaysvc.wsdl file, which is used in the SOAP API, the message elements define the request and response messages and the data types to use in the body of those messages. The message names are the same as the data type element names (e.g., AddItemRequest). In the portType clause, you'll see the name of the service definition interface (the interface you'll use to access operations) will be derived from eBayAPIInterface. This interface specifies each logical operation (e.g., AddItem) and indicates that they are bidirectional (request-response).

The figure below shows the content model for a request (in this case, an AddItem request).

Request Type
A Request Type

The figure below shows the content model for a response (in this case, an AddItem response).

Response Type
A Response Type

Core Components

Certain constructs, such as monetary amounts and units of measure, always require the same combination of elements in order to be semantically meaningful. For example, a monetary amount is typically modeled as a currency and a value. Various base components that use amounts include listing fee amounts and account balance amounts. We refer to common types that are used across multiple API calls as core components. The following example is a snippet from the FeeType complex type and shows that FeeType consists of a name (a string describing what the fee is for) and a fee (e.g., USD 1.00) field. The fee field uses the AmountType complex type.

Definition of a Type that Uses a Core Component (XML Schema)

<xs:complexType name="FeeType">
    <xs:element name="Name" type="xs:string" minOccurs="0"/>
    <xs:element name="Fee" type="cc:AmountType" minOccurs="0"/>

The following example shows what this data would look like in an actual XML response.

Data for a Type that Uses a Core Component (XML)

    <Fee currencyID="USD">0.0</Fee>
    <Fee currencyID="USD">0.0</Fee>
... more Fee nodes ...
    <Fee currencyID="USD">0.0</Fee>

See Creating Item Listings for information about working with these types when you list and retrieve items. See eBay Types for information about other supported data types.

Base Components

eBay's base components are simple and complex types that model eBay business-level objects (e.g., items) as well as eBay API-specific notions (e.g., detail levels). The abstract request and response types are also base types (see Message Types).

When you design your application's business logic, these are some of the most important eBay objects to understand:

Each of the above components contains a number of subcomponents. For example, Item contains a number of objects that describe the details of the listing itself, such as Title and Description, as well as other business-level information.

Many subcomponents are defined as simple types in the schema. For example, Item.Title is a simple type that just takes a string value. Some components are complex types that group sets of data into logical subcomponents, according to their usage. For example, an Item can contain a ShippingDetails object, which contains a number of other components.

The schema (XSD or WSDL) provides a low-level view of how each component is modeled (see Where to Find the eBay Schema Files), or refer to the eBay Trading API Reference.

Data Validation

When you work with a traditional API, it is important to understand the rules eBay uses for validating input fields and when fields are returned in a given call's response.

Predefined Values

Some types have a predefined list (enumeration) of valid input and output values. To help you reduce errors due to invalid input data, the schema provides you with the valid values. These values are defined in code lists. For example, ListingDuration is a code list that specifies all the valid listing durations on eBay for different listing types. See Code Lists for more information about code lists. If a type uses a code list, only the values in that list can be passed in to a request payload, and they must be spelled in the same way as they are spelled in that list.

Some components do not have corresponding code lists. Instead, the valid values are described in the documentation of the element itself and/or this data is returned in metadata-related API calls, such as GeteBayDetails.

Applicability for Each Call

Some components (e.g., TimeLeft) are only applicable when an Item is returned with a GetItem response; but they are invalid or ignored when an Item is passed in an AddItem request. The applicability of each field in the context of each call is described later in this guide (e.g., Creating Item Listings), as well as in the eBay Trading API Reference. Also see Controlling the Amount of Data Returned for information about the ways in which you can manipulate the set of components that are returned. In many cases, a field or value that is not applicable for a call is ignored if it is passed in. However, if passing a particular value or field would cause the intent of the request to become ambiguous or inconsistent, the call will return an error. For example, if you pass both flat-rate shipping fields and calculated-rate shipping fields when you list an item, the call will fail.

Required and Optional Fields

As a general convention, all elements in the schema are defined with a multiplicity of minOccurs="0". This does not necessarily mean the field is optional in a call you are using.

If an element is defined with a multiplicity of minOccurs="1" (or no minOccurs value, which means it defaults to 1), then the field is required in all cases. However, most elements in the eBay schema are defined with a multiplicity of minOccurs="0".

The schema uses this convention for few reasons:

To determine whether or not a field is required in a particular context, please refer to the eBay Trading API Reference.

If any required fields are missing when you use a call, the request will fail and return errors. See Error Handling.

Repeating (Unbounded) Fields

If the multiplicity of an element is defined as maxOccurs="unbounded" or a value greater than 1 in the schema, it means you can specify the element multiple times in the request (like you are specifying an array). If you do so, the fields must be contiguous. That is, you cannot insert other fields between the repeating fields. Otherwise, some of the data will be dropped in an unpredictable manner.

Length Restrictions

All string input fields that do not use predefined values (e.g. enums) have length restrictions. For these arguments, the documentation specifies the maximum permitted length in characters. For string fields that use predefined values (enums), the maximum length is sometimes, but not always specified in the documentation. Fields of other types (e.g., integers) may also have constraints, and these constraints (like min or max values) are specified in the documentation, where applicable.

Data Types

The schema enforces the usage of correct data types. For example, if an element is defined as a double, you need to pass in a numeric value. See Data Types.

Code Lists

Some base components have predefined lists of possible input and output values (e.g., listing durations). Each code list is a list of values. For example, the ListingDuration code list contains all the possible listing durations (e.g., Days_7) for different listing types on eBay. If a field uses a code list to define its possible values, you can only pass those values in to the request. If you send in an undefined value (including a misspelled value), an error is returned.

The naming convention we use for the code list types is the name of the component followed by "CodeType":


The following example is a snippet from ListingDurationCodeType and shows that the ListingDuration fields can have values like "Days_1" for one-day listings.

Portions of a Code List (XSD)

<xs:simpleType name="ListingDurationCodeType">
      Each code specifies a number of days that a listing can be active
      (i.e., available for bidding/buying). The validity of a code depends
      on the listing type and category.
  <xs:restriction base="xs:token">
    <xs:enumeration value="Days_1">
          1-day listing duration. A seller must have a positive feedback rating of 10
          or more or must be ID Verified to use the 1-day listing duration on
          the US site. Applicable for auctions and a classified ad in a Real Estate category. 
    <!-- ... More codes here ... -->
    <xs:enumeration value="CustomCode">
        (out) Reserved for internal or future use

Some codes are valid in requests and responses, some are only valid in requests, and others are only returned in responses.

All code lists support a default value (CustomCode). If your application uses a supported but outdated version of the schema, it is possible that you will retrieve data where a user has selected an option (on the eBay site or via another application) that your application does not recognize. When your application sends a request, eBay checks the version you pass in. If a value in the response doesn't exist in that version, we map the undefined value to CustomCode. If you detect this value in a response message, you should update your version of the schema to get the latest code lists. See Where to Find the eBay Schema Files.

This CustomCode convention is necessary because SOAP clients cannot easily tolerate new or unexpected enumerated values. If a SOAP client only supports values A, B, C, and we start sending D to that client, it will throw an illegal state exception. In order to have the type safety of enumerations but allow clients that still use older schema versions to continue to work, we have to coerce the new "D" value to a default value that the client understands. This is why all enums have CustomCode.

When you work with code lists, you will need to manage the eBay business logic that affects your application. Code lists define all possible input and output values generically. That is, they do not describe business rules and dependencies. For example:

Release Versions

The release version is the train/version number of the API that you are programming against (e.g., 1221). See Where to Find the eBay Schema Files to download the latest schema.

The Trading API can have releases as often as every two weeks as eBay updates features and adds new ones. Sometimes the update affects everybody no matter what version they are using, and sometimes an update only affects a particular API version. So it's important to keep track of what version of the API you're using.

Each time you execute a request, you need to specify the version of the API you are using. Also, although you are not required to upgrade your application each time a new version of the API is released, it is a good idea to at least be aware of changes made in each release.

Some changes may affect your application's business logic or ability to execute calls successfully. The version number you specify in the gateway URL and request body indicates the schema version that your application is using.

The eBay Developers Program Release Cycle

When you send a request to eBay, you need to specify the version of the schema that you are using (see Routing the Request and Specifying the Schema Version).

You pass the version in the Version field, and the same number is returned in the response in a Version field. Each response also contains a Build field. This refers to the specific software build that eBay used when processing the request and generating the response. Developer Support may request the build information when helping you resolve technical issues.

The latest version of the API is identified by the version number specified in the latest eBay schema file.

When to Update the Schema

If your application uses an outdated version of the eBay schema, eBay will still process the request as long as that version is at or above the lowest supported version.

It is a good idea to test code list values in the response payload to make sure they don't contain the value "CustomCode" (see Code Lists). If you see this value, it's a signal that a code list you're using is out of date with the version on the server.

You should plan to regularly update your version of the schema if you want to support the latest data that eBay has specified. See Where to Find the eBay Schema Files for information about updating your local version of the eBay Trading API schema.

Interoperability Considerations

To reduce interoperability issues (due to differences in SOAP client implementations for different languages and operating environments), we have made certain design decisions that may affect how you design your application to use the base and core component types:

Polymorphism: We limit extension to the request type schema and response type schema. For example, AddItemRequestType extends AbstractRequestType. In all other cases, we avoid polymorphism. For example, when specifying shipping details (ShippingDetails), you need to choose either a flat rate or a calculated rate. Instead of extending a common rate type, we define separate FlatShippingRate and CalculatedShippingRate containers. You can specify either one in the shipping details, but not both. Your application will need to handle such business logic (the "or" logic is not exposed in the schema). For details about such dependencies, please see Creating Item Listings and related topics.

Backward Compatibility: We use a versioning system so that your applications will be backward compatible when new elements appear in the server-side schema. See Interoperability Considerations and the eBay Schema Versioning Strategy. We also provide hints to help developers determine when certain data is out of date on the client side. See Code Lists.

Cardinality/Multiplicity: For base components, the cardinality of major containers is set to minOccurs="0" (but maxOccurs can vary). This will allow us to reuse the same container objects across different use cases that might require different combinations of child components in the future.

In addition, we adhere to the following rules for representing data types in the schema:

See eBay Types for a list of data types and information about working with time values.