---
title: API Reference
language_tabs:
- http
toc_footers:
- bitRec
search: true
---
Thank you very much for choosing bitREC as your recommender system provider.
This is bitREC's API documentation. Please read this document carefully in order to make the integration process smooth and swift.
In case you would need support or more information, do not hesitate to contact our helpful technicians: support@bitrec.com .
# Data Upload
This section explains how to properly manage historical data exchange between your systems and bitREC.
Data upload functions are used for regular data (carts, catalog, customers) uploads/updates to bitREC recommender system.
## Cart Items
```http
POST /client-services/data_upload/carts HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
[{"customerId" : "14", "buId" : "online1","orderTimestamp": "2013-07-10T12:20:00.000", "bonusCode": "ASD4221", "discount": 5.0,
"items": [{"itemId":"Samsung SIII", "price":500.99, "quantity": 2, "discount": 5.0},
{"itemId":"Samsung cover flip", "price":45.50, "quantity": 1},
{"itemId":"auto charger", "price":14.00, "quantity": 1}]}, ...]
```
```shell
# Curl command from shell:
curl -v -H "Content-Type: application/json" -X POST -d '[{"customerId" : "14", "buId" : "online1","orderTimestamp": "2013-07-10T12:20:00.000", "bonusCode": "ASD4221", "discount": 5.0,
"items": [{"itemId":"Samsung SIII", "price":500.99, "quantity": 2, "discount": 5.0},
{"itemId":"Samsung cover flip", "price":45.50, "quantity": 1},
{"itemId":"auto charger", "price":14.00, "quantity": 1}]}]' http://user:pass@recs.bitrec.com/client-services/data_upload/carts
```
> UploadCart JSON format:
```json
{"customerId" : "",
"buId" : "",
"orderTimestamp": "", "bonusCode": , "discount": ,
"items": [{"itemId":"- ", "price":4.45, "quantity": 2, "discount":
}, ...]
}
```
This function is used to regularly upload cart information. Usually it is enough to upload carts once in 24 hours.
* If customerId, buId or any of itemId are found in our system, they will be automatically created without further details.
These details can be later updated using appropriate APIs.
* If orderTimestamp is missing, current time will be used.
### HTTP Request
`POST https://:@//data_upload/carts`
### Body Parameters
Parameter | Required | Description
--------- | ---- | ------- | -----------
UploadCart obj. list | Yes | List of Cart item objects in JSON format
#### UploadCart object
Field | Required | Type | Description
----- | -------- | ---- | ------
customerId | Yes | String | ID of customer
orderTimestamp | Yes | String (Format for date is "yyyy-MM-ddTHH:mm:ss.ms") | Time of cart purchase
buId | No | String | Business unit, where cart was sold
bonusCode | No | String | bonus code for a cart
discount | No | Float | discount on all items in this cart, in money value (not percentage value). Not required, it's possible to assign discount to whole cart, or set discount for separate cart items.
items | Yes | List of UploadCartItem objects | List of cart items
#### UploadCartItem object
Field | Required | Type | Description
----- | -------- | ---- | ------
itemId | Yes | String | ID of item
price | Yes | Float | Price of item
quantity | No | Integer | items' quantity in the cart
discount | No | Float | discount for this item, in money value (not percentage value).
### Response
Code | Description
--- | --------
204 | Request was successfully completed
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
## Items
```http
POST /client-services/data_upload/items HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
[{"itemId" : "456821", "price": 12.4, "category1Id": "1544|489|1444", "category2Id": "789|4555|4788",
"name": "Nikon D3200", "description" : "Nikon D3200 Digital SLR Camera With AF-S DX NIKKOR 18-55mm",
"deliveryTime": 1, "discount": 0.0, "buIds": ["shop L1", "shop L2"], "active": true},...]
```
```shell
# Curl command from shell:
curl -v -H "Content-Type: application/json" -X POST -d '[{"itemId" : "456821", "price": 12.4, "category1Id": "1544|489|1444", "category2Id": "789|4555|4788",
"name": "Nikon D3200", "description" : "Nikon D3200 Digital SLR Camera With AF-S DX NIKKOR 18-55mm",
"deliveryTime": 1, "discount": 0.0, "buIds": ["shop L1", "shop L2"], "active": true}]' http://user:pass@recs.bitrec.com/client-services/data_upload/items
```
> UploadCart JSON format:
```json
{"itemId" : "- ",
"name" : "
- ",
"description" : "
- ",
"price" : "
",
"category1Id" : "",
"category2Id" : "",
"category3Id" : "",
"category4Id" : "",
"category5Id" : "",
"category6Id" : "",
"deliveryTime": "",
"discount": "",
"buIds": [""],
"active": ""
}
```
This function is used to regularly upload or update catalog information. Usually it is enough to upload/update catalog once in 24 hours.
* Required: itemId or 400 will be returned.
* Repeatedly posting data with the same itemId will update the entry in bitrec system
* If you uploaded carts data with unknown items in bitrec system, you can update item information using this REST function call.
### HTTP Request
`POST https://:@//data_upload/items`
### Body Parameters
Parameter | Required | Description
--------- | ---- | ------- | -----------
Item obj. list | Yes | List of Item objects in JSON format
#### Item object
Field | Required | Type | Description
----- | -------- | ---- | ------
itemId | Yes | String | ID of item
price | Yes | Float | Price of item
category1Id | Yes | String | Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category2Id | No | String | Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category3Id | No | String | Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category4Id | No | String | Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category5Id | No | String | Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category6Id | No | String | Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
name | Yes | String | Name of item
description | No | String | Description of item
deliveryTime | No | Integer | Items' delivery time in days
discount | No | Float | Discount on this item (value in percentage)
buIds | No | List of Strings | List of business units where this item belongs
active | No | Boolean | Defines if item is active right now (can be sold, or at least should be included in recommendations)
### Response
Code | Description
--- | --------
204 | Request was successfully completed
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
## Customers
```http
POST /client-services/data_upload/customers HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
[{"customerId" : "154", "gender": "male", "birth": "1982-02-20", "location":"Vilnius"}, ...]
```
```shell
# Curl command from shell:
curl -v -H "Content-Type: application/json" -X POST -d '[{"customerId" : "154", "gender": "male", "birth": "1982-02-20", "location":"Vilnius"},
{"customerId" : "155", "gender": "female", "birth": "1985-04-12", "location":"Klaipeda"}]' http://user:pass@recs.bitrec.com/client-services/data_upload/customers
```
> UploadCart JSON format:
```json
{"customerId" : "",
"gender": "",
"birth": "",
"location":""
}
```
This function is used to regularly upload or update customer information. Usually it is enough to upload/update customers once in 24 hours.
* Required: customerId or 400 will be returned.
* customerId can not have “.” (dot) in the string and better to be alphanumerical
* Repeatedly posting data with the same itemId will update the entry in bitrec system
* If you uploaded carts data with unknown customers in bitrec system, you can update customer information using this REST function call.
### HTTP Request
`https://:@//data_upload/customers`
### Body Parameters
Parameter | Required | Description
--------- | ---- | ------- | -----------
Customer obj. list | Yes | List of Customer objects in JSON format
#### Customer object
Field | Required | Type | Description
----- | -------- | ---- | ------
customerId | Yes | String | ID of customer
gender | No | String | Customers gender
birth | No | String | Birth of customer (Format for date is "yyyy-MM-dd")
location | No | String | Customers' location
### Response
Code | Description
--- | --------
204 | Request was successfully completed
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
## Business Unit
```http
POST /client-services/data_upload/business_units HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
[{"buId":"online", "itemId":"1455522", "active":true},
{"buId":"offline", "itemId":"1455522", "active":true}, ...]
```
```shell
# Curl command from shell:
curl -v -H "Content-Type: application/json" -X POST -d '[{"buId":"online", "itemId":"1455522", "active":true},
{"buId":"offline", "itemId":"1455522", "active":true}]' http://user:pass@recs.bitrec.com/client-services/data_upload/business_units
```
> Business unit JSON format:
```json
{"buId":"",
"itemId":"",
"active":true
}
```
This function is used to regularly upload or update Business Unit information.
Concept of Business Units should be used in several cases:
* Required: externalBusinessUnitId or 400 will be returned.
* customerId can not have “.” (dot) in the string and better to be alphanumerical
* Repeatedly posting data with the same itemId will update the entry in bitrec system
* If you uploaded carts data with unknown customers in bitrec system, you can update customer information using this REST function call.
### HTTP Request
`https://:@//data_upload/business_units`
### Body Parameters
Parameter | Required | Description
--------- | ---- | ------- | -----------
BU obj. list | Yes | List of Business unit objects in JSON format
#### BU object
Field | Required | Type | Description
----- | -------- | ---- | ------
itemId | Yes | String | ID of item
buId | Yes | String | ID of business unit
active | Yes | Boolean | Defines if item in business unit is active (1 - True, 0 - False)
### Response
Code | Description
--- | --------
204 | Request was successfully completed
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
# Business Units
This section explains how to properly manage item availability on different physical or logical business units.
Concept of business units allows retailer to divide catalog items among different physical or logical locations and manage item availability among them. It is also used in order to mark items that are out of stock in cases of single location.
## Activate business unit
```http
POST /client-services/business_units/online/15455/activate HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
```
```php
```
Function is used to activate an item in the given Business Unit.
### HTTP Request
`https://:@//business_units/{buId}/{itemId}/activate`
### Request Parameters
Parameter | Required | Description
--------- | ---- | -------
buId | Yes | Name of business unit
itemId | Yes | item id value
### Response
Code | Description
--- | --------
204 | Request was successfully completed
400 | Bad request – mostly due wrong sending parameters structure
404 | Resource by specified parameters was not found
500 | Internal server error
## Deactivate business unit
```http
POST /client-services/business_units/online/15455/deactivate HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
```
```php
```
Function is used to deactivate an item in the given Business Unit.
### HTTP Request
`https://:@//business_units/{buId}/{itemId}/deactivate`
### Request Parameters
Parameter | Required | Description
--------- | ---- | -------
buId | Yes | Name of business unit
itemId | Yes | item id value
### Response
Code | Description
--- | --------
204 | Request was successfully completed
400 | Bad request – mostly due wrong sending parameters structure
404 | Resource by specified parameters was not found
500 | Internal server error
## Business unit items
```http
POST /client-services/business_units/online/items HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
```
```php
```
> Response:
```json
["14566", "484551", "541222", ...]
```
Function is used to get a list of items in the given business unit.
* Required: buId or 400 will be returned.
### HTTP Request
`https://:@//business_units/{buId}/items`
### Request Parameters
Parameter | Required | Description
--------- | ---- | ------- | -----------
buId | Yes | Business unit name
### Response
Code | Description
--- | --------
200 | Request was successfully completed. Returns content of string list in JSON format. Each of those string represents item Id in that business unit.
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
# Recommendations
This section explains how to receive product recommendations in different pages of your webstore.
## Top (home page )
```http
POST /client-services/recs/items HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14
```
```shell
# Curl command from shell:
curl -v -d "customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14" http://user:pass@recs.bitrec.com/client-services/recs/items
```
This function is used to request recommendations for the home page.
* While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
### HTTP Request
`POST https://:@//recs/items`
### Body Parameters
Parameter | Required | Type | Description
--------- | -------- | ---- | -----------
k | Yes | Integer | number of recommendations to retrieve
customer_id | No | String | Customer id.
visitor_id | No | String | Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie).
bu_id | No | String | Business unit id. If this value is not send, then default business unit id will be taken.
cart_items | No | String | List of cart item IDs separated by ';' (for example 12;45;94;14)
user_agent | No | String | a string representing the customer's browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0)
user_ip | No | String | a string with the customer's IP address (for example 74.125.230.36)
ref | No | String | Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date | No | String | Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).
### Response
Code | Description
--- | --------
200 | Request was successfully completed. Returns content of item id list in JSON format. Example: ["45812", "45212"]
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
## Personal Basket
```http
POST /client-services/recs/personal_basket HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14
```
```shell
# Curl command from shell:
curl -v -d "customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14" http://user:pass@recs.bitrec.com/client-services/recs/personal_basket
```
This function is used to request recommendations for customer personalized item list. Those recommendations are based
on customer orders, viewing history and predicts what customer wants to by at this session.
* While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
### HTTP Request
`POST https://:@//recs/personal_basket`
### Body Parameters
Parameter | Required | Type | Description
--------- | -------- | ---- | -----------
k | Yes | Integer | number of recommendations to retrieve
customer_id | No | String | Customer id.
visitor_id | No | String | Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie).
bu_id | No | String | Business unit id. If this value is not send, then default business unit id will be taken.
cart_items | No | String | List of cart item IDs separated by ';' (for example 12;45;94;14)
user_agent | No | String | a string representing the customer's browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0)
user_ip | No | String | a string with the customer's IP address (for example 74.125.230.36)
ref | No | String | Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date | No | String | Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).
### Response
Code | Description
--- | --------
200 | Request was successfully completed. Returns content of item id list in JSON format. Example: ["45812", "45212"]
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
## Up–Sell
```http
POST /client-services/recs/items/viewed/458544 HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14
```
```php
```
**Up–Sell.**
This function is used to request up-sell recommendations for the item page. Up-Sell items are usually items similar to the current item. A typical label for such recommendations is 'People who viewed this item also viewed'.
* While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
*
### HTTP Request
`POST https://:@//recs/items/viewed/{item_id}`
### Request Parameters
Parameter | Required | Description
--------- | ---- | ------- | -----------
item_id | Yes | Id of item, which page customer is viewing.
### Body Parameters
Parameter | Required | Type | Description
--------- | -------- | ---- | -----------
k | Yes | Integer | number of recommendations to retrieve
customer_id | No | String | Customer id.
visitor_id | No | String | Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie).
bu_id | No | String | Business unit id. If this value is not send, then default business unit id will be taken.
cart_items | No | String | List of cart item IDs separated by ';' (for example 12;45;94;14)
user_agent | No | String | a string representing the customer's browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0)
user_ip | No | String | a string with the customer's IP address (for example 74.125.230.36)
ref | No | String | Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date | No | String | Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).
### Response
Code | Description
--- | --------
200 | Request was successfully completed. Returns content of item id list in JSON format. Example: ["45812", "45212", "654323", "7865146"]
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
## Cross-Sell
```http
POST /client-services/recs/items/bought/458544 HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14
```
```php
```
**Cross-Sell**
This function is used to request cross-sell recommendations for the item page. Cross-Sell items are usually complimentary items to the current item. A typical label for such recommendations is 'People who bought this item also bought'.
* While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
*
### HTTP Request
`POST https://:@//recs/items/bought/{item_id}`
### Request Parameters
Parameter | Required | Description
--------- | -------- | -----------
item_id | Yes | Id of item, which page customer is viewing.
### Body Parameters
Parameter | Required | Type | Description
--------- | -------- | ---- | -----------
k | Yes | Integer | number of recommendations to retrieve
customer_id | No | String | Customer id.
visitor_id | No | String | Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie).
bu_id | No | String | Business unit id. If this value is not send, then default business unit id will be taken.
cart_items | No | String | List of cart item IDs separated by ';' (for example 12;45;94;14)
user_agent | No | String | a string representing the customer's browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0)
user_ip | No | String | a string with the customer's IP address (for example 74.125.230.36)
ref | No | String | Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date | No | String | Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).
### Response
Code | Description
--- | --------
200 | Request was successfully completed. Returns content of item id list in JSON format. Example: ["45812", "45212", "654323", "7865146"]
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
## Category
```http
POST /client-services/recs/items/category/3/Cat-46587 HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14
```
This function is used to request recommendations in category page. A typical label for such recommendations is 'You might be interested in'.
* While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
*
### HTTP Request
`POST https://:@//recs/items/category/{cat_level}/{cat_id}`
### Request Parameters
Parameter | Required | Description
--------- | ---- | ------- | -----------
cat_level | Yes | Category level in hierarchical categories order.
cat_id | Yes | Category id.
### Body Parameters
Parameter | Required | Type | Description
--------- | -------- | ---- | -----------
k | Yes | Integer | number of recommendations to retrieve
customer_id | No | String | Customer id.
visitor_id | No | String | Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie).
bu_id | No | String | Business unit id. If this value is not send, then default business unit id will be taken.
cart_items | No | String | List of cart item IDs separated by ';' (for example 12;45;94;14)
user_agent | No | String | a string representing the customer's browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0)
user_ip | No | String | a string with the customer's IP address (for example 74.125.230.36)
ref | No | String | Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date | No | String | Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).
### Response
Code | Description
--- | --------
200 | Request was successfully completed. Returns content of item id list in JSON format. Example: ["45812", "45212", "654323", "7865146"]
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error
## Checkout page
```http
POST /client-services/recs/items/checkout HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14
```
This function is used to request recommendations in checkout page. A typical label for such recommendations is 'People who bought this also bought'.
* While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
*
### HTTP Request
`POST https://:@//recs/items/checkout`
### Body Parameters
Parameter | Required | Type | Description
--------- | -------- | ---- | -----------
k | Yes | Integer | number of recommendations to retrieve
customer_id | No | String | Customer id.
visitor_id | No | String | Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie).
bu_id | No | String | Business unit id. If this value is not send, then default business unit id will be taken.
cart_items | No | String | List of cart item IDs separated by ';' (for example 12;45;94;14)
user_agent | No | String | a string representing the customer's browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0)
user_ip | No | String | a string with the customer's IP address (for example 74.125.230.36)
ref | No | String | Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date | No | String | Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).
### Response
Code | Description
--- | --------
200 | Request was successfully completed. Returns content of item id list in JSON format. Example: ["45812", "45212", "654323", "7865146"]
400 | Bad request – mostly due wrong sending parameters structure
500 | Internal server error