getSingleItem

getSingleItem gets publicly visible details about one listing on Bonanza. This gives you most of the data that Bonanza shows to the general public on the View Item page (title, description, basic price information, and other details).

You just need to know the Bonanza item ID (a value like 123456789012) in order to retrieve the listing.

Note: What if you need to see item data that is normally only visible to the seller (where Bonanza would require them to login)? For this, you would need to use the authenticated version of this call (getUnlistedItem) instead.

getSingleItem Input

getSingleItemis a non-secure request with the following URL and HTTP header requirements:

Submit to URL: https://api.bonanza.com/api_requests/standard_request
Required in HTTP header: X-BONANZLE-API-DEV-NAME set to your dev_id

The name for your request should be getSingleItemRequest.

So, for example, here is the Ruby code to submit your request:

require "json"
require "net/http"

# Open connection to api.bonanza.com over port 443
http = Net::HTTP.new("api.bonanza.com", 443)
http.use_ssl = true
http.post(
  "/api_requests/standard_request", # The path we're posting to
  "getSingleItemRequest=your_serialized_JSON_data", # The data being posted
  { 'X-BONANZLE-API-DEV-NAME' => 'abcdef123456' } # The HTTP header, which gives your dev_id
)

Here are the available input parameters that can be serialized into JSON:

Argument Type Occurrence Meaning
Call-specific Input Fields
itemId string Required The item ID that uniquely identifies the item listing for which to retrieve the data.

You can determine an item's ID by calling FindItems or from the Bonanza Web site.
Max length: 19 (Note: The Bonanza database specifies 38. Currently, Item IDs are usually 9 to 12 digits).

getSingleItem Output

The name for the output returned from this request is getSingleItemResponse. So, after parsing the serialized response into JSON, you can access the data with something like:

my_json_hash['getSingleItemResponse']

Here are all the possible output parameters:

Argument Type Occurrence Meaning
Standard Output Fields
errorMessage Container Conditionally Description of an error or warning that occurred when Bonanza processed the request. Not returned if the ack value is Success.
errorMessage.error Container Conditionally,
repeatable: [0..*]
errorMessage.error.category ErrorCategory Conditionally Currently unused.
errorMessage.error.message string Conditionally A description of the error
errorMessage.error.type ErrorType Conditionally A unique descriptive name for the error.
timestamp dateTime Always This value represents the date and time when Bonanza processed the request. The time zone of this value is GMT and the format is the ISO 8601 date and time format (YYYY-MM-DDTHH:MM:SS.SSSZ). See the "dateTime" type for information about this time format and converting to and from the GMT time zone.
warnings Container Conditionally Description of a warning that occurred when Bonanza processed the request.
warnings.unrecognized_parameters Container Conditionally,
repeatable: [0..*]
An array of unrecognized parameters.
Call-specific Output Fields
item Container Always Container for more detailed item information.
item.bestOfferEnabled boolean Always Whether the seller will accept a best offer for this item. This feature enables a buyer to make a lower-priced binding offer on a fixed price item. Buyers can't see how many offers have been made (only the seller can see this information). To make a best offer on a listing, use the Bonanza Web site.
item.buyItNowPrice AmountType (double) Conditionally Pseudonym for currentPrice.
item.convertedBuyItNowPrice AmountType (double) Conditionally Pseudonym for currentPrice.
item.convertedCurrentPrice AmountType (double) Always Pseudonym for currentPrice.
item.country CountryCodeType Always Two-letter ISO 3166 country code to indicate the country where the item is located.
item.currentPrice AmountType (double) Always The listing's current price in USD.
item.description string Always The seller's description of the item, if any. This can include HTML markup.
Max length:60000.
item.ebayId int Optional The unique ebay ID for this item.
item.galleryURL anyURI Conditionally URL for a picture used as the Gallery thumbnail, if any. The image uses one of the following graphics formats: JPEG, BMP, TIF, or GIF. Only returned if the seller chose to show a gallery image.
item.itemID string Always The ID that uniquely identifies the item listing. Bonanza generates this ID when an item is listed. This ID is unique across all Bonanza sites.
item.itemSpecifics Container Conditionally 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. The field names are usually very well known within the category.

For example, a book's item specifics might include a field like Publication Year=2007 (where Publication Year is returned in Name, and 2007 is returned in Value), and a field like Format=Hardcover. But a car's item specifics would be different from a book's, with fields like Make= Toyota and Model=Prius. And a ticket's item specifics would be different from those of books and cars, with fields like EventType=Concerts and Venue=The Fillmore.

One of the most common uses for item specifics is the item condition.

Only returned if the seller included Item Specifics in the listing.
item.itemSpecifics
  .nameValueList
