Trading API

Simple Schema Types

The eBay Schema makes use of many simple schema types. Further, various other complexTypes and simpleTypes are based on these simple schema types (e.g. OrderIDType and AmountType).

Except where specified, the data types in the table below follow the conventions for XML Schema simple types as described by the World Wide Web Consortium in XML Schema Part 2: Datatypes.

Data Type Description
anyURI

Specifies a Uniform Resource Identifier (URI), a compact sequence of characters that identifies an abstract or physical resource.

The anyURI type is used most often to specify Uniform Resource Locators (URLs), such as a web page URL (e.g., ViewItemURL) or a file location URL (e.g., PictureURL), but can also be used for email addresses and other valid URI schemes.

xs:anyURI is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

base64Binary

Specifies Base64-encoded arbitrary binary data. The values for this datatype uses only ASCII and EBCDIC characters in the encoding. That is, a base64Binary value uses only the following characters: a-z, A-Z, 0-9, the plus sign (+), the forward slash (/) and the equal sign (=), together with the characters defined as white space (e.g., one or more space (#x20) characters, carriage returns, line feeds, or tabs). No other characters are allowed.

This binary content may be image files or compressed text files, such as a zipped XML payload file.

xs:base64Binary is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

boolean

Specifies binary-valued logic (true/false). Possible input values are true, false, 1, and 0. Possible output values are true and false only (not 1 or 0).

In the API, some fields that are currently defined as booleans might later be redefined as int values (enumerations) or as code lists. This would occur if more choices besides true and false become available. In these rare cases, we use a compatibility level to give you time to modify your application as needed. See the eBay Schema Versioning Strategy for information about how this works.

xs:boolean is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

dateTime

A specific instant of time.

Date-time values are in the ISO 8601 date and time format. Hours are in 24-hour format (e.g., 2:00:00pm is 14:00:00). Unless otherwise specified, all date-time values are recorded in Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT) or Zulu (because the time portion of the time stamp ends with a Z). That is, time values do not reflect the time zone shown on the eBay Web site. Here is an example of the date-time format:

YYYY-MM-DDTHH:MM:SS.SSSZ (e.g., 2004-08-04T19:09:02.768Z)

See Time Values for information about how to convert between local time zones and GMT.

We use the dateTime data type to convey start and end times, the official eBay time, and other time values.

xs:dateTime is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

decimal

A decimal value of arbitrary precision.

In the API, most fields of type decimal can contain the digits 0-9, a hyphen to designate negative numbers as needed, and a period (".") for the decimal separator. Decimal values should never include a thousands separator.

A whole number (i.e., without a period) can be passed as a decimal value.

We typically use the decimal data type to convey values related to units of measure. See individual topics for specific restrictions beyond this for fields of type decimal.

xs:decimal is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

double

A double-precision 64-bit floating point type.

In the API, most fields of type double can contain the digits 0-9, a hyphen to designate negative numbers as needed, and a period (".") for the decimal separator. Double values should never include a thousands separator.

We typically use the double data type to convey values related to monetary amounts. See AmountType, below.

In some cases, a whole number (i.e., without a period) can be passed or returned as a double value. See individual topics for specific restrictions beyond this for fields of type double.

xs:double is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

duration

A length of time.

Duration values are in the ISO 8601 duration format, where P represents "Period", nY represents the number of years, nM the number of months, nD the number of days, T is the date/time separator, nH the number of hours, nM the number of minutes, and nS the number of seconds. So P2DT23H32M51S means "A period of 2 days, 23 hours, 32 minutes, and 51 seconds".

PnYnMnDTnH nMnS (e.g., P2DT23H32M51S)

We use the duration data type to convey values like the time left until a listing ends. For ended listings, the time left is PT0S (zero seconds).

xs:duration is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

float

A single-precision 32-bit floating point type.

In the API, most fields of type float can contain the digits 0-9, a hyphen to designate negative numbers as needed, and a period (".") for the decimal separator. Float values should never include a thousands separator.

We typically use the float data type to convey values related to percentages. See individual topics for specific restrictions beyond this for fields of type float.

xs:float is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

int

A 32-bit integer value between -2147483648 and 2147483647.

In the API, most fields of type int can contain digits 0-9, and hyphen to indicate negative numbers. Some input fields restrict the input to particular values or a range of values. These cases are noted in the associated topic for the specific input field.

We typically use the int data type for enumerations, counts (e.g., how many items are returned), quantities, certain kinds of IDs (other IDs are strings), and similar concepts.

xs:int is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

long A value between -9223372036854775808 and 9223372036854775807.

xs:long is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

string

A string of characters. All characters in the Unicode character set are supported.

Character entity references are used for escaping markup-significant characters. For example, use &amp; for the & (ampersand) character. &lt; for the < (less-than sign) character, and &gt; for the > (greater-than sign) character. It is a good idea to escape such characters in requests instead of using a CDATA construct. Responses from eBay do not include CDATA constructs.

Note that messages from eBay may contain HTML or XML markup within the message text. In this case, the markup elements within the text are escaped (e.g., &lt;![CDATA[ ... ]]&gt;).

Some string input fields (e.g., Item.SubTitle) do not have a known set of possible values. For these arguments, the schema documentation specifies the maximum permitted length in characters.

Other fields (e.g., CategoryID) do have a known set of possible values. Therefore, the maximum length is not specified in the schema documentation.

xs:string is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

time

A specific instant of time.

Time values are in the ISO 8601 date and time format. Hours are in 24-hour format (e.g., 2:00:00pm is 14:00:00). Unless otherwise specified, all time values are recorded in Universal Coordinated Time (UTC), also known as Greenwich Mean Time (GMT) or Zulu (because the time portion of the time stamp ends with a Z). That is, time values do not reflect the time zone shown on the eBay Web site. Here is an example of the time format:

THH:MM:SS.SSSZ (e.g., T19:09:02.768Z)

See Time Values for information about how to convert between local time zones and GMT.

We typically use the time data type to convey a daily recurring time for scheduled tasks.

xs:time is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

token

A set of normalized strings.

In the API, this type of string contains no white space, by convention.

We typically use token to constrain a field to a specified set of normalized string values. For such a field, we define these values in an enumeration that uses token as its base type. For example, CountryCodeType defines the standard set of country abbreviations that eBay recognizes. In some cases, we define the valid values in a call like GeteBayDetails.

If "CustomCode" is returned as an enumeration value, it means we're sending you a placeholder value because we think your application won't recogize the real value. This occurs when you specify a version that is older than the version in which the real value was introduced in the API. To get the real value, upgrade your application to be compatible with a newer version of the API. See the eBay Schema Versioning Strategy for details about how your request version controls output data.

xs:token is part of the XML schema namespace defined as:

xmlns:xs="http://www.w3.org/2001/XMLSchema"

AmountType

An eBay-defined complex type for specifying monetary amounts.

A double value (e.g., 1.00 or 1.0) is meaningful as an amount when accompanied by a specification of the currency, in which case the value specifies the amount in that currency.

In the API, an object of type AmountType expresses both the value (a decimal) and the currency.

We typically use the AmountType data type to specify details such as prices, fees, costs, and payments.

In some cases, a whole number (i.e., without a period) can be passed or returned as a monetary value. This is necessary to support certain currencies that are only expressed as whole numbers (like the Italian Lira and Spanish Peseta).

Because a double is used to represent the amount, this also means whole monetary amounts may be returned with only one 0 after the decimal. For example, a dollar value could be returned as 1.0 instead of 1.00 in calls like AddItem. See individual topics for specific restrictions beyond this for fields of type Amount.

Repeatable (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>AmEx</PaymentMethods>
<PaymentMethods>PersonalCheck</PaymentMethods>
<PaymentMethods>VisaMC</PaymentMethods>
<PaymentMethods>PayPal</PaymentMethods>
<PayPalEmailAddress>mypaypalaccountemail@ebay.com</PayPalEmailAddress>
... other elements here ...

Multiplicity Notation

Sample XML notation Corresponding doc notation Meaning §
minOccurs="0" maxOccurs="unbounded" [0..*] Zero or more
minOccurs="0"
minOccurs="0" maxOccurs="1"
[0..1] Zero or one
minOccurs="0" maxOccurs="6" [0..6] Zero to six

§  While this is the general meaning, be sure to read the description of the particular field: it may state an exception for a particular use.



Copyright © 2005–2015 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.