Product API v3

Returns a product object along with all its colors and sizes (if applicable), as selected by product part_number.

The Product 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 by partnumber or by upcs

http://api.shoppable.com/v3/product?part_numbers=:partnumber1,:partnumber2

http://api.shoppable.com/v3/product?upcs=:upcs,:upcs

cURL Example

curl -H "Bearer TokenExample1234567890" http://api.shoppable.com/v3/product?part_numbers=1070-B2AT6

Request parameters

Parameter Type Description
part_numbers

Optional

URL query The part_numbers of the products you are looking for.
upcs

Optional

URL query The upcs of the products you are looking for. Note while the part_number call will return one merchant the upcs call will return all merchants who have this upc. If a product is out of stock at a particular merchant the product will have outOfStock set to true and active set to false

Response object

The response contains a JSON object with the following attributes:

Attribute Description
part_number Returns the part number passed.
name Name of the product.
brand Brand of the product.
merchant Merchant selling the product and the party handling shipping.
merchant id Id of the merchant.
description Long description of the product.
url Affiliate link of the product.
category Nested categories. The category is formatted as "Level 1 category > Level 2 category > ..."
merchant_item_id part_number as used by the merchant.
customer_service_url Customer service URL of the merchant.
return_policy_url Return policy URL of the merchant.
active Availability of the product. Products may be unavailable due to it being out of stock or poor feed data.
colors Array of available colors with price for a product. Each color also has arrays of images and sizes.
image General image for the product.
retail_price retail price of the product.
sale_price Sale price of the product. This attribute will only be present if the product is on sale.
alt_images Alternate images of the product such as from different angles and/or colors.
free_shipping Whether shipping by the merchant is free.

Color object

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

color Available color for given product.
sale_price Sale price of the product for a specific color of the product. This attribute will only be present if the product is on sale.
retail_price Retails price of the product for a specific color of the product.
images Array of available images for a specific color of the product.
Sizes Array of available sizes for a specific color of the product.

Size object

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

id This is the SKU of the product of the specified color and size. This number is the most unique identifier of a product in a feed.
active Availablility on a specifc size and color of the product.
size Size of the product for a specific color.

Example response

Product at retail price:

{
  "part_number": "1070-B2AT6",
  "name": "Strapless Rose Applique Gabardine Dress, Black",
  "brand": "Lanvin",
  "merchant": "Neiman Marcus",
  "merchant_id": "1070",
  "description": "Tech gabardine shapes the sculptural silhouette of this Lanvin dress with artful appeal.  Look 3 of the Lanvin Fall 2013 runway . Compact tech gabardine with contrast floral appliques. Straight strapless neckline. Fitted bodice with natural waist. Full A-line circle skirt with hidden pockets. Hem hits around the knee. Exposed back zip. Polyester/silk. Made in Italy. Please note: Gloves and necklace are sold separately from dress. About Lanvin: Lanvin is the oldest French house of fashion still creating collections. Founded by Jeanne Lanvin as a millinery on Faubourg Saint-Honore in 1889 Paris, the company earned a following among French socialites. Today, critically acclaimed designer Alber Elbaz upholds the Lanvin tradition of supremely well-made clothes, adding shoes, handbags, jewelry and accessories to the collection.",
  "url": "http://click.linksynergy.com/link?id=v9jIDxMZD/A&u1=&type=15&offerid=279712&murl=http%3A%2F%2Fwww.neimanmarcus.com%2FLanvin-Strapless-Rose-Applique-Gabardine-Dress-Black%2Fprod159840188_cat9360738__%2Fp.prod%3Ficid%3D%26searchType%3DEndecaDrivenCat%26rte%3D%25252Fcategory.service%25253FitemId%25253Dcat9360738%252526pageSize%25253D30%252526No%25253D360%252526refinements%25253D%26eItemId%3Dprod159840188%26cmCat%3Dproduct",
  "category": "Women's > Dresses > Cocktail",
  "merchant_item_id": "B2AT6",
  "customer_service_url": "http://www.neimanmarcus.com/assistance/assistance.jsp?itemId=cat33940736",
  "return_policy_url": "http://www.neimanmarcus.com/assistance/assistance.jsp?itemId=cat33940742",
  "active": true,
  "colors": [
    {
      "color": "DARK BLUE",
      "retail_price": 6150,
      "images": [
        "http://images.neimanmarcus.com/ca/3/product_assets/B/2/A/T/6/NMB2AT6_mi.jpg"
      ],
      "sizes": [
        {
          "id": "1070-B2AT6_8d32bbf2ce59d0ebfa35a1b0d6f52518",
          "active": true,
          "size": "38/6"
        },
        {
          "id": "1070-B2AT6_33034156e95de39f89ff7781d27e37ba",
          "active": true,
          "size": "40/8"
        }
      ]
    }
  ],
  "image": "http://images.neimanmarcus.com/ca/3/product_assets/B/2/A/T/6/NMB2AT6_mi.jpg",
  "retail_price": 6150,
  "alt_images": [
    "http://images.neimanmarcus.com/ca/3/product_assets/B/2/A/T/6/NMB2AT6_mi.jpg"
  ],
  "free_shipping": true

On sale product:

{
  "part_number": "1030-730213",
  "name": "'Cloud' Running Shoe (Men)",
  "brand": "On Shoes",
  "merchant": "Nordstrom",
  "merchant_id": "1030",
  "description": "Get the best of both worlds with the CloudTec system: a cushioned landing and a barefoot-style takeoff in a Swiss-engineered running shoe ideal for a neutral-gait runner looking for lightweight comfort. Color(s): navy/ white. Brand: On Shoes. Style Name: On Shoes 'Cloud' Running Shoe (Men). Style Number: 730213.",
  "url": "http://click.linksynergy.com/deeplink?id=v9jIDxMZD/A&u1=&mid=1237&murl=http%3A%2F%2Fshop.nordstrom.com%2Fs%2Fon-shoes-cloud-running-shoe-men%2F3699384",
  "category": "Men's > Shoes > Athletic",
  "merchant_item_id": "730213",
  "customer_service_url": "http://shop.nordstrom.com/c/customer-service",
  "return_policy_url": "http://shop.nordstrom.com/c/return-policy",
  "active": true,
  "colors": [
    {
      "color": "NAVY/ WHITE",
      "sale_price": 54.96,
      "retail_price": 109.95,
      "images": [
        "http://content.nordstrom.com/imagegallery/store/product/large/9/_8838169.jpg"
      ],
      "sizes": [
        {
          "id": "1030-730213_88f841af538da1b7f2e31652f69dfa3d",
          "active": true,
          "size": "8.5 M"
        }
      ]
    }
  ],
  "image": "http://content.nordstrom.com/imagegallery/store/product/large/9/_8838169.jpg",
  "retail_price": 109.95,
  "sale_price": 54.96,
  "alt_images": [
    "http://content.nordstrom.com/imagegallery/store/product/large/9/_8838169.jpg"
  ],
  "free_shipping": true