getBoothItems
Retrieves an array of items of the specified status(es) for a Bonanza store.
getBoothItems Input
getBoothItems is a secure API method with the following URL and HTTP header requirements:
| Submit to URL: | https://api.bonanza.com/api_requests/secure_request |
| Required in HTTP header: | X-BONANZLE-API-DEV-NAME set to your dev_id |
| X-BONANZLE-API-CERT-NAME set to your cert_id |
Note that all secure methods except for fetchToken and getBoothItems require you to submit a user token so that we know what user account you are acting on behalf of. For details about setting up and submitting user tokens, see our intro to user tokens.
The name for your request should be getBoothItemsRequest.
Here are the available input parameters that can be serialized into JSON:
| Argument | Type | Occurrence | Meaning |
|---|---|---|---|
| requesterCredentials | Container | Required | Container for user credentials |
| requesterCredentials .bonanzleAuthToken | string | Required | The verified user token for the user who you are acting on behalf of. |
| Call-specific Input Fields | |||
| boothId | string or integer | Required | The URL Identifier or ID of a given booth. Aliased as userId and storeId. |
| itemStatus | array of strings | Optional | Fetch items from booth that match the specified itemStatus values. Important: If submitting a request with an item status other than 'for_sale', you must also submit the user token with your request. See the intro to user tokens. Valid statuses: for_sale, ready_to_post, missing_fields, reserved, and sold Default: for_sale |
| itemsPerPage | integer | Optional | The number of items to return. Max: 500 Default: 20 |
| page | integer | Optional | The page number to fetch. Default: 1 |
| order | string | Optional | The order to sort the items in. Currently only accepts "newest". Default: none |
getBoothItems Output
The name for the output returned from this request is getBoothItemsResponse. So, after parsing the serialized response into JSON, you can access the data with something like:
my_json_hash['getBoothItemsResponse']
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 | |||
| currentPage | integer | Always | The current page number. |
| size | integer | Always | The number of items returned. |
| totalEntries | integer | Always | The total number of items in the booth matching the query. |
| items | Container | Always, repeatable: [0..*] | Contains an array of the items returned. |
| items.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. |
| items.buyItNowPrice | AmountType (double) | Conditionally | Pseudonym for currentPrice. |
| items.convertedBuyItNowPrice | AmountType (double) | Conditionally | Pseudonym for currentPrice. |
| items.convertedCurrentPrice | AmountType (double) | Always | Pseudonym for currentPrice. |
| items.country | CountryCodeType | Always | Two-letter ISO 3166 country code to indicate the country where the item is located. |
| items.currentPrice | AmountType (double) | Always | The listing's current price in USD. |
| items.description | string | Always | The seller's description of the item, if any. This can include HTML markup. Max length:60000. |
| items.ebayId | integer | Optional | The unique ebay ID for this item. |
| items.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. |
| items.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. |
| items.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. |
| items.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. |
| items.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. |
| items.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). |
| items.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:
|
| items.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.) |
| items.paymentMethods | string | Conditionally, repeatable: [0..*] |
Lists the payment type(s) accepted as payment for this item. Possible values include:
|
| items.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. |
| items.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.) |
| items.primaryCategory | Container | Always | |
| items.primaryCategory.categoryId | string | Always | Numeric ID of the first (or only) category in which the item is listed. (Listings can appear in more than one category.) |
| items.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.productListingDetails | array | Optional | Provides the upc/mpn/isbn value in the form: ["upc/mpn/isbn", "value"] |
| items.quantity | int | Always | The number of items the seller currently has available for sale. |
| items.returnPolicy | Container | Optional | Holds details about the return policy for this item. |
| items.returnPolicy. description |
string | Optional | Details of the seller's return policy. |
| items.returnPolicy. returnsAccepted |
string | Optional | Whether the seller will accept returns on this item. Possible options: * ReturnsAccepted * ReturnsNotAccepted |
| items.returnPolicy. returnsWithin |
integer | Optional | The buyer can return the item within this period of time from the day they receive the item. |
| items.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:
|
| 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:
|
| 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:
|
| 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:
|
| items.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. |
| items.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.) |
| items.variations.variation | ItemVariation, optionally [0..*] | Optional | Details about one or more item variations |
| items.variations. variation. quantity |
integer | Required if using variations | The quantity of this particular item variation |
| items.variations. variation. nameValueList |
NameValueList container, optionally [0..*] | Required if using variation | A container for the one or more name/value pairs of the item variations |
| items.variations. variation. nameValueList. name |
string | Required if using variation | The name of the attribute being specified, i.e., "Size". Gathered from GetCategoryTraits. |
| items.variations. variation. nameValueList. value |
string | Required if using variation | 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. |
| items.variations. variation. upc |
string | Conditional | The variation-specific universal product code |
