findHalfItems

Searches Half.com for items associated with the specified product ID. The number of item listings that can be returned per call varies depending on the paginationInput specified. Returns a maximum of 1500 items.

findHalfItems Input

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

findHalfItems Output

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

<?xml version="1.0" encoding="utf-8"?>
<findHalfItemsResponse xmlns="http://www.ebay.com/marketplace/half/v1/services">
  <!-- Standard Output Fields -->
  <ack> AckValue </ack>
  <errorMessage> ErrorMessage
    <error> ErrorData
      <category> ErrorCategory </category>
      <domain> string </domain>
      <errorId> long </errorId>
      <exceptionId> token </exceptionId>
      <message> string </message>
      <parameter name="string"> ErrorParameter (string) </parameter>
      <!-- ... more parameter nodes here ... -->
      <severity> ErrorSeverity </severity>
      <subdomain> string </subdomain>
    </error>
    <!-- ... more error nodes here ... -->
  </errorMessage>
  <timestamp> dateTime </timestamp>
  <version> string </version>
  <!-- Call-specific Output Fields -->
  <paginationOutput> PaginationOutputType
    <entriesPerPage> int </entriesPerPage>
    <pageNumber> int </pageNumber>
    <totalEntries> int </totalEntries>
    <totalPages> int </totalPages>
  </paginationOutput>
  <product> HalfCatalogProductType
    <BestFixedPrice currencyId="string"> Amount (double) </BestFixedPrice>
    <BestRentalPrice currencyId="string"> Amount (double) </BestRentalPrice>
    <categoryName> string </categoryName>
    <!-- ... more categoryName nodes here ... -->
    <detailsURL> anyURI </detailsURL>
    <item> ItemType
      <comments> string </comments>
      <condition> HalfItemConditionCodeType </condition>
      <description> string </description>
      <excludedShippingAreas> string </excludedShippingAreas>
      <itemID> string </itemID>
      <itemLocation> string </itemLocation>
      <itemURL> anyURI </itemURL>
      <price currencyId="string"> Amount (double) </price>
      <quantity> int </quantity>
      <rentalPrice duration="RentalDurationType" currencyId="string"> RentalAmount (double) </rentalPrice>
      <!-- ... more rentalPrice nodes here ... -->
      <seller> UserType
        <feedbackScore> int </feedbackScore>
        <positiveFeedbackPercent> float </positiveFeedbackPercent>
        <userID> string </userID>
      </seller>
      <shippingService> ShippingServiceOptionsType
        <cost currencyId="string"> Amount (double) </cost>
        <expeditedService> boolean </expeditedService>
        <type> type </type>
      </shippingService>
      <!-- ... more shippingService nodes here ... -->
      <storefront> StorefrontType
        <storeName> string </storeName>
        <storeURL> anyURI </storeURL>
      </storefront>
    </item>
    <!-- ... more item nodes here ... -->
    <itemSpecifics> NameValueListArrayType
      <nameValueList> NameValueListType
        <name> string </name>
        <value> string </value>
        <!-- ... more value nodes here ... -->
      </nameValueList>
      <!-- ... more nameValueList nodes here ... -->
    </itemSpecifics>
    <listPrice currencyId="string"> Amount (double) </listPrice>
    <productID type="ProductIDCodeType"> ProductIDType (string) </productID>
    <!-- ... more productID nodes here ... -->
    <reviewCount> int </reviewCount>
    <stockPhotoURL> anyURI </stockPhotoURL>
    <title> string </title>
  </product>
</findHalfItemsResponse>

Return Value	Type	Occurrence	Meaning

Standard Output Fields [Jump to call-specific fields]