Container Conditionally,
repeatable: [0..*]
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.
 
item.itemSpecifics
  .nameValueList.name
string Conditionally 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.
item.itemSpecifics
  .nameValueList.value
string Conditionally,
repeatable: [0..*]
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).
item.listingStatus string Always

Specifies the listing's status in Bonanza's processing workflow. If an item's EndTime is in the past, but there are no details about the buyer or high bidder (and the user is not anonymous), you can use sellingState information to determine whether Bonanza has finished processing the listing.

sellingState values:

  • Active: The listing is still live. It is also possible that the auction has recently ended, but Bonanza has not completed the final processing (e.g., the high bidder is still being determined).
  • Canceled: The listing has been canceled by either the seller or Bonanza.
  • Missing required fields: The listing needs one or more fields populated before it can be put up for sale (required fields are currently title, category, and price)
  • Ready for sale: The has all the needed fields populated, and will be put up for sale next time the booth is updated/activated
  • Reserved: The seller has marked the item as "reserved"; it will remain in our system, not available for sale, until the seller reactivates it
  • Sold: The item has been sold
  • Unknown: Typically seen when an item has been purged from existence and is awaiting deletion
  • Another number: This indicates the native item status ID on Bonanza. If you see a number being reported as the item status and you aren't sure why, please report it to api@bonanza.com
item.location string Always Physical location of the item, as specified by the seller. (This gives a general indication of where the item will be shipped or delivered from.)
item.paymentMethods string Conditionally,
repeatable: [0..*]

Lists the payment type(s) accepted as payment for this item. Possible values include:

  • Paypal
  • Amazon
  • Credit Card
item.pictureURL anyURI Conditionally,
repeatable: [0..24]
Contains the URL for an image associated with the item, if any. Returned only if the seller included at least one picture in their listing. Note that this element does not return the URLs of pictures that the seller included in the Description via HTML IMG tags.
item.viewItemURL anyURI Always The canonical listing URL for the item.
item.postalCode string Always Postal code indicating the physical location of the item, as specified by the seller. (This gives a general indication of where the item will be shipped or delivered from.)
item.primaryCategory Container Always  
item.primaryCategory.categoryId Integer Always Numeric ID of the first (or only) category in which the item is listed. (Listings can appear in more than one category.)
item.primaryCategory.categoryName string Always Display name of the first (or only) category in which the item is listed. This is a fully qualified category breadcrumb (e.g., Computers & Networking:Laptops, Notebooks).
item.primaryCategory.categoryHierarchy Array Always An array of category IDs from the parent category downward.
item.quantity int Always The number of items the seller currently has available for sale.
item.returnPolicy Container Optional Holds details about the return policy for this item.
item.returnPolicy.
description
string Optional Details of the seller's return policy.
item.returnPolicy.
returnsAccepted
string Optional Whether the seller will accept returns on this item. Possible options:
  • ReturnsAccepted
  • ReturnsNotAccepted
item.returnPolicy.
returnsWithin
integer Optional The buyer can return the item within this period of time from the day they receive the item.
item.returnPolicy.
shippingCostPaidBy
string Optional Value should be "seller" if the seller will pay return shipping, or "buyer" if not.
item.seller Container Always Container for information about this listing's seller.
item.seller.feedbackRatingStar string Always

Visual indicator of user's feedback score. feedbackRatingStar values:

  • None: No graphic displayed, feedback score 0-9.
  • Yellow: Yellow Star, feedback score 10-49.
  • Blue: Blue Star, feedback score 50-99.
  • Turquoise: Turquoise Star, feedback score 100-499.
  • Purple: Purple Star, feedback score 500-999.
  • Red: Red Star, feedback score 1,000-4,999.
  • Green: Green Star, feedback score 5,000-9,999.
  • YellowShooting: Yellow Shooting Star, feedback score 10,000-24,999.
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.
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.
item.seller.userId string Always The user's unique Bonanza user ID.
item.shippingCostSummary Container Always Container for shipping information.
item.shippingCostSummary
  .carrier
String Conditionally The shipping carrier, if the shipping type is "calculated." Possible values include "usps", "ups", and "fedex".
item.shippingCostSummary
  .insuranceCost
AmountType (double) Conditionally The cost of insurance. For flat rate shipping, this is the value set by the seller, if any.
item.shippingCostSummary
  .insuranceType
String Conditionally The type of shipping insurance. Applicable values: None, Optional, Required, Included.
item.shippingCostSummary
  .packageSize
String Conditionally A text description of the size specified for the package, if the shipping type is "calculated."
item.shippingCostSummary
  .shippingServiceCost
AmountType (double) Conditionally The basic shipping cost of the item.
item.shippingCostSummary
  .shippingType
ShippingTypeCodeType Always

