Catalog API v1

Returns the contents of the catalog, as selected by brand, category and/or search term. Also returns a navigation object listing the categories, brands, merchants, etc... of the passed request parameters. See all request parameters and response objects below.

The Catalog REST-like API supports JSON and JSONP formats. All of the resources are described below. This API is not a strictly REST because it's been crafted to support JSONP.

JSONP Callback Parameter

In all requests, you may specific a callback parameter for JSONP responses. This parameter wraps your response in a callback method of your choice. For example, appending callback=cb to your request will result in a response body of: cb && cb(...). Callbacks may only contain alphanumeric characters and underscores; any invalid characters will be stripped.


Request format

http://api.shoppable.com/v1/token/:yourApiToken/catalog/?rows=:rows&offset=:offset&sort=:sorte&size=:sort&brand=:(brand)&category=:(category)&search=:search_phrase

cURL Example

curl -H "Referer: http://example.com" http://api.shoppable.com/v1/token/QTKjF6dJrYC3NOwE2498831069e1b964/catalog/?search=shoes&rows=20&offset=0

Request parameters

Parameter Type Description
apiToken

REQUIRED

URL Param The API token for your domain. The API token must match the domain in the Referer header.
rows

OPTIONAL

Query String Param Limits the number of product records returned in the response. The default is set to 20.
offset

OPTIONAL

Query String Param The beginning index (one-base) for extracting a modified array. The default is to begin from 1.
search

OPTIONAL

Query String Param Search Term to search for in catalog. Uses Shoppable field weights to determine relevance
brands

OPTIONAL

Query String Param Comma separated list of brands for query filter.
categories

OPTIONAL

Query String Param Comma separated list of categories used for query filter.
sort

OPTIONAL

Query String Param List of how product results should be sorted. Valid values are: -last_modified, price, -price, name and ransom.
sizes

OPTIONAL

Query String Param Comma separated list of sizes for query filter.
colors

OPTIONAL

Query String Param Comma separated list of colors for query filter.
merchants

OPTIONAL

Query String Param Comma separated list of merchants for filtering.
min_price

OPTIONAL

Query String Param Minimum price for query filter.
max_price

OPTIONAL

Query String Param Maximum price for query filter.
discount_type

OPTIONAL

Query String Param Parameter to include or exclude sale items. 'all' - (default) No filters and display all products. 'on_sale' - Filter only sale items. 'full_price' - Exclude all on sale items.
navigation_type

OPTIONAL

Query String Param Parameter for how the navigation is returned. Options are "limited","category_all", "category_only","except_category","all","none". Default selection is "limited", providing only the top 100 results of each naviation section.
part_numbers

OPTIONAL

Query String Param Comma separated list of part_numbers.

Response object

The response contains a JSON object with the following attributes:

Attribute Description
products An array of products in the query result.
metadata Metadata of the information returned.
navigation Navigation object for display of navigation interface.

Product object

Each product in the products array will contain the following attributes.

Attribute Description
part_number 72Lux's part number.
name The name.
brand The brand name.
merchant The merchant name from which this product is sold.
description The description. This normally won't contain HTML markup unless you add your own markup in the Shoppable Dashboard.
url The direct URL to the product on the merchant's site.
active A boolean that indicates whether the product is available for purchase. By default, this will always be true since the API only responds with active products.
colors An array that contains the various SKU's for a product. (see below)
image A default image for the product. This will be set to the image of the first SKU in the colors array. This is useful for displaying the price even when there are no available SKUs for the product.
category The category of the product, if one is set. If a category is not set, this attribute will be omitted. The category is formatted as "Level 1 category > Level 2 category > ..."
material The material the product is made from, if one is set. If the material is not set, this attribute will be omitted.
merchant_item_id The merchant's item ID for the product if one is set. If the merchant_item_id is not set by the merchant, this attribute will be omitted.
customer_service_url The merchant's customer service URL if one is set. If the customer_service_url is not set by the merchant, this attribute will be omitted.
return_policy_url The merchant's return policy URL if one is set. If the return_policy_url is not set by the merchant, this attribute will be omitted.
retail_price A default retail_price for the product. This will be set to the retail_price of the first SKU in the colors array. This is useful for displaying the price even when there are no available SKUs for the product.
sale_price A default sale_price for the product. This attribute is only present when the item is discounted from it's retail price. This will be set to the sale_price of the first SKU in the colors array. This is useful for displaying the sale price even when there are no available SKUs for the product.
alt_images An array containing all of the images 72Lux has for the product. The default image from above will always be the first element of the array.
free_shipping A boolean indicating whether this product qualifies for free shipping.
lead_color If the publisher has set a lead color for this product on the Shoppable Dashboard, this attribute will be set to the name of that color. In addition, the lead color will always be the first element in the colors array.
custom_classes If the publisher has set any custom CSS classes for this product on the Shoppable Dashboard, this attribute will contain a string of those custom CSS class names.

