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.
Example 1: Input
Here is a very basic sample message that would be sent to the API.
Example 1: Response
The API will return the results of your request in a similar way. Here is a basic sample response.
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.
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.
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:
|
productStatusID
|
Yes / Integer | The status of the product. Possible values are as follows:
|
| 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:
|
| 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:
|
| 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. |
