Some base components have predefined lists of possible input and output values (e.g., listing durations). Each code list is a list 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 request. If you send in an undefined value (including a misspelled value), an error is returned.

The naming convention we use for the code list types is the name of the component followed by "CodeType":

ComponentNameCodeType

The following example is a snippet from ListingDurationCodeType and shows that the ListingDuration fields can 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.

This 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 CustomCode.

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 reference documentation.
  • 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.