Color object

Each color in the colors array will contain the following attributes.

Attribute Description
color The name of the color. This attribute will be set to an empty string "" if the product doesn't come in different colors.
retail_price The retail_price for this color.
sale_price The sale_price for this color. This attribute is only present when the item is discounted from it's retail price.
images An array of image URLs for this color. Each color will always have at least one image, but it might not always be unique to the color.
sizes An array that contains the various SKU's for a color. (see below)

Size object

Each size in the sizes array will contain the following attributes.

Attribute Description
id 72Lux's unique SKU for this color/size variant of the product. This ID is used for adding SKU's to a shopping cart
size A string containing the size of the current SKU. This attribute is omitted if the product does not come in different sizes.
active A boolean that indicates whether this SKU is available for purchase. By default, this will always be true since the API only responds with active SKUs.
merchant_sku The merchant's SKU for the current color/size combination if one is set. If the merchant_sku is not set by the merchant, this attribute will be omitted.

Metadata object

Each color in the colors array will contain the following attributes.

Attribute Description
count Count of total products in the request.
query_time The query_time for this request.

Each color in the navigation array will contain the following attributes.

Attribute Description
previous_page_url The previous url for paging through the result set. A "" is returned if you are at the first result set.
next_page_url The next url for paging through the result set.
url The current url requested.
colors An array list of the colors of the result set.
sizes An array that contains the sizes and count for the search query
brands An array that contains the brands and count for the search query
merchants An array that contains the merchants and count for the search query
min_price The minimum price in the result set.
max_price The maximum price in the result set.

Example response

