addFixedPriceItem

addFixedPriceItem allows you to post an item to a booth on behalf of a Bonanza user. Prior to being able to add an item, the user must verify that you are authorized to act on their behalf, see our intro to user tokens for more details.

Take a look at some examples in C#, Java, PHP, Python, and Ruby.

If the booth you are adding to has more than 40k items, then your call will be processed asynchronously. The response will be:

{ 'resultMessage' => "Item queued for addition", 'success' => true }

addFixedPriceItem Input

addFixedPriceItem 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 addFixedPriceItemRequest.

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
item Container Required Container to hold all the details about item being posted.
item.customCategoryId integer Optional Also known as a Booth Category, the custom category ID corresponds to a user-defined category. Learn more
item.description string Optional Description of the item. Can include most kinds of HTML.
Max length: 60000 characters.
item.externalProductId string Optional An optional string identifier for this item so that it can be tracked with third party inventory systems.
item.obo boolean Optional False if the seller will not accept offers on this item. True by default.
item.itemSpecifics Container Optional Container for providing item traits.
item.itemSpecifics.specifics Array of label-value pairs Optional Array of label/value pairs, for example [ [ "condition", "new" ], [ "genre", "romance" ] ]. Specifying item traits will mean more traffic for the item, both on Bonanza and through search engines.
item.itemSpecifics.discardOld boolean Optional If true, all existing specifics for the item will be discarded before importing new specifics.
item.pictureDetails Container Optional Container for giving details about an item's pictures.
item.pictureDetails.discardOld boolean Optional If true, all existing pictures for the item will be discarded before importing new pictures.
item.pictureDetails.pictureURL anyURI Optional, repeatable: [0..3] Up to four URLs for pictures that are to be associated with this item. We will fetch these images from the web when you make the request, so be sure they are accessible to the Bonanza.com domain.
item.pictureDetails.pictureFilename image data Optional, repeatable: [0..3] Up to four pictures that are to be associated with this item. These should be included as multipart form data.
item.price double Optional The price that this item should be listed at, in US dollars.
item.primaryCategory Container Optional Container to specify item's category. See getCategories.
item.primaryCategory.categoryId integer Optional The ID of the category for this item.
item.quantity integer Optional Quantity of the item being sold. One is the default. Setting to 0 will return a sellingState of Missing required fields.
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.
returnsAcceptedOption		 string Optional Whether the seller will accept returns on this item. Possible options:
  • ReturnsAccepted
  • ReturnsNotAccepted
item.returnPolicy.
returnsWithinOption		 integer Optional The buyer can return the item within this period of time from the day they receive the item. Use the returnPolicy.description field to explain the policy details
item.returnPolicy.
shippingCostPaidByOption		 string Optional Value should be "seller" if the seller will pay return shipping, or "buyer" if not.
item.shippingDetails Container Optional Details about shipping for the item being sold.
item.shippingDetails
shipsWithinDays		 integer Optional The number of business days the item will ship within
item.shippingDetails.
calculatedShippingRate		 Container Required if shippingType is "Calculated" Container for calculated shipping details.
item.shippingDetails.
calculatedShippingRate.
packageSize		 string Optional Applicable values:
  • Large envelope
  • Normal package
  • Large package
  • Very large package
  • USPS Priority Mail Small Flat Rate Box
  • USPS Priority Mail Medium Flat Rate Box
  • USPS Priority Mail Large Flat Rate Box
  • USPS Priority Mail Flat Rate Envelope
  • USPS Priority Mail Padded Flat Rate Envelope
  • USPS Priority Mail Legal Flat Rate Envelope
item.shippingDetails.
calculatedShippingRate.
shippingWeightLbs		 integer Required if shippingType is "Calculated" Number of pounds for this package.
item.shippingDetails.
calculatedShippingRate.
.shippingWeightOz		 integer Required if shippingType is "Calculated" Number of ounces for this package, beyond the shipping pounds. That is, if the package is 16 lbs, 8 oz, then this field should be "8".
item.shippingDetails.
calculatedShippingRate.
shippingHeight		 integer Required if shippingType is "Calculated" and "packageSize" is unspecified Height of the package in inches. Note that side chosen as height, width and depth are arbitrary. One just needs to specify the length of each of the three dimensions.
item.shippingDetails.
calculatedShippingRate.
shippingWidth		 integer Required if shippingType is "Calculated" and "packageSize" is unspecified Width of the package in inches. Note that side chosen as height, width and depth are arbitrary. One just needs to specify the length of each of the three dimensions.
item.shippingDetails.
calculatedShippingRate.
shippingDepth		 integer Required if shippingType is "Calculated" and "packageSize" is unspecified Depth of the package in inches. Note that side chosen as height, width and depth are arbitrary. One just needs to specify the length of each of the three dimensions.
item.shippingDetails.
insuranceDetails		 Container Optional Details about shipping insurance.
item.shippingDetails.insuranceDetails.
insuranceOption		 string Optional Type of shipping insurance offered. Applicable values:
  • IncludedInShippingHandling. Shipping insurance is included free of charge with standard shipping.
  • Optional. Shipping insurance can optionally be added for a fee.
  • Required. Shipping insurance must be added for a fee.
