Overview of the API Schema
This section introduces the major components that are available in the API schema.
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 (but not all fields in these types are used by all calls). Below are some examples of the fields in these base types:
- All call 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.
- ErrorLanguage — 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.
- WarningLevel — Use this to control whether to retrieve warnings if you pass in unrecognized fields. See Customizing Your Application's Error Handling Abilities.
- All call responses 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.
- Ack (Acknowledgement) — All responses return a standard acknowledgement element that indicates the success, failure, or partial failure of a call.
- Timestamp — 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 call requests support a MessageID element and all responses support a CorrelationID element. If you pass a MessageID 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 in the CorrelationID field of 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., AddItemRequestType and AddItemResponseType for the AddItem call) are derived from the abstract request/response types. The concrete 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 concrete type names is the name of the call followed by "Request" or "Response":
The figures below illustrate the request and response content models.
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).
A Request Type
The figure below shows the content model for a response (in this case, an AddItem response).
A Response Type
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.
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).
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>
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 (Introduction))
- User (see Users)
- Transaction (see Order Line Items)
- 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.
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.
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, and they must be spelled in the same way as they are spelled in that list.
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.
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
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 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 (
<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>firstname.lastname@example.org</PayPalEmailAddress> ... other elements here ...
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.
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.
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_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 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":
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.
Portions of a Code List (XSD)
<xs:simpleType name="ListingDurationCodeType"> <xs:annotation> <xs:documentation> 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:documentation> </xs:annotation> <xs:restriction base="xs:token"> <xs:enumeration value="Days_1"> <xs:annotation> <xs:documentation> 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. </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>
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.
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
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 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 Creating Item Listings).
The release version is the version number of the eBay Trading API that you are programming against (e.g., 1131). See Where to Find the eBay Schema Files to download the latest schema.
The Trading API has a release 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
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.
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.
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,
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
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 values, we use the int (32-bit) data type instead of long (64-bit), 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.