All Trading API applications must use the UTF-8 encoding scheme and not ISO-8859-1.

Additionally, all applications must validate text strings specified in the body of each request to make sure the characters are UTF-8 compliant. It is not sufficient to simply transmit information to eBay in UTF-8 format. Characters provided by users (e.g., in item descriptions, street addresses, names of persons, etc.,) must be converted to UTF-8 if they are received in a non-UTF-8 charset (e.g., from a browser for which the encoding was not UTF-8,) or stored in a database in a non-UTF-8 charset.

For additional information, refer to:

Specify the target site

In order to route a request to the correct target site, specify the numeric site ID of the target site in the request as follows:

Depending on the specific purpose of a call, the site ID value is usually specified as the site on which an item is listed or on which the user is registered.

Some request also require that the SiteCodeType be included in the body of the request, depending on the type of call being issued. For example, when calling AddItem, the target site must also be specified using the Item.Site input field. The site specified for the item should match the site specified elsewhere in the request.

Note: For a list of valid site names and IDs, call GeteBayDetails or refer to SiteCodeType.

Site ID and request validation

The eBay site specified in requests affects the business logic and validation rules that are applied to the request.

Note: Sometimes validation rules are determined by a combination of site ID, the user's registration address, and other information. Refer to the pertinent reference documentation for information about any possible inter-dependencies.

For example, the site ID value specified may affect data such as:

  • The list of available categories, including the availability of categories that support item specifics, product details, and VAT/business items

  • The site specified in AddItem calls may impact item/listing visiblity within some searches

    For example, when calling GetItem for the US site, listings that appear in categories on the UK site are not returned/visible.

  • International business requirements (e.g., whether a listing is subject to VAT)
  • Values returned in converted prices (e.g., Item.ListingDetails.ConvertedStartPrice)
  • Shipping cost calculations
  • Default units of measure (e.g., pounds vs. kilograms)

  • Item-related time stamps that are displayed on the eBay Web site

    For example, item revision times might use localized time stamps such as PDT. These time stamps are not necessarily apparent via the API, which expresses time values in GMT.

  • Localization of certain standardized string values within listing details
  • The language of error and warning strings that are returned
  • Other data which varies based on the call being used

However, the site ID specified does not necessarily act as a filter for limiting data returned. It depends on the nature of the request:

  • Item IDs are unique across all sites.

    Therefore, an item ID on the UK site would not be re-used for a different listing on the US site, so calls that filter data by the item ID (e.g., GetItem,) retrieve the same listing regardless of which site is specified. This is important because sometimes only the item ID is available and the specific site on which the item was listed is not known. In such cases, the site ID value passed in only affects site-specific data such as ConvertedStartPrice as indicated above.

  • Similarly, user IDs are unique across all sites.

    This means that calls that retrieve data by a user ID (e.g., GetUser and GetSellerList) retrieve the data regardless the site on which a user is registered and which site is specified in the request.

    Again, this is important because the site on which a user is actually registered may not be known.

  • Site-specific user information, such as a subscription to an eBay store on the US site, depends on the site specified in the request.

  • Category IDs are not unique across all sites and each site has variations in the category hierarchy. Therefore, site ID values do have a filtering effect when retrieving category-based data and also affect validation when listing items.

    Calls such as AddItem will fail if a category ID is provided that is incorrect for the specified site. Calls that filter results by category ID (e.g., GetCategories,) generally retrieve data that is only applicable to the site specified in the request.

  • Other types of user information (e.g., registration date,) do not depend on the site specified in the request.

Although the benefit of including the Item.Site field may not be externally apparent for some calls, other calls may actually fail or may not behave as expected if Item.Site is not included in the request or if the value provided does not match the value specified elsewhere in the call.

Therefore, it is strongly recommended that Item.Site always be specified when listing an item. For some applications, it may be convenient to utilize reusable classes, modules, or functions to set the site ID value and the Item.Site field at the same time so that their values always match.

Specify the schema version

For each request, the version of the schema that is being used must be specified. How this is done depends on which format is being used:

  • When using the XML version, the schema version is specified using the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header.

    For more information, including how to download a schema file, refer to Using the XML version of the Trading API.

  • When using the SOAP version, the schema/WSDL version is specified using the version query parameter.

    For more information, including how to download a WSDL, refer to Using the SOAP version of the Trading API.

When to update the schema

If an 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 do not include the value CustomCode. If this value is included, it indicates that a code list being used is out of date with the version on the server. Refer to Code lists for additional information.

You should plan to regularly update your version of the schema if you want to support the latest data that eBay has specified.

If you are using the SOAP API and you do not plan to update your application each time a new version of the WSDL becomes available, you should use the URL with the numbered version identifier. If you plan to always retrieve the latest changes available, it may be more convenient to use the URL with the latest version identifier.