The shipping method that was used for determining the cost of shipping. For example: flat rate, calculated, or free. The seller specifies the available shipping services when they list the item.

shippingType values:

  • Calculated: The calculated shipping model: The posted cost of shipping is based on the buyer-selected shipping service, chosen by the buyer from the different shipping services offered by the seller. The shipping costs are calculated by Bonanza and the shipping carrier, based on the buyer's address. Any packaging and handling costs established by the seller are automatically rolled into the total.
  • Flat: The flat-rate shipping model: The seller establishes the cost of shipping and any shipping insurance, regardless of what any buyer-selected shipping service might charge the seller.
  • Free: Free is used when the seller has declared that shipping is free for the buyer.
  • NotSpecified: The seller did not specify the shipping type.
item.shippingCostSummary
  .shippingLbs
Integer Conditionally The number of pounds specified for the package. Returned only if shipping type is "calculated."
item.shippingCostSummary
  .shippingOz
Integer Conditionally The number of ounces for the package, in excess of its pounds (i.e., if the package is 5 lbs, 2 oz, this will return "2"). Returned only if shipping type is "calculated."
item.shippingCostSummary
  .shippingServices
Container Conditionally, 1..* Array of details about shipping services
item.shippingCostSummary
  .shippingServices
  .name
String Always Name of shipping service (e.g., "USPS Priority")
item.shippingCostSummary
  .shippingServices
  .carrier
String Always Name of shipping service carrier (e.g., "USPS")
item.shippingCostSummary
  .shippingServices
  .shippingServiceCost
AmountType (double) Conditionally Cost of this shipping service, if flat rate. Absent if not
item.shipToLocations Container Always,
repeatable: [1..*]
International locations to which the seller is willing to ship this item. Returned only for items that have ShipToLocations specified.
item.shipToLocations
  .region
string Conditionally

The region for this data. Applicable values:
  • Americas (North, South, or Latin America)
  • Asia
  • Europe
  • NorthAmerica
  • SouthAmerica
  • Worldwide
item.shipToLocations
  .shippingServiceCost
AmountType (double) Conditionally The basic shipping cost of the item to the region specified.
item.shipToLocations
  .shippingType
ShippingTypeCodeType Always

The shipping method that was used for determining the cost of shipping. For example: flat rate, calculated, or free. The seller specifies the available shipping services when they list the item.

shippingType values:

  • Calculated: The calculated shipping model: The posted cost of shipping is based on the buyer-selected shipping service, chosen by the buyer from the different shipping services offered by the seller. The shipping costs are calculated by Bonanza and the shipping carrier, based on the buyer's address. Any packaging and handling costs established by the seller are automatically rolled into the total.
  • Flat: The flat-rate shipping model: The seller establishes the cost of shipping and any shipping insurance, regardless of what any buyer-selected shipping service might charge the seller.
  • Free: Free is used when the seller has declared that shipping is free for the buyer.
  • NotSpecified: The seller did not specify the shipping type.
item.startTime dateTime Always Time stamp (in GMT) that Bonanza recorded as the moment that the listing was made available. The start time returned by a search call may vary from the value returned by GetSingleItem.
item.sku string Optional SKU of the item, for inventory tracking purposes.
item.title string Always Name of the item as it appears in the listing or in search and browse results.
item.variations Container Optional Details about potential variations for this item. Variations are multiple similar (but not identical) items in a single fixed-price listing. For example, a T-shirt listing could contain multiple items of the same brand that vary by color and size (like "Blue, Large" and "Black, Medium"). Each variation specifies a combination of one of these colors and sizes. Each variation can have a different quantity. You can buy multiple items from one variation at the same time. (That is, one order line item can contain multiple items from a single variation.)
item.variations.variation ItemVariation, optionally [0..*] Conditionally Details about one or more item variations
item.variations.
variation.
price
integer Conditionally The quantity of this particular item variation
item.variations.
variation.
quantity
integer Conditionally The quantity of this particular item variation
item.variations.
variation.
pictureURL
string Optional Contains the URL for an image associated with the variation, if any. 
item.variations.
variation.
sku
string Optional The SKU specific to this varation. An item may have one SKU that covers all variations, or different SKUs for each variation.
item.variations.
variation.
nameValueList
NameValueList container, optionally [0..*] Conditionally A container for the one or more name/value pairs of the item variations
item.variations.
variation.
nameValueList.
name
string Conditionally The name of the attribute being specified, i.e., "Size". Gathered from GetCategoryTraits.
item.variations.
variation.
nameValueList.
value
string Conditionally The value of the attribute referred to by "name." For example, if name was "Size" value may be "L". Potential values can be gleaned from from GetCategoryTraits.

getSingleItem Examples