As of February 2020, the lowest supported version is 1097.
This topic describes eBay's versioning strategy for the Trading API (and Shopping API), which enables us to evolve the schema while maintaining backward compatibility for at least 18 months. This strategy is intended to address these concerns:
In each release, we do our best to update the schema in a backward-compatible way. However, sometimes we need to make changes that aren't backward compatible:
xs:int
),
but in a future enhancement we might need a way to allow decimal fractions for
the same value (xs:double
). If your application is expecting a field to return
an integer at runtime and we start returning a double instead, your application could fail.
So, we need a way to avoid changing the type directly.maxOccurs="unbounded"
).
As some toolkits interpret repeating fields as arrays, this would be equivalent
to a type change.When such changes are necessary, we need a way to gracefully phase in the new approach and gracefully phase out the old one. (That is, we need to make changes without causing third-party applications to fail unexpectedly, and applications need to be designed to accommodate routine changes.) This approach is described below.
Basic Schema Concepts
Versioning Strategy Key Points
eBay's Version Support Schedule
Schema Changes That Affect Compatibility
Logical Changes That Affect Compatibility
Schema Versions and Requirements for Compatible Application Check
Upgrading Applications to Support New Versions
Also see:
Version-Dependent Logical Changes
Before reading this document, you should be familiar with these basic concepts.
Concept | Description |
---|---|
object | eBay's schema consists of these basic building blocks:
All of these objects are subject to the usage policies described in this document. |
schema version | eBay has releases to all of its marketplaces every two weeks. These releases may include new features, functional changes, bug fixes, and/or performance updates. Not all releases will require an update to the Trading/Shopping WSDLs and associated docs. If a WSDL/doc update is not made for a release, the Trading and Shopping API Release Notes will state this. All Trading API schema versions are numbered (1157, 1159, 1161, and so forth). The versions are always odd numbers. We release the same code to international sites (e.g., ebay.co.uk) at the same time as the US release. (We use the same version of the schema for both US and international releases.) The Release Notes list all schema versions and their US release dates, as well as the changes that were made in each release. |
request version | With each API request, you specify the version of the schema your
client software is using. The request version helps eBay determine which objects and business logic we should use to process the request. The version can also affect the response schema, because when we have replaced an object, we check the request version to decide whether to return the old object. See Schema Changes That Affect Compatibility below. |
This section summarizes key points you should understand about our versioning strategy. These points are explained in more detail in later sections.
A deprecated object is an object that we no longer recommend. The schema version when this deprecation occurs is the object's deprecation version. For example, if we deprecated an object called "Flavor" in version 1161 of the schema, then the deprecation version for that object was 1161.
Whenever we deprecate an object, we also delete the object from the latest schema at the same time (unless otherwise noted). Your application should not be affected by these deletions until you upgrade to a newer version of the schema. (See the object deprecation schedule for a list of previously deprecated objects that have been deleted from the schema.)
We control a deprecated object's usage based on the request version:
See Deprecation of Existing Objects for more details.
We increment the lowest supported version every 6 months.
The lowest supported version will be 18 months old. See eBay's Version Support Schedule.
Objects that were deprecated in unsupported versions (more than 18 months old) may no longer work, or may stop working without notice. Applications should remove dependencies on deprecated objects as early as possible.
In February and August of each year, eBay increments the lowest supported schema version.
The table below shows eBay's schema version support schedule. The row with bold text indicates the current lowest supported version. Rows with gray text indicate future versions that are not yet published or past versions that are no longer supported.
Version Support Schedule (Projected)
Schema Version | Lowest Supported Version as of |
---|---|
1097 | February 2020 |
1123 | August 2020 |
1149 | February 2021 |
1175 | August 2021 |
1201 | February 2022 |
1227 | August 2022 |
Here's an example of how to interpret the table:
Note: In rare cases when it becomes necessary,
eBay reserves the right to drop support for an object immediately.
This could be due to a sudden business development or to an unanticipated design issue. In these cases, we may provide you with only limited notice of deprecation, and we may drop support for the object right away. This helps you avoid undesirable adoption of unusable features. When we have needed to do this in the past, it has occurred within a release or two of the object's initial appearance. |
Here's how this schedule will affect you:
Important: Once a schema version is no longer supported, objects that were deprecated as of that version (or earlier) are not supported, regardless of the request version.
Note: By "not supported", we mean that the
deprecated object will no longer work, and eBay will not address issues you
report related to the deprecated object (or functionality). Applications that still depend on unsupported objects do so at their own risk. If you use unsupported objects, your application may encounter severe errors. |
eBay makes three basic kinds of changes to the schema:
In many cases, these changes will not affect your application until you upgrade to a newer schema. The effects can depend on whether your application happens to use the functionality that has changed, and the version of the schema you are using.
We do our best to keep you informed of schema changes through the schema documentation, release notes, the eBay Developer Program Blog, site status, and other mechanisms.
We can introduce new objects at any time and at any level of the schema.
Usually, the request version doesn't control your ability to use new elements or calls
(unless otherwise noted). For example, new output elements are usually returned for all
request versions. We add an xs:any
element to the end of each type
to express this openness. By policy we also try to add elements to the end of a type before the xs:any
element. (This is only a policy; it's not a guarantee.)
Note: Our approach gives you the flexibility to adopt individual elements without updating your request version, if necessary. This can be useful when your application uses the same request version for all calls, but you only have the time or resources to adopt one particular feature. |
However, the request version does control whether we return new code type values (enumerations) in responses. If your software is already using an element that is a code type, you need a safe way to handle new values that your software doesn't recognize yet. Therefore, we check your request version, and then in our response we map any newer code type values to a default value you can recognize (CustomCode) instead. (See Overview of the API Schema for more information about code types.)
For backward compatibility:
As stated earlier, a deprecated object is an object that we no longer recommend (although we still support it). We do our best not to deprecate objects, but sometimes it becomes necessary to deprecate an object due to business, legal, or functional issues. The schema version when this deprecation occurs is the object's deprecation version.
Here's what happens in the API:
Here's the behavior you can expect:
Context | Description |
---|---|
Input |
You can still pass in the deprecated object (unless otherwise noted).
You may receive a warning in the response. If the deprecated object has been replaced and you supply both objects in the request, the new object is given precedence (the deprecated object is ignored). |
Output |
If the request version is less than (<) the deprecation version:
|
When testing a call, you can set WarningLevel to High to identify whether you are using deprecated objects in your request.
We sometimes need to effectively change an existing object to a different type, or replace or rename an object. Rather than replacing an object directly, we usually use the addition and deprecation approaches described above. That is, we add a new object with a different name and we deprecate the old object.
For backward compatibility:
Client software that depends on the old object should start using (or expecting) the new one as soon as possible. This is particularly important if the old object reflects functionality that is inconsistent with current eBay site logic. Otherwise, your application's users may see unexpected (and undesirable) behavior.
In some cases, we may change an existing object's behavior without replacing it. See Logical Changes That Affect Compatibility for an example. Again, we do our best to minimize these kinds of changes.
Incompatible changes can be logical or functional; not necessarily changes to the schema itself. As with deprecated objects, we implement these kinds of changes based on the version whenever possible.
For example, suppose a call returns a node called ManyDetails:
In this example, we are not deprecating ManyDetails or changing the schema in any way, but this change would break any application that specifically looks for ManyDetails and expects it to be returned by default. Therefore, we would implement this change so that only clients specifying request version 503 or higher would see the new behavior.
See the Version-Dependent Logical Changes table for a summary of objects that behave differently based on the request version.
To comply with eBay's requirements for Compatible Application Check, new applications must use the latest version that is available in the Production environment at the time of Compatible Application Check.
For example, suppose your application had a Compatible Application Check at version 525. If version 555 is the latest version available in production, then you can still use version 525 or higher.
On the other hand, suppose you submit a new request for a Compatible Application Check. If version 555 is the latest version available in production, you would need to use the latest version (555 in this example).
We increment the lowest supported version periodically. Make sure you understand how your application will be affected by these changes (see eBay's Version Support Schedule). Plan to start adjusting your application to use the latest version before we drop support for the version you are using. (You do not necessarily need to redo a Compatible Application Check for your application if you are only upgrading it to a newer version.)
At a high level, we suggest you follow this process when you upgrade an application to a newer version of the schema:
You may see some people use the older term "compatibility level" instead of "request version" in the Forums, KB articles, obsolete documentation, and other resources. The term is also used in the X-EBAY-API-COMPATIBILITY-LEVEL header, for XML requests. This is simply an older name for the request version.
Copyright © 2005–2020 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.