{
  "metadata": {
    "count": 89,
    "query_time": 7
  },
  "navigation": {
    "colors": [
      {
        "color": "airforce",
        "count": 15
      },
      {
        "color": "black",
        "count": 4
      },
      {
        "color": "blue",
        "count": 89
      },
      {
        "color": "blueblack",
        "count": 4
      },
      {
        "color": "bright",
        "count": 8
      },
      {
        "color": "france",
        "count": 2
      },
      {
        "color": "light",
        "count": 11
      },
      {
        "color": "sky",
        "count": 1
      },
      {
        "color": "turkey",
        "count": 14
      }
    ],
    "merchants": [
      {
        "merchant": "reiss",
        "count": 89
      }
    ],
    "sizes": [
      {
        "size": "36",
        "count": 8
      },
      {
        "size": "38",
        "count": 7
      },
      {
        "size": "40",
        "count": 6
      },
      {
        "size": "42",
        "count": 7
      },
      {
        "size": "44",
        "count": 8
      },
      {
        "size": "46",
        "count": 6
      },
      {
        "size": "L",
        "count": 8
      },
      {
        "size": "M",
        "count": 6
      },
      {
        "size": "S",
        "count": 8
      },
      {
        "size": "UK10 / US6",
        "count": 2
      },
      {
        "size": "UK12 / US8",
        "count": 3
      },
      {
        "size": "UK14\n/US10",
        "count": 2
      },
      {
        "size": "UK14 /US10",
        "count": 1
      },
      {
        "size": "UK4 / US0",
        "count": 2
      },
      {
        "size": "UK6 / US2",
        "count": 2
      },
      {
        "size": "UK8 / US4",
        "count": 2
      },
      {
        "size": "XL",
        "count": 3
      },
      {
        "size": "XS",
        "count": 6
      },
      {
        "size": "XXL",
        "count": 2
      }
    ],
    "categories": [],
    "brands": [
      {
        "brand": "reiss",
        "count": 89
      }
    ],
    "price_min": 111,
    "price_max": 935,
    "url": "/v1/token/yEP3hmeAOyzxNObKa09537820d6631c2/catalog?search=jacket&brands=Reiss&colors=blue",
    "previous_page_url": "",
    "next_page_url": "/v1/token/yEP3hmeAOyzxNObKa09537820d6631c2/catalogsearch=jacket&brands=Reiss&colors=blue&offset=3"
  },
  "products": [
    {
      "part_number": "1010-65300631000",
      "name": "Verona SEAM DETAIL JACKET",
      "brand": "Reiss",
      "merchant": "REISS",
      "description": "Reiss seam detail jacket. Verona in turkish blue is a slim\nfit, funnel neck coat. This fully-lined, wool-blend style has\nexposed seam and dart detail, slit front pockets and a concealed\nplacket fastening with slant stitching.",
      "url": "http://click.linksynergy.com/link?id=v9jIDxMZD/A&offerid=213891.165300631000&type=15&murl=http%3A%2F%2Fwww.reiss.com%2Fus%2Fwomens%2Fcoats-and-jackets%2Fverona%2Fturkish-blue",
      "color": "Turkish blue",
      "image": [
        "http://img.reiss.co.uk/downloads/Image/product/487x558/653006-31-1.jpg"
      ],
      "material": "35% wool 63% polyester 2% elastane",
      "retail_price": 395,
      "price": 395
    },
    {
      "part_number": "1010-13300331000",
      "name": "Cramont PERFORATED LEATHER JACKET",
      "brand": "Reiss",
      "merchant": "REISS",
      "description": "Reiss perforated leather jacket. Crafted from perforated inky\nblue leather, this stylish Cramont jacket will add a luxe extra\nlayer to all manner of ensembles. The fully lined jacket features a\ntwo way zip and button collar front closure, elasticated ribbed\nsleeve cuffs and hem, a zip pocket to each hip and an interior zip\npocket.",
      "url": "http://click.linksynergy.com/link?id=v9jIDxMZD/A&offerid=213891.113300331000&type=15&murl=http%3A%2F%2Fwww.reiss.com%2Fus%2Fmens%2Fcoats-and-jackets%2Fcramont%2Fblue",
      "color": "Blue",
      "image": [
        "http://img.reiss.co.uk/downloads/Image/product/487x558/133003-31-1.jpg"
      ],
      "material": "100% goat suede",
      "retail_price": 710,
      "price": 710
    },
    {
      "part_number": "1010-18204531012",
      "name": "Summer FITTED JACKET",
      "brand": "Reiss",
      "merchant": "REISS",
      "description": "Reiss fitted jacket. Summer in blue is a one-button fitted\nblazer. With a wide notch lapel, this snappy little jacket has four\nwelt pockets to the front, three-button cuffs and shape-enhancing\nseaming to the back.",
      "url": "http://click.linksynergy.com/link?id=v9jIDxMZD/A&offerid=213891.118204531012&type=15&murl=http%3A%2F%2Fwww.reiss.com%2Fus%2Fwomens%2Fcoats-and-jackets%2Fsummer%2Fblue",
      "color": "Blue",
      "image": [
        "http://img.reiss.co.uk/downloads/Image/product/487x558/182045-31-1.jpg"
      ],
      "material": "95% polyester 5% elastane",
      "retail_price": 425,
      "sale_price": 205,
      "price": 205
    }
  ]
}