Frames API v1

Returns the contents of the frame, as selected by frameId or tag.

The Frames 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/:apiToken/frame/:frameId?rows=:rows&offset=:offset

Or

http://api.shoppable.com/v1/token/:apiToken/frame/tag/:tag?rows=:rows&offset=:offset

cURL Example (by frameId)

curl -H "Referer: http://example.com" http://api.shoppable.com/v1/token/QTKjF6dJrYC3NOwE2498831069e1b964/frame/1

cURL Example (by tag)

curl -H "Referer: http://example.com" http://api.shoppable.com/v1/token/QTKjF6dJrYC3NOwE2498831069e1b964/frame/tag/example-tag

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.
frameId

REQUIRED (if not using tag)

URL Param The Id of the requested frame.
tag

REQUIRED (if not using frameId)

URL Param The tag of the requested frame. Make sure this parameter is properly URL-encoded.
rows

OPTIONAL

Query String Param Limits the number of product records returned in the response. The default is to return all products in the frame.
offset

OPTIONAL

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

Response object

The response contains a JSON object with the following attributes:

Attribute Description
products An array of products in the frame.
frameName The name of the frame.
frameId The Id of the frame.

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.

Example response

{
  "products": [
    {
      "part_number": "1071-9780007161263",
      "name": "A SENSE OF THE WORLD:HOW A BLIND MAN BECAME HISTORY'S GREATEST TR",
      "brand": "HarperCollins Publishers",
      "merchant": "HarperCollins Publishers",
      "description": "He was known simply as the Blind Traveler. A solitary, sightless adventurer, James Holman (1786-1857) fought the slave trade in Africa, survived a frozen captivity in Siberia, hunted rogue elephants in Ceylon, helped chart the Australian outback—and, astonishingly, circumnavigated the globe, becoming one of the greatest wonders of the world he so sagaciously explored. A Sense of the World is a spellbinding and moving rediscovery of one of history's most epic lives—a story to awaken our own senses of awe and wonder.",
      "url": "http://www.harpercollins.com/books/?isbn=9780007161263",
      "merchant_item_id": "9780007161263",
      "active": true,
      "colors": [
        {
          "color": "",
          "retail_price": 3.99,
          "images": [
            "http://www.harpercollins.com/harperimg/isbn/large/3/9780007161263.jpg"
          ],
          "sizes": [
            {
              "id": "1071-9780007161263/9780007161263",
              "active": true,
              "merchant_sku": "9780007161263"
            }
          ]
        }
      ],
      "image": "http://www.harpercollins.com/harperimg/isbn/large/3/9780007161263.jpg",
      "retail_price": 3.99,
      "alt_images": [
        "http://www.harpercollins.com/harperimg/isbn/large/3/9780007161263.jpg"
      ],
      "free_shipping": true
    },
    {
      "part_number": "1069-3715d8fc-659c-47cd-a299-bb0dea093bd5",
      "name": "Kids G Vilas 2 Grade School Shoe",
      "brand": "Puma",
      "merchant": "DTLR",
      "description": "<strong>Leather upper</strong> build for instantly recognizable style and durability. Lace-up closure for snug fit. Cushy midsole for comfort and support. Rubber outsole for enhanced grip. This Kid's Puma G. Villa shoe, features a leather upper build and cushy midsole designed to ensure serious comfort and durability.",
      "url": "http://gan.doubleclick.net/gan_click?lid=41000613802488500&pid=885922858041&adurl=http%3A%2F%2Fwww.dtlr.com%2Fproduct%2Fshoes%2Fkids%2Fgrade-school%2Fpuma-kids-g-vilas-2-grade-school%2Fdark-denim.html%3Fgdftrk%3DgdfV21658_a_7c2162_a_7c7352_a_7c885922858041&usg=AFHzDLulvRa8qbEX51ONnNheIpxGXoeI7g&pubid=21000000000329667",
      "merchant_item_id": "3715d8fc-659c-47cd-a299-bb0dea093bd5",
      "customer_service_url": "http://www.dtlr.com/document/customer-service.html",
      "return_policy_url": "http://www.dtlr.com/document/return-policy.html",
      "active": true,
      "lead_color": "Dark Denim",
      "colors": [
        {
          "color": "Dark Denim",
          "sale_price": 38.98,
          "retail_price": 55,
          "images": [
            "http://29.media.tumblr.com/tumblr_lisw5rptyA1qbbpjfo1_500.jpg"
          ],
          "sizes": [
            {
              "id": "1069-3715d8fc-659c-47cd-a299-bb0dea093bd5_606738674ad8c01a659525f0da8272cf",
              "active": true,
              "merchant_sku": "885922858041",
              "size": "4"
            },
            {
              "id": "1069-3715d8fc-659c-47cd-a299-bb0dea093bd5_61aeafb5713566c475d1f1c194f87849",
              "active": true,
              "merchant_sku": "885922858072",
              "size": "5.5"
            },
            {
              "id": "1069-3715d8fc-659c-47cd-a299-bb0dea093bd5_cc269c6591b067d41cba722954a87359",
              "active": true,
              "merchant_sku": "885922858096",
              "size": "6.5"
            }
          ]
        },
        {
          "color": "Gray - White",
          "sale_price": 38.98,
          "retail_price": 55,
          "images": [
            "http://www.dtlr.com/upload/img/Puma-Kids-G-Vilas-2-Grade-School/Gray--White/Puma-Kids-G-Vilas-2-Grade-School-Gray--White_E2r6E_600__scale_width.jpg"
          ],
          "sizes": [
            {
              "id": "1069-3715d8fc-659c-47cd-a299-bb0dea093bd5_f075c164fd9163052b6fe45d5760a93d",
              "active": true,
              "merchant_sku": "886375736825",
              "size": "4"
            },
            {
              "id": "1069-3715d8fc-659c-47cd-a299-bb0dea093bd5_bb6b23a2871ab0c1bf93669e3f6b1106",
              "active": true,
              "merchant_sku": "886375736832",
              "size": "4.5"
            }
          ]
        }
      ],
      "image": "http://29.media.tumblr.com/tumblr_lisw5rptyA1qbbpjfo1_500.jpg",
      "retail_price": 55,
      "sale_price": 38.98,
      "alt_images": [
        "http://29.media.tumblr.com/tumblr_lisw5rptyA1qbbpjfo1_500.jpg",
        "http://www.dtlr.com/upload/img/Puma-Kids-G-Vilas-2-Grade-School/Gray--White/Puma-Kids-G-Vilas-2-Grade-School-Gray--White_E2r6E_600__scale_width.jpg"
      ]
    }
  ],
  "frameName": "Test frame2",
  "frameId": 22
}