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.allowForSale | boolean | Optional | If true, item selling state will be automatically set to Active. Default value is false. |
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:
|
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:
|
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:
|
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:
|
item.shippingDetails .internationalShippingServiceOption. shipToLocation | string | Required | Region for which we are specifying a shipping cost. Applicable values:
|
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:
|
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:
|
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:
|
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:.
|
message | string | Conditionally | Provides detailed description of missing fields that prevent the item from being made available for sale. |