ack	AckValue	Always	Indicates whether or not errors or warnings were generated during the processing of the request. Applicable values: • Failure (out) eBay encountered a fatal error during the processing of the request, causing the request to fail. When a serious application-level error occurs, the error is returned instead of the business data. • PartialFailure (out) eBay successfully processed the request, but one or more non-fatal errors occurred during the processing. For best results, requests should return without warning messages. Inspect the message details and resolve any problems before resubmitting the request. • Success (out) eBay successfully processed the request and the business data is returned in the response. Note that it is possible for a response to return Success, but still not contain the expected data in the result. • Warning (out) The request was successfully processed, but eBay encountered a non-fatal error during the processing. For best results, requests should return without warnings. Inspect the warning details and resolve the problem before resubmitting the request.
errorMessage	ErrorMessage	Conditionally	An error or warning that occurred when eBay processed the request. Not returned if the ack value is Success.
errorMessage.error	ErrorData	Conditionally, repeatable: [0..*]	Details about a single error.
errorMessage.error.category	ErrorCategory	Conditionally	There are three categories of errors: request errors, application errors, and system errors. Applicable values: • Application (out) An error occurred due to a problem with the request, with the most likely source being the application sending the request. For example, the request is missing a required data element or it contains an invalid field. The problem must be corrected before the request can be resent. Inspect the error message to find the cause of the problem. If the problem is due to an application error, modify the application and resend the request. If the error is due to invalid data, the source of the data must be corrected before you resend the resend request to eBay. • Request (out) An error occurred due to a problem with the request, with the most likely source being missing or invalid data in the request. The problem must be corrected before the request can be retried. Inspect the error message to find the cause of the problem. If the problem is a result of end-user data, alert the end-user to the problem and provide the means for them to correct the problem. Once the problem is resolved, resend the request to eBay. • System (out) Indicates that an error has occurred on the eBay system side. For example, a database or server could be down. Inspect the error message to find the cause of the problem. If the problem is on the eBay side, an application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form.
errorMessage.error.domain	string	Conditionally	Name of the domain upon which the error occurred. Domains include: Marketplace A business or validation error occurred in the service. SOA An exception occurred in the Service Oriented Architecture (SOA) framework.
errorMessage.error.errorId	long	Conditionally	Returned if there is an error. A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.
errorMessage.error.exceptionId	token	Conditionally	Unique identifier for an exception associated with an error.
errorMessage.error.message	string	Conditionally	A detailed description of the condition that resulted in the error.
errorMessage.error.parameter	ErrorParameter (string)	Conditionally, repeatable: [0..*]	Some warning and error messages return one or more variables that contain contextual information about the error. This is often the field or value that triggered the error.
errorMessage.error.parameter [ attribute name ]	string	Conditionally	The name of the parameter in the get of parameter types returned within the error type.
errorMessage.error.severity	ErrorSeverity	Conditionally	Indicates whether the error caused the request to fail (Error) or not (Warning). If the request fails and the source of the problem is within the application (such as a missing required element), please change the application before you retry the request. If the problem is due to end- user input data, please alert the end-user to the problem and provide the means for them to correct the data. Once the problem in the application or data is resolved, you can attempt to re- send the request to eBay. If the source of the problem is on eBay's side, you can retry the request without change for a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form. When a warning occurs, the error is returned in addition to the business data. In this case, you do not need to retry the request (as the original request was successful). However, depending on the cause or nature of the warning, you might need to contact either the end user or eBay to effect a long term solution to the problem to prevent it from reoccurring in the future. Applicable values: • Error (out) The request that triggered the error was not processed successfully. When a serious application-level error occurs, the error is returned instead of the business data. • Warning (out) The request was processed successfully, but something occurred that may affect your application or the user. For example, eBay may have changed a value the user sent in. In this case, eBay returns a normal, successful response and also returns the warning.
errorMessage.error.subdomain	string	Conditionally	Name of the subdomain upon which the error occurred. Subdomains include: Merchandising The error is specific to the Merchandising service. MarketplaceCommon The error is common to all Marketplace services.
timestamp	dateTime	Always	The date and time of the response.
version	string	Always	The release version that eBay used to process the request. Developer Technical Support may ask you for the version value if you work with them to troubleshoot issues. Note: The version in use is normally the latest release version, as specified in the release notes. Note that eBay releases the API to international sites about a week after the API version is released to the US site.

Call-specific Output Fields

