A catalog is a list of items which may include content or products.
Create Catalog
You can create a new catalog from the API by using the create catalog API end-point.
Inputs:
- “name”: Catalog name (string)
Output:
- On successful create, returns the catalog’s unique identifier
Sample call:
- cURL
curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"catalog" : {"name" : "ACME Item Catalog"}}' -u <USER API KEY>: https://api.getblueshift.com/api/v1/catalogs
Sample response:
- JSON
{"catalog_uuid":"<CATALOG UUID>"}
Add Item To Catalog
You may add multiple items to a catalog in batches of 100 items at a time, by using the add item to catalog API end-point. We recommend you to limit the no. of api calls to 5 per second.
Inputs:
- "catalog uuid": Use the catalog uuid as returned from the create a catalog api end-point
- Array of products
Output:
- On success, returns “ok”
- cURL
curl -v -H "Accept: application/json" -H "Content-type: application/json" -X PUT -u <USER API KEY>: https://api.getblueshift.com/api/v1/catalogs/<CATALOG UUID>.json -d '
{
"catalog": {
"products": [
{
"brand": "Nike",
"category": [
"Home",
"Home > Shoes",
"Home > Shoes > Running"
],
"image": "http://server/path/image.jpg",
"msrp": "47",
"price": "37.99",
"product_id": "189909",
"availability": "in stock",
"tags": [
"running",
"athlete"
],
"title": "Nike Jordan Running Shoes in Blue",
"web_link": "http://server/path/product.html"
},
{
"brand": "Reebok",
"category": [
"Home",
"Home > Shoes",
"Home > Shoes > Sports"
],
"image": "http://server/path/image2.jpg",
"msrp": "47",
"price": "37.99",
"product_id": "189910",
"availability": "in stock",
"tags": [
"basketball"
],
"title": "Reebok Basketball Shoes",
"web_link": "http://server/path/product2.html"
}
]
}
}'
Catalog Attributes
Attribute | Description | Example |
product_id | Unique identifier of item. This is what you pass in the product_ids in your events and should match exactly | 123345jjd |
title | Title of item | 32" LCD TV |
web_link | URL for item on your website | http://server/path.html |
image | A link to the image of item | http://server/image.jpg |
price | Selling price | 29 |
category | Array of strings with category identifier starting from root of taxonomy | Home, Home > Electronics |
brand | Brand name of item | Nike |
msrp | Maximum suggested retail price | 35 |
availability | Indicates sku status | ["in stock", "out of stock"] |
start_date | Indicates active/inactive status | ISO 8601 format (2016-02-02T04:19:42Z) |
end_date | Indicates active/inactive status | ISO 8601 format (2016-02-02T04:19:42Z) |
parent_sku | Ties all variants or child items together | a123345jjd |
tags | An array of strings denoting grouping of similar products into collections or groups | |
custom attribute (create your own) | You may pass any other attribute and it would get saved | For example: category_url, alt_images, etc. |
Error Codes & Responses:
Code | Text | Description |
400 | Bad Request | The request was invalid or cannot be otherwise served. An accompanying error message will explain further |
413 | You can upload maximum 100 products in one api call | The server is refusing to process a request because the request payload is larger than the server is willing or able to process. |
422 | Unprocessable Entity | Some/all of the products have invalid data, please check the response for more information on. |
429 | Rate limit exceeded | Too many requests |
500 | Internal Server Error | Please contact blueshift for more information |
502 | Service unavailable, please retry | Bad Gateway, re-try with exponential backoff |
503 | Service unavailable, please retry | Service Unavailable, re-try with exponential backoff |
504 | Service unavailable, please retry | Gateway Timeout, please re-try with exponential backoff |
Sample Error Response:
- JSON
{
"products": [
{
"brand": "Nike",
"category": [
"Home",
"Home > Shoes",
"Home > Shoes > Running"
],
"image": "http://server/path/image.jpg",
"msrp": "47",
"price": "37.99",
"stock": "in stock",
"tags": [
"running",
"athlete"
],
"title": "Nike Jordan Running Shoes in Blue",
"web_link": "http://server/path/product.html",
"catalog_uuid": "326da192-e461-4151-bf16-0f7ef0ed6592",
"product_id": null
},
{
"brand": "Reebok",
"category": [
"Home",
"Home > Shoes",
"Home > Shoes > Sports"
],
"image": "http://server/path/image2.jpg",
"msrp": "47",
"price": "37.99",
"availability": "in_stock",
"tags": [
"basketball"
],
"web_link": "http://server/path/product2.html",
"catalog_uuid": "326da192-e461-4151-bf16-0f7ef0ed6592",
"product_id": "189910"
}
],
"errors": [
{
"product_id": [
"can't be blank"
]
},
{
"title": [
"can't be blank"
]
}
]
}