Brandboom API Documentation v. 2.0.0
  • Brandboom Business Subscription is required for API access.
  • Brandboom does not provide implementation consultations or custom modifications. You must hire your own technical resources.
  • Your implementation must be able to make RESTful calls to the Brandboom API.
  • Contact Brandboom customer service to enable account integration and provide us with your static IPs. While the production environment is open to the public, our sandbox/testing environment is behind a firewall. The sandbox is a self-contained environment where you can set up and test your data as you wish.

    One easy way to check what IP address your server has is to run the following command in your server’s terminal:

    curl icanhazip.com or curl -s 'http://checkip.dyndns.org'

    Once Brandboom has enabled your account for integration, you'll see all the information you need for integration on your Account page. Your Public Key, Secret Key, Account ID, etc, should now be listed under the section "Integration".

    Log into the sandbox environment manage.brandboom.net to configure your sandbox and load it with data as needed. You can import data by using import templates.

    Below are sample templates. These files in Excel format can be used via both the API or the front end functionality located on the Product/Customer page. It is recommended however that you use the CSV files to call the API since they are much more compact and quicker to process.

    Sample Products Import Templates:

    Sample Customers Import Template:

    Use the API Explorer to experiment with the various API calls without coding:

    You can pick the function you want to try out from the "API/function" dropdown. Paste in your API keys and choose one of the functions and click "Go" to see the query in action. The RESTful query issued will be printed on screen. The result will be printed at the bottom of the page. Please note that the API Test Page cannot be opened in the same browser that you have the sandbox site open, as the two would log each others' sessions out.

    When you are testing with the sandbox environment, you might get an HTTPS certificate warning. Just make sure you disable certificate validation (for cUrl, it is the CURLOPT_SSL_VERIFYPEER flag). Once you’ve finished and tested in the sandbox, you can test with sample orders on production and resolve any remaining issues.

    Brandboom's API is based on a REST implementation. API entry points are divided by models/actions. For example, the orders API is located at https://manage.brandboom.com/api/v2/orders while the line sheets API is located at https://manage.brandboom.com/api/v2/linesheets.

    An API request URL looks like this:

    https://manage.brandboom.com/api/v2/{model}/{method}/{id}?{name}={value}&...

    Each API call requires the following parameters minimum:

    credentials
    We recommend that you embed your publicKey / timestamp / signature as the HTTP headers X-Auth-Key / X-Auth-Timestamp / X-Auth-Signature respectively. Alternatively, you can list them as query string parameters.
    responseType: (optional)
    The format of the response message. "json" is the default and the only supported format from V2 onwards. "xml" and "text" are deprecated but will be maintained for V1 functions.
    jsonp: (json only, optional)
    JavaScript to be prepended to the parenthesized payload object (refer to JSONP - JSON with Padding).

    Brandboom uses a pair of 128-bit MD5 public and secret keys; each key is a 32-digit long hexadecimal string.

    Instead of sending out the secret key, authentication is based on unique and ephemeral signatures generated using the secret key before submission upon every request. Notice that:

    Your account comes with:

    Public Key
    Tied to your account and it is used to identify you
    Secret Key
    Used to sign API requests (explained below). You should never share or expose your Secret Key to anyone

    Each API request must be signed to ensure its authenticity. A signature can be generated by taking the uppercase MD5 sum of the concatenation of your Public Key, your Secret Key, and the request timestamp (Unix-epoch timestamp) in the following fashion:

    signature = strtoupper(MD5("PUBLIC"+PublicKey+"SECRET"+SecretKey+"TIMESTAMP"+timestamp))

    When making your request, make sure you include your credentials as HTTP headers:

    X-Auth-Key:
    The API Public Key given to your account
    X-Auth-Timestamp:
    The Unix-epoch timestamp when the signature was generated
    X-Auth-Signature:
    The signature generated

    APIs requests are sent over the http protocol. Brandboom supports TLS encryption to protect data from being intercepted while in transit. You can enable TLS by simply accessing the Brandboom API address through https instead of http. Please note that Brandboom no longer supports SSL encryption as security loop holes have been identified.

    Assuming your Public Key is 5D41402ABC4B2A76B9719D911017C592, and the signature generated with your Secret Key and the current timestamp 1278031982 is 1F3870BE274F6C49B3E31A0C6728957F.

    Here is an example of what a request to retrieve orders will look like:

    Request Method
    GET
    Request URL
    https://manage.brandboom.com/api/v2/orders/search
    X-Auth-Key
    5D41402ABC4B2A76B9719D911017C592
    X-Auth-Timestamp
    1278031982
    X-Auth-Signature
    1F3870BE274F6C49B3E31A0C6728957F

    *It's recommend that you use a secured (https) connection if the content of the data is sensitive.

    The Brandboom API follows the RESTful design. GET requests imply "search". POST requests imply "create". PUT requests imply "update". DELETE requests imply "delete". When making a request, if you choose to omit the {method} in the URL, Brandboom will assume the method based on the request type. For example,

    GET
    https://manage.brandboom.com/api/v2/orders -> "search" method of orders
    PUT
    https://manage.brandboom.com/api/v2/orders -> "create" method of orders
    POST
    https://manage.brandboom.com/api/v2/orders/431 -> "update" method on Order 431
    DELETE
    https://manage.brandboom.com/api/v2/orders/431 -> "delete" method on Order 431

    Unless otherwise documented, the response message will be in json. While still supported for V1 functions, xml and text (plain text) have been deprecated since V2. The response format can be specified by using the responseType parameter when sending a request. The response message contains the following attributes:

    method
    the name of the method that was requested
    status
    "true" if succeeded, "false" or "error" if failed
    value
    the payload of the request if successful/applicable; the error messages if failed
    type
    the format of the response message
    JSON
    {
    	method": "search",
    	status": "error",
    	value": "Permission Denied",
    	jsonp": "MyApp.foo",
    	type": "json"
    }
    
    XML (deprecated since V2)
    <response>
    	<method> search</method>
    	<status>error</status>
    	<value>Permission Denied</value>
    	<type>xml</type>
    </response>
    
    TEXT (deprecated since V2)
    error|||Permission Denied
    
    PHP
    <?php
    function calculateSignature($publicKey, $secretKey, $timestamp){
    	return strtoupper(MD5("PUBLIC".$publicKey."SECRET".$secretKey."TIMESTAMP".$timestamp));
    }
    
    function fetch($approach, $url, $fields, $file=null){
    	$timestamp = time();
    	$publicKey = "5AEE3AF949C8383DD321D352433CDC0C";
    	$secretKey = "25320587CF6D4F206F68B517F0878408";
    	$signature = calculateSignature($publicKey, $secretKey, $timestamp);
    
    	//Approach 1 - Use pecl_http functions
    	//NOTE: this is the preferred method
    	if($approach==1){
    		$options = array(
    			'headers'=>array(
    				"X-Auth-Key" => $publicKey,
    				"X-Auth-Timestamp" => $timestamp,
    				"X-Auth-Signature" => $signature
    			),
    			'ssl'=>array(
    				/* needed for sandbox manage.brandboom.net environment*/
    				'verifypeer'=>false
    			)
    		);
    		$rawResult = http_post_fields($url, $fields, $file? array($file) : null, $options);
    		$parsedResult = http_parse_message($rawResult);
    		return $parsedResult->body;
    	}
    	//Approach 2 - Use curl functions
    	else if($approach==2){
    		//write to a file called orders.xml in the tmp dir
    		$tmpFile = "/tmp/orders.xml";
    		$fp = fopen($tmpFile, "w");
    
    		//if there are files to be attached
    		if($file){
    				//if PHP version >= 5.5
    				if(function_exists("curl_file_create")){
    					$cFile = curl_file_create($file["file"], $file["type"], $file["name"]);
    					$fields['data'] = $cFile;
    				}
    				//PHP < 5.6
    				else{
    					$fields['data'] = '@'.$file["file"];
    				}
    			}
    
    		//set the url, number of POST vars, POST data
    		$ch = curl_init();
    		curl_setopt($ch,CURLOPT_URL, $url);
    		curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    		curl_setopt($ch,CURLOPT_HEADER, true);
    		curl_setopt($ch,CURLOPT_SSL_VERIFYPEER, false);
    		/* needed for sandbox manage.brandboom.net environment*/
    		curl_setopt($ch,CURLOPT_SSL_VERIFYHOST, 2);
    
    		$headers = array(
    			"X-Auth-Key: ".$publicKey,
    			"X-Auth-Timestamp: ".$timestamp,
    			"X-Auth-Signature: ".$signature
    		);
    		curl_setopt($ch,CURLOPT_HTTPHEADER, $headers);
    
    		curl_setopt($ch,CURLOPT_POST, count($fields));
    		curl_setopt($ch,CURLOPT_POSTFIELDS, $fields);
    		curl_setopt($ch,CURLOPT_FILE, $fp);
    		curl_setopt($ch,CURLOPT_HEADER, 0);
    
    		//execute post
    		$status = curl_exec($ch);
    		if(curl_errno($ch))
    			print curl_error($ch);
    		else
    			curl_close($ch);
    
    		//close connection
    		fclose($fp);
    
    		return file_get_contents($tmpFile);
    	}
    }
    
    //#################################################
    /*        Retrieving orders from brandboom       */
    //#################################################
    $url = "https://manage.brandboom.net/api/v2/orders/search";
    $fields = array(
    	"status" => "export",
    	"numResults" => 0
    );
    $result = fetch(1, $url, $fields);
    echo $result;
    
    //#################################################
    /*         Posting products to brandboom         */
    //#################################################
    $url = "https://manage.brandboom.com/api/v2/products/import";
    $fields = array(
    	"brandID" => "34",
    	"showroomID" => "161",
    	"mode" => "COMBINE"
    );
    $importFile = array(
    	'name' => 'data',
    	'type' => 'text/csv',
    	'file' => "/tmp/product_import_template.csv",
    );
    $result = fetch(2, $url, $fields, $importFile);
    echo $result;
    

    Use this method to search/list out all your showrooms.

    URL
    GET https://manage.brandboom.com/api/v2/showrooms/{showroomID} , or
    https://manage.brandboom.com/api/v2/showrooms/search
    Parameters
    showroomID (optional) Comma-separated listed of showroomIDs to filter with. You can find this ID inside of the Showroom Settings popup.

    Return
    Response Payload The response is an object with an attribute named "showrooms" containing an array of showrooms that you're authorized to access.

    Product Object

    The structure of a Showroom object is as follow:
    {
    	"id":21364,								//showroomID
    	"name":"Sample Showroom",				//showroom name
    	"urlAlias":"abc83",						//showroom URI
    	"brandID":19457, 							//brandID
    	"isMaster":true,							//main showroom or sub-showroom
    	"locale":"en_US",
    	"languageCode":"en",
    	"dateFormat":"MM\/dd\/yyyy",
    	"numberFormat":"#,##0.00|.|,|",
    	"priceTiers":[21757], 						//price tier IDs used by showroom
    	"terms":["Credit Card","COD","Check"], 		//available payment terms
    	"shippingOptions":[], 						//availabel shipping methods
    	"numActiveProducts":0,
    	"orderMinimum":0, 						//required minimum order amount
    	"customFields":[], 						//user custom fields
    	"currentClass":"Showroom"
    }

    Use this method to retrieve products. There's a maximum of 300 results per request.

    URL
    GET https://manage.brandboom.com/api/v2/products/{productID} , or
    https://manage.brandboom.com/api/v2/products/search
    Parameters
    brandID Brand ID. Please refer to your account page.
    showroomID Showroom ID. You can locate the showroomID in the Showroom Settings popup.
    priceTierID The numeric Price Tier ID. Unless you've specified a groupName (in which case the priceTierID will be pulled from the group), you must specify the price tier you want to use for the products. Please refer to the Price Tiers to see how to retreive a full list.
    language The two-letter code of the language that products descriptions should be retrieved in. The langguage you pick must correspond to language of a valid existing showroom. Default is en for English.
    productID (optional) Comma-separated list of Brandboom Product IDs.
    keywords (optional) Caret-separated (^) list of keywords to search by.
    groupName (optional) Show products that are inside of the presentation by this name.
    styleNumbers (optional) Caret-separated (^) list of style numbers that these products should have. Ex: "MKG-231^MKG233"
    types (optional) Comma-separated list of types that these products have been tagged with. Ex: "Mens, Womens"
    seasons (optional) Comma-separated list of seasons that these products have been tagged with. Ex: "Fall 15, Summer 16"
    categories (optional) Comma-separated list of categories that these products have been tagged with. Ex: "Shorts, Tees"
    sizes (optional) Comma-separated list of sizes that these products contain. Ex: "S, "M"
    numResults (optional) The number of results that you want your request to limit to. The maximum and default are 300 results per request (100 if format is xml).
    resultOffset (optional) The result offset that you want your request to start from. The default is 0 (the beginning).

    Return
    Response Payload The response is an object with a totolNumResults attribute, and array of Product objects loaded with descriptions in the specified language and prices in the specified price tier.

    Product Object

    The structure of a Product object is as follow:
    {
    	"id": 1497120,
    	"accountID": 912,
    	"brandID": 1244,
    	"statusLock": 0,
    	"styleNumber": "GrayTank",				//style number
    	"options": ["GRY"],						//array of option codes
    	"sizes": ["S"],								//array of sizes
    	"optionAvailableCounts": {					//availability of each option
    		"GRY": {
    			"count": "",						//aggregate inventory count of this option across all sizes
    			"hasInfinite": true 					//true if unlimited
    		}
    	},
    	"prepacks": [],
    	"category": [
    		"Tops",
    		"Jacket"
    	],
    	"types": [
    		"Womens",
    		"Mens"
    	],
    	"imageIDs": [
    		"00000297051B19A6",
    		"0000029705004438",
    		"00000297049D9424"
    	],
    	"referenceName": "Gray Tank 23",			//product name
    	"referenceDate": "2014-03-26",				//ship date
    	"dateCreated": "2015-03-02 12:47:04",
    	"dateModified": "2015-03-02 12:47:04",
    	"status": 0,								//0: active, 1:suspended, 2:deleted
    	"minQTY": 3,								//minimum quantity required when ordering
    	"imageReference": "",
    	"description": {							//ProductDescription for the specified language
    		"id": 1497120,
    		"language": "en",						//2-letter language code
    		"name": "Gray Tank 23",				//product name in this specific language
    		"description": "Loose Gray Tank Top",	//description in this specific language
    		"season": ["Fall"],						//seasons
    		"sizeRange": "S",						//string description of the size range. ex: "S-XL"
    		"options": ["GRY"],
    		"optionsTranslation": {"GRY": "Gray"}, 	//option-code to option-name translations in thie specific language 
    		"type": "I"							//I: index; T: translation
    	},
    	"price": {								//ProductPrice for the specified price tier
    		"id": 1497120,
    		"priceTierID": 1548,
    		"currency": "USD",
    		"MSRP": 30,
    		"price": 15,
    		"discount": 0,
    		"priceRange": [						//array of one or two elements, specifying the min/max 
    			10								//prices across all the skus of this product
    		],
    		"currentClass": "ProductPrice"
    	},
    	"skus": [									//all the skus of this product
    		{
    			"id": 7696290,
    			"styleNumber": "GrayTank",
    			"option": "GRY",
    			"size": "S",
    			"skuNumber": "",
    			"UPC": "",
    			"description": "",
    
    			"processingCount": 0,				//quantities tied in at-once orders with the status of "processing"
    			"completeCount": 0,				//quantities tied in at-once orders with the status of "complete"
    			"pickAndPackCount": 0,			//quantities tied in at-once orders with the status of "export"
    			"shippedCount": 0,				//quantities tied in at-once orders with the status of "shipped"
    			"pendingCount": 0,				//quantities tied in all at-once orders whose referenced inventory numbers haven't been updated since
    			"exportedCount": 0,				//quantities tied in at-once orders with the status of "exported"
    			"inventoryCount": null,				//AvailableToSell = inventoryCount - "comleted" - "exported"
    											//NOTE: null == unlimited; 0 == sold-out
    			"futureProcessingCount": 0,			//quantities tied in future orders with the status of "processing"
    			"futureCompleteCount": 0,
    			"futurePickAndPackCount": 0,
    			"futureShippedCount": 0,
    			"futurePendingCount": 0,
    			"futureExportedCount": 0,
    			"futureInventoryCount": null,
    			"futureInventoryDate": null,
    
    			"accountID": -1,
    			"brandID": 1244,
    			"objectID": null,
    			"warehouseID": -1,
    			"dateCreated": "2015-03-02 12:47:04",
    			"dateModified": "2015-03-02 12:47:04",
    			"dateInventoryModified": "2015-03-02 12:47:04", 	//date the inventoryCount attribute was changed
    			"importing": 0,
    			"isDeleted": false,
    			"isActive": true
    		}
    	],
    	"reference": "",
    	"statusSR": 0,
    	"currentClass": "Product",
    	"showroomStatuses": []
    }
    

    This method is called when you want to import a list of skus and/or their inventory either directly inline or via an Excel file or CSV file attachment. If you choose to use an attachment file, you must conform to the layout of the sample templates listed below.


    If you only need to import new inventory counts, make sure you set the import mode to inventory. This will let the API know that you're only updating numbers but not product information. It will allow the API to process much faster.

    On the other hand, if you set the mode to split or combine, the API will scan through every single column/attribute of each row/object and overwrite any of the current product information. If you do not wish to overwrite specific columns/attributes, simply don't include them in your requests.

    You will need to provide at least the Style Number, Option Code, Size or the SKU Number minimum.

    • Your HTTP Post must include enctype="multipart/form-data" for file uploading to work (RFC-186). Otherwise, the file will not be picked up.
    • It’s strongly recommended that you test out importing with a couple lines of data first.
    Parameters
    mode split - import products info and inventory counts; styles with multiple options will be split into multiple products with 1 option per product
    combine - import products info and inventory counts; styles with multiple options will be kept as a single product with multiple options
    inventory - only import the inventory counts; use this when you just want to update the inventory counts
    bypassDiff By default, in order to conserve processing power, only rows that weren’t included in the last immediate API import would be processed. Behind the scene, the server runs a diff command between the current data and the last-uploaded data. Setting this to “true” will force the server to process the data uploaded regardless.
    data An array of objects, each with information pertaining to each SKU. Assuming your showroom has a price tier of the currency "USD" and it's named "WHL", an object in your array might look like the following:

    [
    	{
    		"styleNumber": "MKD1233", 	//mandatory; style ID
    		"optionCode":"GRY", 			//mandatory; standardized manufacutring option/color code