paginationOutput	PaginationOutputType	Always	Controls the pagination of the result set. Child elements specify the maximum number of item listings to return per call and the page of data to return. No more than 1500 items can be retrieved for a given search, regardless of how many matches are found. This limit is enforced by the maximum page number allowed (60) and the maximum entries per page allowed (25).
paginationOutput .entriesPerPage	int	Always	Specifies the no of entries in the current page. Max: 25.
paginationOutput.pageNumber	int	Always	Specifies the current page of the response. Max: 60.
paginationOutput.totalEntries	int	Always	Specifies the total no of entries found.
paginationOutput.totalPages	int	Always	Specifies the number of the pages the response can span.
product	HalfCatalogProductType	Always	Info about a catalog product on Half.com. This contains stock information about a particular DVD, book, or other product.
product.BestFixedPrice	Amount (double)	Conditionally	The lowest fixed price that the item is offered for on the site.
product.BestFixedPrice [ attribute currencyId ]	string	Conditionally	Currency in which the monetary amount is specified.
product.BestRentalPrice	Amount (double)	Conditionally	The lowest price for which the item is offered for rent, at a 125 day duration, on the site.
product.BestRentalPrice [ attribute currencyId ]	string	Conditionally	Currency in which the monetary amount is specified.
product.categoryName	string	Always, repeatable: [1..*]	The name of the domain in which the product was found. If the product is mapped to multiple domains, Half.com returns the most applicable domain (as determined by Half.com).
product.detailsURL	anyURI	Always	Fully qualified URL for optional information about the product, such as a movie's description or film credits. This information is hosted through the Half.com Web site and it cannot be edited. Portions of the content are protected by copyright. Applications can include this URL as a link in product search results so that end users can view additional descriptive details about the product. This is usually always returned when Product is returned, but it may be safest to check for the existence of this field.
product.item	ItemType	Always, repeatable: [1..*]	Contains data for an item listing.
product.item.comments	string	Conditionally	Comments about the item as entered by the seller.
product.item.condition	HalfItemConditionCodeType	Always	Returns the Half.com condition code for the item. For example, "brand new," "used," etc. Applicable values: • Acceptable (out) The item might have minor damage, or it might be missing a part or accessory. However, the item is still intact and is in working order. • BrandNew (out) New, unread, unused and in perfect condition. • CustomCode (out) Reserved for internal or future use. • Good (out) The item shows very minimal use or damage and it still includes all accessories (such as dust jackets, liner notes, and cases). You might use the item yourself, but probably wouldn't give it as a gift. • LikeNew (out) Item still in original packaging, no wear and tear, and all facets of the product are intact. The item could easily be mistaken for brand new. • VeryGood (out) Doesn't look brand new, but it has no easily noticeable damage and very minimal wear and tear. You could give it to a good friend as a gift.
product.item.description	string	Conditionally	Description about the item as entered by the seller.
product.item .excludedShippingAreas	string	Always	Restricted Shipping Areas as entered by the seller using comma-separated locations.
product.item.itemID	string	Always	The ID that uniquely identifies the item listing on Half.com Max length: 19 (Note: The eBay database specifies 38. Currently, Item IDs are usually 9 to 12 digits).
product.item.itemLocation	string	Conditionally	Returns the location of the item from where it will be shipped from.
product.item.itemURL	anyURI	Conditionally	The URL to view this listing on half.com. This URL is optimized to support natural search.
product.item.price	Amount (double)	Conditionally	The current price of the item in the currency of the site on which the item is listed. That is, CurrentPrice is in the original listing currency. This field is not returned if the item is a rental (ItemFilter.name is set to Rental).
product.item.price [ attribute currencyId ]	string	Conditionally	Currency in which the monetary amount is specified.
product.item.quantity	int	Always	The number of items the seller is offering in the listing.
product.item.rentalPrice	RentalAmount (double)	Conditionally, repeatable: [0..*]	The price of the rental item in the currency of the site on which the item is listed. This field is returned if the item is available as a rental item. Currently, only items in the Books catalog are eligible as rental items.
product.item.rentalPrice [ attribute duration ]	RentalDurationType	Conditionally, repeatable: [0..*]	The amount of time for which the item will be rented out. For a list of possible enumeration values, see RentalDurationType.
product.item.rentalPrice [ attribute currencyId ]	string	Conditionally, repeatable: [0..*]	Currency in which the monetary amount is specified.
product.item.seller	UserType	Always	Container for information about this listing's seller.
product.item.seller .feedbackScore	int	Always	The aggregate feedback score of a user. A user's feedback score is the net positive feedback minus the net negative feedback left for the user. Feedback scores are a quantitative expression of the desirability of dealing with a user as a buyer or a seller in transactions. Each transaction can result in one feedback entry for a given user. (The buyer can leave feedback for the seller, and the seller can leave feedback for the buyer.) That one feedback can be positive, negative, or neutral. The aggregate feedback score of a user represents that user's overall feedback score (referred to as a "feedback rating" on the eBay site). If the user has chosen to make their feedback private, then FeedbackScore is not returned and FeedbackPrivate is returned with a value of true.
product.item.seller .positiveFeedbackPercent	float	Always	A seller's positive feedback score. The percentage value of a seller's positive feedback is calculated by dividing the seller's positive feedback score by their negative feedback score. The last 12 months of feedback scores are taken into consideration for this calculation.
product.item.seller.userID	string	Always	The user's unique eBay user ID.
product.item.shippingService	ShippingServiceOptionsType	Always, repeatable: [1..*]	Contains basic shipping-related costs for the item. If Item.Quantity is greater than 1, this is the shipping cost for one item. If the seller offers a choice of more than one shipping service (such as UPS Ground and USPS Media mail), this is the cost of the "first" shipping option (usually the lowest cost option). If a listing has shipping costs, use GetShippingCosts if you want to get more details about the services and costs that the seller is offering.
product.item.shippingService .cost	Amount (double)	Always	The cost of shippping for the service as fixed by Half.com.
product.item.shippingService .cost [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified.
product.item.shippingService .expeditedService	boolean	Always	Indicates an expedited shipping service.
product.item.shippingService .type	type	Always	A domestic shipping service offered for shipping the item (for example, UPS Ground). Applicable values: • ShippingMethodExpress (out) Indicates an expedited shipping method. • ShippingMethodStandard (out) Indicates either a Media Mail or Ground shipping method.
product.item.storefront	StorefrontType	Always	Returns the seller's store information if the seller has an eBay store. Returns a blank store if the seller does not have an eBay storefront.
product.item.storefront .storeName	string	Always	The name of the sellerId's store on Half.com. Not returned if the seller does not have a store. Max length: 200.
product.item.storefront .storeURL	anyURI	Conditionally	The URL of the seller's Half.com Store page. Not returned if the seller does not have a store.
product.itemSpecifics	NameValueListArrayType	Always	A list of name/value pairs that are included in the product's pre-filled Item Specifics. These indicate common aspects or characteristics of the product, such as Publisher (for a book). Also see ProductID for ISBN, UPC, or EAN values, if applicable. This is usually returned. (We are not aware of any cases in which this node is not be returned. However, it may be safest to check for the existence of this node.)
product.itemSpecifics .nameValueList	NameValueListType	Always, repeatable: [1..*]	This list is an array of Item Specifics, which are category-specific fields that the seller added to describe the listing. The names of these fields are different for items in different categories, so they're returned in a generic name/value structure. For example, Item Specifics for a car might include a field like Make=Toyota (where Make is returned in Name, and Toyota is returned in Value) and Model=Prius (where Model is returned in Name, and Prius is returned in Value). In multi-variation listings, the same name cannot appear in both the VariationSpecifics node and in the ItemSpecifics node. For FindProducts, this can also be an Item Specific that is defined for a product. That is, Item Specifics can be returned both for items and products in FindProducts.
product.itemSpecifics .nameValueList.name	string	Always	The name of the item specific. This field is returned only in responses if the seller included an item specific Name in the listing. However, if the seller didn't also include a corresponding value for the item specific, it is best to not display the name to name to avoid confusing users. For the item condition, this usually includes the word "Condition" for eBay US, UK, Australia, and India listings; and "Artikelzustand" for eBay Germany, Austria, and Switzerland listings. Note: Ignore item specifics with SIFFTAS in the name. These are for internal use by eBay and aren't meaningful to users.
product.itemSpecifics .nameValueList.value	string	Always, repeatable: [1..*]	A value for the item specific. This field is only returned in responses if the seller included a value for an item specific. In the GetSingleItem response, this field is always returned for each item specific that is returned (if any). However, if the seller didn't select a value for the item specific, this field may return empty, or it may return a value like "-", "Not Selected", or "Unspecified" (or the equivalent in the language of the site). For the item condition, this usually includes the word "New" or "Used" for eBay US, UK, Australia, and India listings; and "Neu" or "Gebraucht" for eBay Germany, Austria, and Switzerland listings.
product.listPrice	Amount (double)	Always	The list price (suggested retail price) of the item.
product.listPrice [ attribute currencyId ]	string	Always	Currency in which the monetary amount is specified.
product.productID	ProductIDType (string)	Always, repeatable: [1..*]	The Half.com or external IDs associated with the product. Use the Reference value as input to search for the same product in the future, or use the ISBN, EAN, or UPC value (if returned). The ISBN, EAN, and UPC values can also be useful as keys if your application is comparing products across different sites. Always returned when Product is returned.
product.productID [ attribute type ]	ProductIDCodeType	Always	The nature of identifier being used. For findHalfItems only Reference, ISBN, UPC, and EAN are supported. For a list of possible enumeration values, see ProductIDCodeType.
product.reviewCount	int	Always	The total number of reviews that are available for this product on the Half.com Web site. This can be greater than the number of reviews returned by FindProducts. In a future release, we will provide the capability to retrieve details about reviews. Always returned when Product is returned. Min: 0.
product.stockPhotoURL	anyURI	Conditionally	Fully qualified URL for a stock image (if any) that is associated with the Half.com catalog product. The URL is for the image Half.com usually displays in product search results (usually 70px tall). It may be helpful to calculate the dimensions of the photo programmatically before displaying it. Only returned if a URL is available for the product.
product.title	string	Always	The title of the product as specified in the catalog. Always returned when Product is returned.

findHalfItems Samples

New to making API calls? Please see Making an API Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Available samples:

Basic ↓ - Find a DVD on Half.com.
Condition-ISBN ↓ - Uses an ISBN to find item listings offering the specified textbook in new condition.

Sample: Basic

Find a DVD on Half.com.

Description

Bountiful Buyer is browsing for a DVD titled "Harry Potter and the Prisoner of Azkaban" on the Half.com site.

Input

To help Bountiful Buyer find the DVD she wants, your application accepts the keywords "Harry Potter and the Prisoner of Azkaban" supplied by Bountiful Buyer and does a product search using the Shopping API (using the FindHalfProducts call), as described in FindHalfProducts Sample: Basic Call

The FindHalfProducts call returns two types of productID, one that is of type "Reference" and one that is of type "UPC". The Reference ID is the eBay internal ID, the UPC ID is the universal product code. (If the item were a book instead of a DVD, there would be a ProductID of type "ISBN" rather than "UPC". You can use any of these returned product IDs as input to the findHalfItems call.

Using a productID returned by FindHalfProducts, call findHalfItems in the Half Finding API to get items matching Bountiful Buyer's request. The basic sample gets all items regardless of seller or condition, returning a maximum of 100 items, (4 pages of items displaying 20 items per page) as specified in the paginationInput settings.

SOAP format (HTTP POST). Also available is the .txt version of this XML.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://www.ebay.com/marketplace/half/v1/services">
<soap:Header/>
  <soap:Body>
  <ser:findHalfItemsRequest>
    <ser:productID type="Reference">30549257</ser:productID>
    <ser:paginationInput>
      <ser:pageNumber>4</ser:pageNumber>
      <ser:entriesPerPage>20</ser:entriesPerPage>
    </ser:paginationInput>
  </ser:findHalfItemsRequest>
  </soap:Body>
</soap:Envelope>

Output

SOAP format. Also available is the .txt version of this XML.

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   <soapenv:Header/>
   <soapenv:Body>
      <findHalfItemsResponse xmlns="http://www.ebay.com/marketplace/half/v1/services">
         <ack>Success</ack>
         <version>1.0.0</version>
         <timestamp>2011-03-14T17:09:35.697Z</timestamp>
         <paginationOutput>
            <pageNumber>1</pageNumber>
            <entriesPerPage>25</entriesPerPage>
            <totalEntries>1710</totalEntries>
            <totalPages>69</totalPages>
         </paginationOutput>
         <product>
            <title>Harry Potter and the Prisoner of Azkaban (DVD, 2004, 2-Disc Set, Widescreen)</title>
            <detailsURL>http://product.half.ebay.com/Harry-Potter-and-the-Prisoner-of-Azkaban-DVD-2004-2-Disc-Set-Widescreen_W0QQprZ30549257QQtgZinfo</detailsURL>
            <stockPhotoURL>http://i.ebayimg.com/14/!!eBk1S!!2M~$(KGrHqUOKp!E0Uc5hywYBNQ)HUyWzQ~~_7.JPG?set_id=89040003C1</stockPhotoURL>
            <productID type="Reference">30549257</productID>
            <productID type="UPC">085392844524</productID>
            <itemSpecifics>
               <nameValueList>
                  <name>Leading Role</name>
                  <value>Daniel Radcliffe</value>
                  <value>Emma Watson</value>
                  <value>Rupert Grint</value>
               </nameValueList>
               <nameValueList>
                  <name>Format</name>
                  <value>DVD</value>
               </nameValueList>
               <nameValueList>
                  <name>Director</name>
                  <value>Alfonso Cuaron</value>
               </nameValueList>
            </itemSpecifics>
            <item>
               <itemID>90000889583</itemID>
               <itemURL>http://product.half.ebay.com/Harry-Potter-and-the-Prisoner-of-Azkaban-DVD-2004_W0QQprZ30549257QQtgZvidetailsQQitemZ90000889583</itemURL>
               <quantity>100</quantity>
               <seller>
                  <userID>archana_half</userID>
                  <feedbackScore>200</feedbackScore>
                  <positiveFeedbackPercent>100.0</positiveFeedbackPercent>
               </seller>
               <price currencyId="$">1.0</price>
               <shippingService>
                  <type>ShippingMethodStandard</type>
                  <cost>2.99</cost>
                  <expeditedService>false</expeditedService>
               </shippingService>
               <itemLocation>san jose, CA</itemLocation>
               <excludedShippingAreas/>
               <condition>BrandNew</condition>
               <description/>
               <storefront>
                  <storeURL>http://shops.half.ebay.com/archna-half_W0QQsellerarchna_half</storeURL>
                  <storeName>archana_half</storeName>
               </storefront>
            </item>
            <item>
               <itemID>90000930335</itemID>
               <itemURL>http://product.half.ebay.com/Harry-Potter-and-the-Prisoner-of-Azkaban-DVD-2004_W0QQprZ30549257QQtgZvidetailsQQitemZ90000930335</itemURL>
               <quantity>100</quantity>
               <seller>
                  <userID>alm_us_01</userID>
                  <feedbackScore>219</feedbackScore>
                  <positiveFeedbackPercent>99.1</positiveFeedbackPercent>
               </seller>
               <price currencyId="$">1.0</price>
               <shippingService>
                  <type>ShippingMethodExpress</type>
                  <cost>5.49</cost>
                  <expeditedService>true</expeditedService>
               </shippingService>
               <shippingService>
                  <type>ShippingMethodStandard</type>
                  <cost>2.99</cost>
                  <expeditedService>false</expeditedService>
               </shippingService>
               <itemLocation>Multiple</itemLocation>
               <excludedShippingAreas>Alaska,Hawaii,PO Boxes(including APOs)</excludedShippingAreas>
               <condition>BrandNew</condition>
               <description/>
               <storefront>
                  <storeURL>http://shops.half.ebay.com/alm-us-01_W0QQsellerZalm_us_01</storeURL>
                  <storeName>alm_us_01</storeName>
               </storefront>
            </item>
            <listPrice currencyId="$">19.0</listPrice>
            <reviewCount>4</reviewCount>
         </product>
      </findHalfItemsResponse>
   </soapenv:Body>
</soapenv:Envelope>

Back to list of samples

Sample: Condition-ISBN

Uses an ISBN to find item listings offering the specified textbook in new condition.

Description

Bountiful Buyer is looking for a new textbook required by one of her college classes. She knows the ISBN number from the course syllabus.

Input

In this example, there is no need to get a product ID using FindHalfProducts from the Shopping API. The buyer knows the ISBN number and provides it to your application. Your application uses that number as the productID of type "ISBN" when making the call to findHalfItems. The itemFilter specifies that only item listings offering the book in brand new condition are returned.

The paginationInput settings specify that only one page of items is returned, with a maximum of 8 items.

SOAP format (HTTP POST). Also available is the .txt version of this XML.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://www.ebay.com/marketplace/half/v1/services">
<soap:Header/>
  <soap:Body>
    <ser:findHalfItemsRequest>
      <ser:productID type="UPC">085392844524</ser:productID>
      <ser:itemFilter>
        <ser:name>Condition</ser:name>
        <ser:value>BrandNew</ser:value>
      </ser:itemFilter>>
      <ser:paginationInput>
        <ser:pageNumber>1</ser:pageNumber>
        <ser:entriesPerPage>8</ser:entriesPerPage>
      </ser:paginationInput>
    </ser:findHalfItemsRequest>
  </soap:Body>
</soap:Envelope>

Output

SOAP format. Also available is the .txt version of this XML.

soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   <soapenv:Header/>
   <soapenv:Body>
      <findHalfItemsResponse xmlns="http://www.ebay.com/marketplace/half/v1/services">
         <ack>Success</ack>
         <version>1.0.0</version>
         <timestamp>2011-03-14T17:20:27.126Z</timestamp>
         <paginationOutput>
            <pageNumber>1</pageNumber>
            <entriesPerPage>2</entriesPerPage>
            <totalEntries>6</totalEntries>
            <totalPages>3</totalPages>
         </paginationOutput>
         <product>
            <title>Harry Potter and the Prisoner of Azkaban (DVD, 2004, 2-Disc Set, Widescreen)</title>
            <detailsURL>http://product.half.ebay.com/Harry-Potter-and-the-Prisoner-of-Azkaban-DVD-2004-2-Disc-Set-Widescreen_W0QQprZ30549257QQtgZinfo</detailsURL>
            <stockPhotoURL>http://i.ebayimg.com/14/!!eBk1S!!2M~$(KGrHqUOKp!E0Uc5hywYBNQ)HUyWzQ~~_7.JPG?set_id=89040003C1</stockPhotoURL>
            <productID type="Reference">30549257</productID>
            <productID type="UPC">085392844524</productID>
            <itemSpecifics>
               <nameValueList>
                  <name>Leading Role</name>
                  <value>Daniel Radcliffe</value>
                  <value>Emma Watson</value>
                  <value>Rupert Grint</value>
               </nameValueList>
               <nameValueList>
                  <name>Format</name>
                  <value>DVD</value>
               </nameValueList>
               <nameValueList>
                  <name>Director</name>
                  <value>Alfonso Cuaron</value>
               </nameValueList>
            </itemSpecifics>
            <item>
               <itemID>90000886702</itemID>
               <itemURL>http://product.half.ebay.com/Harry-Potter-and-the-Prisoner-of-Azkaban-DVD-2004_W0QQprZ30549257QQtgZvidetailsQQitemZ90000886702</itemURL>
               <quantity>91</quantity>
               <seller>
                  <userID>wchan_half4</userID>
                  <feedbackScore>101</feedbackScore>
                  <positiveFeedbackPercent>100.0</positiveFeedbackPercent>
               </seller>
               <price currencyId="$">1.0</price>
               <shippingService>
                  <type>ShippingMethodStandard</type>
                  <cost>2.99</cost>
                  <expeditedService>false</expeditedService>
               </shippingService>
               <itemLocation>New york, CT</itemLocation>
               <excludedShippingAreas/>
               <condition>BrandNew</condition>
               <description/>
               <storefront>
                  <storeURL>http://shops.half.ebay.com/wchan-half4_W0QQsellerZn_half4</storeURL>
                  <storeName>wchan_half4</storeName>
               </storefront>
            </item>
            <item>
               <itemID>90000886704</itemID>
               <itemURL>http://product.half.ebay.com/Harry-Potter-and-the-Prisoner-of-Azkaban-DVD-2004_W0QQprZ30549257QQtgZvidetailsQQitemZ90000886704</itemURL>
               <quantity>100</quantity>
               <seller>
                  <userID>wchan_half4</userID>
                  <feedbackScore>101</feedbackScore>
                  <positiveFeedbackPercent>100.0</positiveFeedbackPercent>
               </seller>
               <price currencyId="$">1.0</price>
               <shippingService>
                  <type>ShippingMethodStandard</type>
                  <cost>2.99</cost>
                  <expeditedService>false</expeditedService>
               </shippingService>
               <itemLocation>New york, CT</itemLocation>
               <excludedShippingAreas/>
               <condition>BrandNew</condition>
               <description/>
               <storefront>
                  <storeURL>http://shops.half.ebay.com/wchan-half4_W0QQsellerZwchan_half4</storeURL>
                  <storeName>wchan_half4</storeName>
               </storefront>
            </item>
            <listPrice currencyId="$">19.0</listPrice>
            <reviewCount>4</reviewCount>
         </product>
      </findHalfItemsResponse>
   </soapenv:Body>
</soapenv:Envelope>

Back to list of samples

findHalfItems Change History

Version	Description
1.2.0 06/23/2011	sortBy (added): This input element gives you the ability to specify how to sort the items returned in the response. product.item.rentalPrice (added): This output element is returned for items that can be rented (currently only items in the books category are eligible for rental). product.BestFixedPrice (added): This output element returns the lowest fixed price that the item is offered for on the site. product.BestRentalPrice (added): This output element returns the lowest price for which the item is offered for rent, at a 125 day duration, on the site. ItemFilterType.enum (added): Several new enums were added to ItemFilterType to provide more ways to control the items returned in the response. The new enum values are: ExcludeSeller, Seller, ShippingService, ListingType, and MaxPrice. product.item.price (modified): The price output element is no longer Always returned. If the item being returned is a rental item only, the item price is displayed only in the new rentalPrice output element. ItemFilter.value (modified): You can now provide more than a single value element in an ItemFilter when sending a request. This enables you to enter multiple userIds when you use Seller as the search filter.
1.0.0 02/18/2011	(added) New call.

Version

Description

1.2.0
06/23/2011

sortBy (added): This input element gives you the ability to specify how to sort the items returned in the response.
product.item.rentalPrice (added): This output element is returned for items that can be rented (currently only items in the books category are eligible for rental).
product.BestFixedPrice (added): This output element returns the lowest fixed price that the item is offered for on the site.
product.BestRentalPrice (added): This output element returns the lowest price for which the item is offered for rent, at a 125 day duration, on the site.
ItemFilterType.enum (added): Several new enums were added to ItemFilterType to provide more ways to control the items returned in the response. The new enum values are: ExcludeSeller, Seller, ShippingService, ListingType, and MaxPrice.
product.item.price (modified): The price output element is no longer Always returned. If the item being returned is a rental item only, the item price is displayed only in the new rentalPrice output element.
ItemFilter.value (modified): You can now provide more than a single value element in an ItemFilter when sending a request. This enables you to enter multiple userIds when you use Seller as the search filter.

1.0.0
02/18/2011

(added) New call.

User-Contributed Notes

itemFilter	ItemFilter	Optional, repeatable: [0..*]	Used to specify filter items. Currently the only item filters that are supported are item condition and seller. Supported Item Filter Names: Condition Seller ListingType
itemFilter.name	ItemFilterType	Optional	The item filter as selected from ItemFilterType enumeration list. Applicable values: • Condition (in) Return items based on the item condition: Valid values are: BrandNew, LikeNew, VeryGood, Good, Acceptable • ExcludeSeller (in) Exclude items listed by the sellerId(s) specified in the ItemFilter.value field. • FeedbackScoreMin (in) Return items only where the seller has a feedback score that is equal to or higher than the value specified in the ItemFilter.value field. • ListingType (in) Return items based on the listing type. Valid values are: FixedPrice and Rental • MaxPrice (in) Return items that are equal to or below the value specified in the ItemFilter.value field. The maximum price is in units of US dollars. • Seller (in) Return items from only the sellerId(s) specified in the ItemFilter.value field. • ShippingService (in) Return items on the shipping method. Valid values are: ShippingMethodStandard and ShippingMethodExpress
itemFilter.value	string	Optional, repeatable: [1..*]	Value on which to filter the returned items with regards to the associated item filter Name field. For example, if you specify Seller in the Name field, use this field to specify the Seller ID whose items you to include in the response. You can repeat this field to list multiple Seller IDs.
paginationInput	PaginationInputType	Optional	Controls the pagination of the result set. Child elements specify the maximum number of item listings to return per call by establishing the number of items per page and the number of pages. If paginationInput is not specified, the default is 1 page of items and 25 items per page. These settings control the number of listings returned in the response, but does not specify the details to return for each listing. Note: No more than 1500 items can be retrieved for a given search, regardless of how many matches are found. This limit is enforced by the maximum page number allowed (60) and the maximum entries per page allowed (25).
paginationInput.entriesPerPage	int	Optional	No of entries per page Min: 1. Max: 25. Default: 25.
paginationInput.pageNumber	int	Optional	Needed result page Min: 1. Max: 60. Default: 1.
productID	ProductIDType (string)	Required	Use this to retrieve specify which items are to be retrieved. Only those items associated with this product ID are returned. Specify the ID as a string, and optionally use the type attribute to indicate the nature of the ID you are specifying. Max length: 4000.
productID [ attribute type ]	ProductIDCodeType	Required	The nature of identifier being used. For findHalfItems only Reference, ISBN, UPC, and EAN are supported. For a list of possible enumeration values, see ProductIDCodeType.
sortBy	SortByType	Optional	Specifies the sort conditions for the returned items. The default is 125 days for Rental Items and the itemPrice for FixedPrice items.
sortBy.sortOn	SortOnType	Optional	The field on which the response entries are sorted. Applicable values: • FixedPrice (in) Sort on the Fixed Price of the item. • RentalPrice125Days (in) Sort on the 125 day rental price of the item. • RentalPrice30Days (in) Sort on the 30 day rental price of the item. • RentalPrice45Days (in) Sort on the 45 day rental price of the item. • RentalPrice60Days (in) Sort on the 60 day rental price of the item. • RentalPrice90Days (in) Sort on the 90 day rental price of the item.
sortBy.sortOrder	SortOrder	Optional	The order of the sort, either INCREASING or DECREASING. Applicable values: • DECREASING (in) Items are sorted on the specified field, from larger to smaller. • INCREASING (in) Items are sorted on the specified field, from smaller to larger.