Catalog API

Elizabeth

October 12, 2017 22:45

A catalog is a list of items which may include content or products.

Create Catalog
Add Item To Catalog
Catalog Attributes

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"
      ]
    }
  ]
}