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
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}]}, ...]
# 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:
{"customerId" : "<customer id>",
"buId" : "<business unit>",
"orderTimestamp": "<order timestamp, format yyyy-MM-ddTHH:mm:ss.ms>", "bonusCode": <cart bonus code>, "discount": <discount>,
"items": [{"itemId":"<item id>", "price":4.45, "quantity": 2, "discount": <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://<usr>:<pssw>@<HOST>/<c_path>/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
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},...]
# 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:
{"itemId" : "<item id>",
"name" : "<item name>",
"description" : "<item description>",
"price" : "<price>",
"category1Id" : "<category hierarchy 1, category IDs separated by | >",
"category2Id" : "<category hierarchy 2, category IDs separated by | >",
"category3Id" : "<category hierarchy 3, category IDs separated by | >",
"category4Id" : "<category hierarchy 4, category IDs separated by | >",
"category5Id" : "<category hierarchy 5, category IDs separated by | >",
"category6Id" : "<category hierarchy 6, category IDs separated by | >",
"deliveryTime": "<time in days for delivery>",
"discount": "<discount>",
"buIds": ["<list of business units>"],
"active": "<boolean value, defines if item is active right now>"
}
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://<usr>:<pssw>@<HOST>/<c_path>/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
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"}, ...]
# 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:
{"customerId" : "<customer id>",
"gender": "<cusotmer gender: 'male' or 'female'>",
"birth": "<cusotmers birth date>",
"location":"<customers 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://<usr>:<pssw>@<HOST>/<c_path>/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
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}, ...]
# 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:
{"buId":"<business unit id>",
"itemId":"<itme id>",
"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://<usr>:<pssw>@<HOST>/<c_path>/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
POST /client-services/business_units/online/15455/activate HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
Function is used to activate an item in the given Business Unit.
HTTP Request
https://<usr>:<pssw>@<HOST>/<c_path>/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
POST /client-services/business_units/online/15455/deactivate HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
Function is used to deactivate an item in the given Business Unit.
HTTP Request
https://<usr>:<pssw>@<HOST>/<c_path>/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
POST /client-services/business_units/online/items HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
Response:
["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://<usr>:<pssw>@<HOST>/<c_path>/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 )
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
# 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://<usr>:<pssw>@<HOST>/<c_path>/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
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
# 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://<usr>:<pssw>@<HOST>/<c_path>/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
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
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://<usr>:<pssw>@<HOST>/<c_path>/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
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
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://<usr>:<pssw>@<HOST>/<c_path>/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
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://<usr>:<pssw>@<HOST>/<c_path>/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
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://<usr>:<pssw>@<HOST>/<c_path>/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 |