Overview of the API Schema

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

If you are planning to use the eBay SDK for Java or the eBay SDK for .NET, please note that the SOAP API schema contains data as it is passed from an application to eBay or from eBay to an application. This includes such code components as Item, User, Feedback, and Transaction. Data for these objects is set and extracted using methods or properties on those types. And the data is transferred between the application and eBay through the API call classes.

The schema is organized into these major components:

API request and response messages (see Message Types)
Core components (see Core Components)
Base components (see Base Components, Data Validation, Code Lists)

To ensure interoperability between different platforms and clients, the schema follow certain design principles. See 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:

AbstractRequest—This is the base type for requests.
AbstractResponse—This is the base type for responses.

The abstract base types define fields that are standard for all calls. For example:

All requests let you specify general instructions related to the data you're sending in or the data you want eBay to return.
Detail level—Use this to control the amount of data returned. See Controlling the Amount of Data Returned.
Error language—Use this to specify the language you want errors returned in. See Customizing Your Application's Error Handling Abilities.
Version—Use this to specify the version of the schema you are using. See Release Versions for details.
Warning Level—Use this to control whether to retrieve warnings if you pass in unrecognized fields. See Customizing Your Application's Error Handling Abilities.
All response types also include standard information.
Version and build—Use this information to determine the version of the schema and the specific software build that eBay used when processing the request and generating the response. See Release Versions for details.
Errors—For any request, one or more errors may be returned. Please see Error Handling for more information about working with errors.
Acknowledgement—All responses return a standard acknowledgement element that indicates the success, failure, or partial failure of a call.
Time stamp—All responses return the official eBay time stamp in UTC/GMT (see Data Types for information about time values). The time stamp indicates the time when eBay processed the request; it does not necessarily indicate the current eBay official eBay time. In particular, calls like GetCategories can return a cached response, so the time stamp may not be current.
All requests support a MessageID element and all responses support a CorrelationID element. If you pass a message ID in a request (up to 64 characters), it should be unique across the eBay site. See Specifying a Message ID to Correlate the Request and Response for more information. We will return the same value as the correlation ID in the response. This may be useful for tracking that a response is returned for every request and to match particular responses to particular requests.

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 and 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":

VerbNameRequest

VerbNameResponse

For a summary of the concrete message types that are available, see Overview of Calls.

Figure 5-1 and Figure 5-2 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).

Figure 5-1 shows the content model for a request (in this case, an AddItem request).

Figure 5-1 A Request Type

Figure 5-2 shows the content model for a response (in this case, an AddItem response).

Figure 5-2 A Response Type

The wrapper classes in the eBay SDK for Java and in the eBay SDK for .NET use the SOAP API schema as the basis for conveying data to and from eBay.

Using an object in an SDK is slightly different from using the SOAP API directly. If you use an SDK, you create a concrete request object and populate it with data; data is entered into the properties of an SDK call class or passed as the input for an execution method. For the data returned to your application from eBay, concrete response objects are created. You may or may not need to even operate on the response object. Key data for an API call is returned by the execution method of the call class. For instance, the execution method for the GetItemCall class, getItem( ), returns the data for the item in an Item object. The application only needs to inspect that object, rather than inspecting the response object, to get the data.

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. Example 5-1 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 5-1 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>

Example 5-2 shows what this core component data would look like in an actual XML document (e.g., in the call response).

Example 5-2 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 Listing Items 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:

Item (see Items and Listings)
Category (see Categories)
User (see Users)
Transaction (see Transactions (End of Auction))
Feedback (see Feedback)

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.

Please refer to the following resources for information about working with specific base components:

Categories—This chapter provides information about many of the base components that you can use to retrieve and work with the eBay category hierarchy.
Listing Items—This chapter provides information about many of the base components that you can use when you want to list an item.
Working with Attribute-Based Features—This chapter provides information about many of the base components that you can use when you want to list or retrieve items with Item Specifics and Pre-filled Item Information.
Retrieving Items—This chapter provides information about many of the base components that you can use to browse for listings and retrieve specific listings.
Searching for Items—This chapter provides information about many of the base components that you can use to search eBay for listings that satisfy a particular query.
Completing the Sale—This chapter provides information about many of the base components that you can use to process items that have been won or purchased.
Leaving and Retrieving Feedback—This chapter provides information about many of the base components that you can use to leave feedback retrieve feedback left for a user.
Managing User Information—This chapter provides information about many of the base components that you can use to work with and manage various types of user information, from the data for an eBay user to a user's preference settings.
The schema —This provides you with the low-level view of how each component is modeled.

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., Listing Items), as well as in the relevant call reference within this guide (e.g., AddItem) and the eBay Trading API Call 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:

The same types can be shared across multiple calls, but some elements defined on those types might not be shared. For example, Item.Country is required as input to AddItem, but it isn't applicable in the response of GetSellerEvents. As both of these calls share the same basic Item object, eBay needs to set the Item.Country element's multiplicity to minOccurs="0" in the schema so that Item can be used in both cases.
The same field can be required in one use case and optional in another, even within the same call. For example, in AddItem, the Item.Title field is required as input in most cases, but it's optional if you use a feature that "pre-fills" the title for you. Therefore, eBay needs to define the Item.Title element's multiplicity as minOccurs="0" in the schema to account for this "pre-filling" use case.
Future eBay enhancements can change a required field to optional. For example, Item.Location used to be required in AddItem. But when we added a new Item.PostalCode field (to support a new search feature), the Location field became optional. Therefore, to "future-proof" the schema against such logical changes, eBay usually defines fields as minOccurs="0" in the schema, even when the field is currently required.

To determine whether or not a field is required in a particular context, please refer to the eBay Trading API Call 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). eBay publishes these values as code lists (small data dictionaries) that you can access programmatically. Each code list is an enumeration of values. For example, the ListingDuration code list lists all the possible listing durations (e.g., Days_3) on eBay. Furthermore, if a field uses a code list to define its possible values, you can only send those values in. 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

For information about the code lists that are available, see the API schema. Many input tags require as input one of the values defined one of the available code lists.

Example 5-3 is a snippet from the ListingDurationCodeType schema and shows that the ListingDuration codes have values like "Days_1" for one-day listings.

Example 5-3 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>

For a SOAP API example showing portions of the same code list in a generated stub, see the ListingDurationCodeType.java file in the eBay SDK for Java:

eBay SDK for Java

http://developer.ebay.com/community/featured_projects/?name=eBay+SDK+for+Java

Example 5-4, 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 5-4 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 Example 5-3):

(in, out) means the value can be specified as input and can be returned in responses.
(in) means the value can be specified as input, but it is not returned in responses. Usually, this occurs when a computed value is returned in responses instead. For example, you specify a listing duration for an listing when you use AddItem. But, the GetItem response does not return the listing duration. Instead, it returns the start time and the end time of the listing.
(out) means the value cannot be specified as input. It is only returned in responses.

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 (see Code Lists). 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:

Certain arguments may become valid or invalid according to other values specified in the request. For example, the ListingDuration code list does not programmatically specify which durations are valid for Chinese Auction listings. Instead, this kind of information is described in the code list annotations.
Certain values may become required when other values are specified in the request. For example, if you specify a shipping option, you must also specify a shipping region. This kind of information is available in this documentation (see Listing Items).

Release Versions

The release version is the version number of the eBay Trading API that you are programming against (e.g., 631). 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. If you are an SDK user and are considering updating your SDK to a more recent version, see the Readme file for your SDK.

This section covers the following topics:

The eBay Developers Program Release Cycle

When to Update the Schema

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 (Gateway URLs) and Specifying the Schema Version in the Message Payload).

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.

If you are using the eBay SDK for Java, you can determine the WSDL version by creating and setting up an ApiContext object and inspecting the WSDLVersion property (using the ApiContext.getWSDLVersion( ) method). Compare that version with the version on the eBay Developers Program site if you are considering whether to download a new WSDL version.

If you are using the eBay SDK for .NET, you can determine the WSDL version by creating and setting up an ApiContext object and inspecting the Version property. Compare that version with the version on the eBay Developers Program site if you are considering whether to download a new WSDL version.

When a new version of the API becomes available, we announce it in the newsletter (see eBay Developers Program News). 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 Newsletter or 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 newsletter and release notes, we add an "i" suffix to version numbers to clarify which versions are in effect internationally (e.g., "Version 349i"). 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 Listing Items 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:

For numeric data types, we use int (32 bit) instead of integer and float instead of decimal (for percentage values).
We derive the core monetary amount type from double.
We return time values in GMT/UTC, using the ISO format. However, some development environments (e.g., the Java 2 Platform and the Microsoft .NET Framework) convert time values returned in SOAP messages to the time zone specified in your environment's locale.

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

User-Contributed Notes