Articles in this section

See more

Catalog API

Avatar
Elizabeth
  • Updated
Follow

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

  1. Create Catalog
  2. Add Item To Catalog
  3. 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",
      "sku": 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",
      "sku": "189910"
    }
  ],
  "errors": [
    {
      "sku": [
        "can't be blank"
      ]
    },
    {
      "title": [
        "can't be blank"
      ]
    }
  ]
}

Related articles

Comments

0 comments

Please sign in to leave a comment.