Overview of the API Schema

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

Topics:

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. For example:

The concrete requests and responses (e.g., AddItemRequest and AddItemResponse for the AddItem call) are derived from the abstract request types. The concrete types define context-specific business data that is applicable for the particular call. For example, AddItemRequest specifies that it takes an item (Item) as the message payload, and AddItemResponse specifies that it returns the item ID (ItemID) and fees (Fees).

The naming convention we use for the concrete 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.

Note: 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).

Figure: A Request Type
Request Type

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

Figure: A Response Type
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 use amounts represent notions like listing fee amounts and account balance amounts. We define the types such as amounts as core components in the schema. The following example is a snippet from the FeeType schema and shows that the FeeType component consists of a name (a string describing what the fee is for) and a fee (e.g., USD 1.00). The fee is represented as an amount type,

Example: Definition of a Type that Uses a Core Component (XML Schema)
<xs:complexType name="FeeType">
  <xs:sequence>
    <xs:element name="Name" type="xs:string" minOccurs="0"/>
    <xs:element name="Fee" type="cc:AmountType" minOccurs="0"/>
  </xs:sequence>
</xs:complexType>

The following example shows what this core component data would look like in an actual XML document (e.g., in the call response).

Example: Data for a Type that Uses a Core Component (XML)
<Fees>
  <Fee>
    <Name>AuctionLengthFee</Name>
    <Fee currencyID="USD">0.0</Fee>
  </Fee>
  <Fee>
    <Name>BoldFee</Name>
    <Fee currencyID="USD">0.0</Fee>
  </Fee>
... more Fee nodes ...
  <Fee>
    <Name>SubtitleFee</Name>
    <Fee currencyID="USD">0.0</Fee>
  </Fee>
</Fees>

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 components 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 the 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. 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, and they must be spelled in the same way as they are spelled in that list.

Note: A few components do not have corresponding code lists. Instead, the valid values are described in the documentation of the element itself. For example, StoreCategoryID has no code list. Its list of possible values is described in the element's type documentation instead.

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.

Note: 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.

For example, AddItem lets you specify multiple payment methods in the request. Here is the definition of the PaymentMethod element and another element called PayPalEmailAddress in the Item schema (ItemType):

<xs:element name="PaymentMethods" type="ns:BuyerPaymentMethodCodeType" minOccurs="0" maxOccurs="unbounded" />

<xs:element name="PayPalEmailAddress" type="xs:string" minOccurs="0" />

When you send the request to eBay, the PayPalEmailAddress element must be inserted after all the PaymentMethod elements, not between them:

...

<PaymentMethods>CashOnPickup</PaymentMethods>

<PaymentMethods>PayPal</PaymentMethods>

<PayPalEmailAddress>mypaypalaccountemail@ebay.com</PayPalEmailAddress>

... other elements here ...

Length Restrictions

All string input fields have length restrictions. Some string input fields (e.g., Item.SubTitle) do not have a known set of possible values. For these arguments, the documentation specifies the maximum permitted length in characters. Other string fields (e.g., Country) do have a known set of possible values. In these cases, the maximum length is not specified in the documentation. Fields of other types (e.g., integers) may also have length restrictions. These restrictions are also 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 an enumeration of values. For example, the ListingDuration code list contains all the possible listing durations (e.g., Days_3) on eBay. If a field uses a code list to define its possible values, you can only pass those values in to the call. If you send in an undefined value (including a misspelled value), an error is returned.

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

ComponentNameCodeType

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

Example: Portions of a Code List (XSD)
<xs:simpleType name="ListingDurationCodeType">
  <xs:annotation>
    <xs:documentation>
      ListingDurationCodeType - Type declaration to be used by other schema.
      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.
    </xs:documentation>
  </xs:annotation>
  <xs:restriction base="xs:token">
    <xs:enumeration value="Days_1">
      <xs:annotation>
        <xs:documentation>
          (in/out) 1 Day - 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 Chinese auctions
          (including Real Estate) and Personal Offer (Second Chance Offer).
        </xs:documentation>
      </xs:annotation>
    </xs:enumeration>
    <!-- ... More codes here ... -->
    <xs:enumeration value="CustomCode">
      <xs:annotation>
        <xs:documentation>
        (out) Reserved for internal or future use
        </xs:documentation>
      </xs:annotation>
    </xs:enumeration>
  </xs:restriction>
</xs:simpleType>

The following example, which also applies to the SOAP API, shows portions of the same code list in a generated stub class in C#. Each code list is an enumeration defining a set of named constants.

Example: Portions of a Code List Stub (C#)
   public enum ListingDurationCodeType {
      Days_1,
      // ... more enumeration elements here ...
      CustomCode,
}

Some codes are valid in requests and responses, some are only valid in requests, and others are only returned in responses. In the schema, the usage is specified in the code list annotations (see the following example).

Very important: 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.

Note: 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 version number of the eBay Trading API that you are programming against (e.g., 813). See Where to Find the eBay Schema Files to download the latest schema.

Every two weeks, 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.

If you are just starting out, start with the latest version, and always make sure your application is using at least the lowest supported version.

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

Note: 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.

When a new version of the API becomes available, we announce it on the eBay Developer Product Updates page. You can also check the eBay Developers Program site periodically to find out if any new versions are available. The latest version of the API is identified by the version number specified in the latest eBay schema file.

New features and functional changes are initially available on US sites (e.g., ebay.com and stores.ebay.com). We release functionality applicable to international sites (e.g., ebay.co.uk) about one week after the US site release. This means that when we announce new functionality in the Release Notes, that functionality is only available on the US site. It will be available to international sites about one week later. For a list of supported international sites, see the site code list (SiteCodeType) and Field Differences for eBay Sites.

Note: For communication purposes in the Release Notes, we add an "i" suffix to version numbers to clarify which versions are in effect internationally (e.g., "Version 695i"). The "i" is not used in the schema or the URL to the schema, and you should not pass the "i" when submitting requests to international sites.

When to Update the Schema

Older versions of the schema are periodically deprecated, which means they are no longer supported. See the eBay Trading API Schema Versioning Strategy for details about how deprecation works for the Trading API and a list of supported versions.

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 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, AddItemRequest extends AbstractRequest. 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.

Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.