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:
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 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:
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.
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.
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:
minOccurs="0"in the schema so that Item can be used in both cases.
minOccurs="0"in the schema to account for this "pre-filling" use case.
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.
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:
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.
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.
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:
See eBay Types for a list of data types and information about working with time values.
Copyright © 2014-2020 eBay Inc. All rights reserved.