BBAPI: GetProducts and SetProducts Commands

Products are easily accessible using the GetProducts and SetProducts commands. As a developer you can include or manipulate any data related to a product using the XML API. This document will explain how to use each.

On This Page:

Available Commands

GetProducts
Use this command if you wish to retrieve data for certain products. You can pass in zero or more search messages to the system. Passing in more than one <product> node can acheive complex searches similar to an OR statement.

Additional paramaters may be passed with the GetProducts command. These are as follows and should be placed inside the <params> node.

Paramater Possible Values Description
<getProductItemData> y / n (default is: n) Whether to include item data in response XML.

SetProducts
Use this command if you wish to save product data. Passing in a productID will perform an update on that product. If no productID is passed, a new record will be inserted with the given data. You can save multiple product records with one message. A copy of the saved data will be returned.

loading...

Example 1: Input

Here is a very basic sample message that would be sent to the API.

loading data...

Example 1: Response

The API will return the results of your request in a similar way. Here is a basic sample response.

loading data...

The above two samples are only very basic messages and in practice, these will most likely be much more complicated. Below are some more detailed examples.

Example 2: Response

Here is a sample that includes a product item within the product. For information on the relation between a product and an item, please see this article. This message would be sent to save a product with an item. The response message would similar to the response shown in example one.

loading data...

Example 3: Response

This example includes a complete XML message including an item, attributes and images. This message would be sent to the API to save a product with an item and related attributes and images. This message could also be a response when quering the system for this product.

loading data...

Attributes allow admins to customize the definition of their product. Admins can create attributes and then use these to further define their products. For example, there is no natural field for a retail site to specify the size or color of the products (in this case, we will say a t-shirt). An admin would create an attribute for size and another for color. When setting the product, these values can then be defined for each product. Multiple values can be assigned for each attribute, allowing the admin to set multiple sizes (sm, med, lg) and/or colors. Attributes must be pre-defined using the SetAttributes command, but the individual values pertaining to the product (ie. the relation) are defined with the SetProducts command. When using the GetProducts command, the attribute and the related values are returned for easy accessibility.

Images can be assigned to both products and items. It is up to the developer to choose if an item should be related to the product or item. In most cases, general images will be related to the product and more specific images, such as ones only relating to the item, are attached to the item definition.

Summary of Nodes

All fields are optional for GetProducts command. If a field is marked as required, this is only for the SetProducts command.

Node

 Required for Set / Type Description

productID

 No / Integer Unique ID of product to retrieve or update. If no ID is set and using SetProducts, a new product will be entered.

productName

 No / String Name of product to search or set.
productSKU No / String Unique string of product to be used by store owner. Can search on this field.
productPrice No / Double This value is calculated based off of the sum prices of all the items within the product. It cannot be set using SetProducts.
productType Yes / Integer

The type of product. Possible values are as follows:

  • 1 - product
  • 2 - membership
  • 3 - auction item (not currently supported)

productStatusID

 

 

 Yes / Integer

The status of the product. Possible values are as follows:

  • 1 - Active
  • 2 - Pending
  • 3 - On Hold
  • 4 In Active
productStatusName No / String This is the english value of the status ID. This field cannot be set using the SetProducts command.
productKeywords No / String A string of keywords to use when searching for products using GetProducts command. Has no effect with SetProducts.
productDateStart Yes / Integer The start date of the product. If using GetProducts, the system will search for products later than this date. If using SetProducts, will set the start date to the product. This value should be a Unix timestamp.
productDateEnd No / Integer The end of the product. This value should be a Unix timestamp.
productImage No / String Only used in GetProducts. Returns the default product image.
productCategoryID Yes / Integer ID reference to the category the product is in. Can use this a search parameter.
productCategoryName No / String

English reference of category.

productRemove No / String Set to 'y' to remove the product. Should only be used in SetProducts.
productItemID No / Integer ID of item.
productItemName No / String Name of item.
productItemDescription No / String May contain well formatted HTML. Description of item.
productItemCategoryID Yes / Integer ID reference of category.
productItemCategoryName No / String Name of category.
productItemCycleID Yes / Integer ID reference to billing cycle.
productItemCycleName No / String Name of billing cycle.
productItemPrice Yes / Double Price of item.
productItemIsShippable Yes / Char If shipping should be charged on the item. Set to 'y' for yes, 'n' for not applicable.
productItemIsTaxable Yes / Char If tax should be charged on the item. Set to 'y' for yes, 'n' for not applicable.
productItemHeight No / Double Height of item. Used in some shipping calculations.
productItemWidth No / Double Width of item. Used in some shipping calculations.
productItemLength No / Double Length of item. Used in some shipping calculations.
productItemType Yes / Char

Type of item. Possible values are:

  • r - Required.
  • o - Optional
productItemTypeName No / String Name of item type.
productItemWeight No / Double Weight of item.
imageID No / Integer ID of image.
imageSource No / String File name of image.
imageText No / String Optional text caption for image.
imageAlt No / String Optional text for image alt attribute
imageRank No / String Rank of image. If an image is submitted with the same rank as an existing image for the same item, the system will shift the other image down one.
fileID No / Integer Unique ID of file.
fileName Yes / String File name of file.
fileSize No / Integer This field cannot be set. It is calculated based on the actual file size of the file.
attributeID Yes / Integer Unique ID of attribute. The ID of an existing attribute.
attributeName No / String Display of this attribute.
attributeType No / String

Type of attribute. There are currently three different types:

  1. text - Wildcard value. Admin can customize the value from the product admin.
  2. select - Values are related to pre-existing values. Similar to a database relation. Admin selects a value from the product admin.
  3. user defined - Admin associates one or more values to the attribute and the user can define which one to use when ordering. This is often the case when selling clothing. The user would choose a size and color.
attributeValues Yes / Node All values associated with this attribute. Can contain one or more.
attributeValueRelID No / Integer Unique ID of this relation (attribute to item attribute value)
attributeValueChildID No / Integer ID of corresponding attribute value. Used with attribute type select or user defined.
attributeValueText No / String Text representation of value. This is what would be used to display the attribute.