item.shippingDetails.insuranceDetails.
insuranceFee		 double Optional Cost for domestic shipping insurance.
item.shippingDetails .internationalShippingServiceOption Container Optional, repeatable: [0..*] Array of containers for describing international shipping options.
item.shippingDetails .internationalShippingServiceOption. shippingType string Required Type of shipping offered for this destination. Applicable values:
  • Calculated
  • Fixed
  • Free
  • SeeDescription
item.shippingDetails .internationalShippingServiceOption. shipToLocation string Required Region for which we are specifying a shipping cost. Applicable values:
  • Africa
  • Asia
  • Australia
  • Canada
  • Europe
  • Germany
  • Japan
  • Mexico
  • N. and S. America
  • United Kingdom
  • Worldwide
item.shippingDetails .internationalShippingServiceOption. shippingServiceCost double Required if shippingType is "Fixed" Flat cost to ship to the region specified in shipToLocation.
item.shippingDetails. internationalShippingServiceOption .shippingCarrier string Required if shippingType is "Calculated" Name of shipping carrier to use. Applicable only if "Calculated Shipping" declared. Applicable values:
  • UPS
  • USPS
  • FedEx
item.shippingDetails .shippingServiceOptions Container Optional, repeatable (0..*) Container for domestic shipping details.
item.shippingDetails.shippingServiceOptions.
buyerPaysForLabel		 boolean optional Allow the buyer to pay the cost of the shipping label as part of their purchase.
item.shippingDetails .shippingServiceOptions.
shippingType		 string Required Type of shipping offered. Applicable values:
  • Calculated
  • Fixed
  • Free
  • SeeDescription
item.shippingDetails.
shippingServiceOptions.
freeShipping		 boolean Optional If true, domestic shipping is free. Note that either this variable must be set, or a shippingServiceCost must be set before the item can be made available for sale on Bonanza.
item.shippingDetails.
shippingServiceOptions. shippingServiceCost		 double Required if shippingType is "Fixed" Flat cost for domestic shipping.
item.shippingDetails.
shippingServiceOptions. shippingService		 shippingServiceType Optional See shippingServiceType for applicable values
item.shippingDetails.
shippingServiceOptions. shippingCarrier		 string Required if shippingType is "Calculated" Name of shipping carrier to use. Applicable only if "Calculated Shipping" declared. Applicable values:
  • UPS
  • USPS
  • FedEx
item.sku string Optional SKU of the item, for inventory tracking purposes.
item.title string Required to sell Title of the item, maximum of 80 characters. While you don't necessarily have to submit this with your request, your item will not be available to be put up for sale until a valid title is given.
item.variations ItemVariation, optionally [0..n] 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.
price		 double Optional The price that this variation should be listed at, in US dollars. If no variation price is specified, the variation price will be set to the "default" price of the item submitted in the item.price argument.
item.variations.
quantity		 integer Required if using variations The quantity of this particular item variation
item.variations.
sku		 string Optional The variation's SKU
item.variations.
upc		 string Optional The variation's UPC
item.variations.
imageIndex		 integer Optional If specified associates this variation with an image from the list of this item's images. The value of imageIndex is a zero-based index into the array of item's images.
item.variations.
nameValueList		 NameValueList container, optionally [0..2] Required if using variation A container for the name/value pairs of the item variations. Attempting to submit more than two will return a TooManyVariationNames error.
item.variations.
nameValueList.
name		 string Required if using variation The name of the attribute being specified, i.e., "Size". Gathered from GetCategoryTraits. The names must be the same across all variations.
item.variations.
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.

addFixedPriceItem Output

The name for the output returned from this request is addFixedPriceItemResponse. So, after parsing the serialized response into JSON, you can access the data with something like my_json_hash['addFixedPriceItemResponse']

Here are all the possible output parameters:

Return Value 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
itemId integer Always Unique ID for the item that was created.
categoryId integer Always ID of the category this item was listed with.
sellingState string Always The current selling state of the item. Applicable values:.
  • Active. This item is currently up for sale on Bonanza.
  • Ended. This item is not currently available for sale. It may be reserved or sold.
  • Missing required fields. This item has been created, but it doesn't have some of the fields necessary to be made available for sale.
  • Ready for sale. This item has all the necessary fields to get posted, once the user clicks the "Update Booth" button, it will be made available for sale.
  • Unknown. The status of this item can't be determined.
message string Conditionally Provides detailed description of missing fields that prevent the item from being made available for sale.

addFixedPriceItem Examples