ShopSavvy Data API

Documentation & Examples

View All Plans

Getting Started

  • First you'll need to subscribe to one of our plans. There's a free plan available you can subscribe to try out the API.
  • Once you've subscribed, if you're not automatically redirected, go to the plan's page by going to the Product Catalog in our developer portal and selecting the plan you're now subscribed to.
  • Click Authentication in the sidebar.
  • Use the Base URL and API Keys shown there to interact with the API.

Your Base URL and API Keys will look something like this:

Now, you'll make HTTP requests to the API using the Base URL shown there. You'll need to supply the Primary API Key shown there in an HTTP Header field called X-BLOBR-KEY.

That's it. You're now ready to start requesting data from the API.

Keep reading for details on how to request each type of data, and how to use each of the features of the API, here's a quick list if you want to jump straight to a section:

Products

Retrieving Product Details

Cost: 1 credit per product requested.

You can retrieve product details by using the GET /products?ids={identifiers} endpoint.

The identifiers parameter can be a comma-separated list of one or more identifiers.
You can use mix and match any combination of different identifiers, like GET /products?ids=B07G14HTBZ,611247369449,3ONn300xybP3y66ibqc1.

An identifier can be any of the following:

  • UPC
  • EAN
  • ISBN
  • GTIN
  • Amazon ASIN
  • Model Number
  • URL at any Retailer
  • ShopSavvy Product ID
GET /products?ids=611247373064,611247369449

The response will be a JSON array of products, in the same order as the `ids` parameter specified in the request.

Products will each have the following fields. (Note: not all fields are available on all products).

  • title: The name of the product.
  • category: A comma separated list of categories for the product.
  • brand: The brand of the product.
  • color: The color of the product.
  • model: The model of the product.
  • shopsavvy: The ShopSavvy Product ID of the product. This can optionally be used alongside any other identifier when retrieving products, offers, etc.
  • barcode: The barcode of the product. Will always be a number.
  • amazon: The Amazon ASIN of the product.
  • mpn: The manufacturer's part number of the product.
  • images: An array of image URLs pointing to images of the product.

[
      {
        "title": "Keurig K-Mini Single Serve Coffee Maker, Black",
        "category": "Grocery & Gourmet Food > Beverages > Coffee, Tea & Cocoa > Coffee > Single-Serve Capsules & Pods",
        "brand":"Keurig",
        "color":"Black",
        "model": "K-MINI",

        "shopsavvy": "3ONn300xybP3y66ibqc1",
        "barcode": 611247373064,
        "amazon": "B07G14HTBZ",
        "mpn": "5000200237",

        "images":[
        "https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/31jy5fSzyRL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/411uxu%2Bg17L.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/41jEx1YoTQL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/41CanelWIlL.jpg",
        ]
      },
      {
        "title": "Keurig K-Elite Single Serve K-Cup Pod Maker with with Strength and Temperature Control, Iced Coffee Capability, 12oz Brew Size, Brushed Silver",
        "category": "Home & Kitchen > Kitchen & Dining > Coffee, Tea & Espresso > Coffee Makers > Single-Serve Brewers",
        "brand":"Keurig",
        "color":"Silver",
        "model": "K-Elite",

        "shopsavvy": "DrKWneG0MpFlZpwZXNYa",
        "barcode": 611247369449,
        "amazon": "B0788F3R8X",
        "mpn": "5000197492",

        "images":[
        "https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/411fEW99TlL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/51bdqFw6lNL.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/51-NbDX9S7L.jpg",
        "https://images-na.ssl-images-amazon.com/images/I/412o2pQ-swL.jpg"
        ]
      }
    ]

Products

Retrieving Product Details in CSV Format

Cost: 1 credit per product requested.

By default all responses are in JSON format, but you can also retrieve products in CSV format by adding ?format=csv to the request, like this:

GET /products?ids=611247373064,611247369449&format=csv

When you do this, the response will be formatted as a CSV file, with columns for each of the different fields, and each product on its on row:

shopsavvy,barcode,amazon,title,category,brand,color,mpn,model,image
3ONn300xybP3y66ibqc1,611247373064,B07G14HTBZ,"Keurig K-Mini Single Serve Coffee Maker, Black","Grocery & Gourmet Food > Beverages > Coffee, Tea & Cocoa > Coffee > Single-Serve Capsules & Pods",Keurig,Black,5000200237,K-MINI,https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/31jy5fSzyRL.jpg
DrKWneG0MpFlZpwZXNYa,611247369449,B0788F3R8X,"Keurig K-Elite Single Serve K-Cup Pod Maker with with Strength and Temperature Control, Iced Coffee Capability, 12oz Brew Size, Brushed Silver","Home & Kitchen > Kitchen & Dining > Coffee, Tea & Espresso > Coffee Makers > Single-Serve Brewers",Keurig,Silver,5000197492,K-Elite,https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/411fEW99TlL.jpg

Offers

Retrieving Offers for Product(s) at All Retailers

Cost: 3 credits per product requested.

An offer represents a product being sold by specific retailer or seller for a specific price, condition, etc.

You can retrieve offers for products by using the GET /products/offers endpoint, like this:

GET /products/offers?ids=611247373064,611247369449

This will return an array of products, each containing a new offers property, which will be an array of offer objects, each containing the following properties:

  • id - A unique identifier for this offer.
  • availability - The availability of the product in the offer. This will only be present if the value is confirmed and known. It will be missing if availability is unknown. Will be either a string of "in" or "out"
  • condition - The condition of the product in the offer. Will be a string of "new", "used", or "refurbished".
  • retailer - The name of the retailer or marketplace the offer is for.
  • price - The price of the product in the offer. Will always be a number.
  • seller - The name of the marketplace seller selling this product. If missing, then the offer is from a first-party retailer and there is no marketplace seller.
  • URL - The URL for the offer.
  • timestamp - An ISO 8601 formatted date and time representing when the offer was last seen by ShopSavvy.

[
    {
      "title": "Keurig K-Mini Single Serve Coffee Maker, Black",
      "category": "Grocery & Gourmet Food > Beverages > Coffee, Tea & Cocoa > Coffee > Single-Serve Capsules & Pods",
      "brand":"Keurig",
      "color":"Black",
      "model": "K-MINI",

      "shopsavvy": "3ONn300xybP3y66ibqc1",
      "barcode": 611247373064,
      "amazon": "B07G14HTBZ",
      "mpn": "5000200237",

      "images":[
      "https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/31jy5fSzyRL.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/411uxu%2Bg17L.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/41jEx1YoTQL.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/41CanelWIlL.jpg",
      ],

      "offers": [
        {
          "id": "0IUouCFtZEhxeOablTPl",
          "availability":"in",
          "condition": "new",
          "retailer": "Amazon",
          "price": 74.96,
          "seller": "Palm Tree Deals",
          "URL": "https://www.amazon.com/dp/B07GV2S1GS?m=A1GKQADQC2VI6E",
          "timestamp": "2022-05-01T22:36:33.236Z"
        },
        {
          "id": "0RmL0ZMUesP2PmSlP97G",
          "availability":"in",
          "condition": "new",
          "retailer": "Amazon",
          "price": 58.86,
          "URL": "https://www.amazon.com/dp/B07GV2S1GS",
          "timestamp": "2022-05-03T22:52:06.802Z"
        },
        {
          "id": "0qp0KKdFnwIi3c09kGyT",
          "availability":"in",
          "condition": "new",
          "retailer": "Walmart",
          "price": 60.34,
          "URL": "https://www.walmart.com/ip/Keurig-K-Mini-Single-Serve-Coffee-Maker-Black/389238886?selectedSellerId=FBB34940E137490C8ABD825B48534874",
          "timestamp": "2022-05-01T20:38:25.218Z"
        },
        {
          "id": "2EHAxfhrvF6hEFs8IarY",
          "availability":"in",
          "condition": "new",
          "retailer": "Walmart",
          "price": 81.5,
          "seller": "Focus Camera",
          "URL": "https://www.walmart.com/ip/Keurig-K-Mini-Single-Serve-K-Cup-Pod-Coffee-Maker-6-to-12-oz-Brew-Sizes-Black/389238886?selectedSellerId=888853D0A1394FA4BB92C88C4FD20210",
          "timestamp": "2022-05-02T20:26:42.657Z"
        },
        {
          "id": "1upFPYp9qj74v8S0E7qp",
          "availability":"in",
          "condition": "refurbished",
          "retailer": "shopcheap.club",
          "price": 59.99,
          "seller": null,
          "URL": "https://shopcheap.club/kitchen-tabletop/keurig-k-mini-coffee-maker-single-serve-k-cup-pod-coffee-brewer-6-to-12-oz-brew-sizes-black/?utm_source=Google%20Shopping&utm_campaign=ShopCheap&utm_medium=cpc&utm_term=7944",
          "timestamp": "2022-05-03T13:49:10.053Z"
        },
        ...
      }
    ]
  },
  ...
]

Offers

Retrieving Offers for a Single Retailer

Cost: 2 credits per product requested.

You can retrieve offers for products at a single retailer by specifying a value for the the retailer parameter. The value should be the domain of the retailer you want to retrieve offers for, like amazon.com or bestbuy.com.

GET /products/offers?ids=611247373064,611247369449&retailer=amazon.com

The response will be in the same format and schema, but it will only contain offers from your specified retailer.

[
    {
      "title": "Keurig K-Mini Single Serve Coffee Maker, Black",
      "category": "Grocery & Gourmet Food > Beverages > Coffee, Tea & Cocoa > Coffee > Single-Serve Capsules & Pods",
      "brand":"Keurig",
      "color":"Black",
      "model": "K-MINI",

      "shopsavvy": "3ONn300xybP3y66ibqc1",
      "barcode": 611247373064,
      "amazon": "B07G14HTBZ",
      "mpn": "5000200237",

      "images":[
      "https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/31jy5fSzyRL.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/411uxu%2Bg17L.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/41jEx1YoTQL.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/41CanelWIlL.jpg",
      ],

      "offers": [
        {
          "id": "0IUouCFtZEhxeOablTPl",
          "availability":"in",
          "condition": "new",
          "retailer": "Amazon",
          "price": 74.96,
          "seller": "ACME Deals",
          "URL": "https://www.amazon.com/dp/B07G14HTBZ?m=A1GKQADQC2VI6E",
          "timestamp": "2022-05-01T22:36:33.236Z"
        },
        {
          "id": "0RmL0ZMUesP2PmSlP97G",
          "availability":"in",
          "condition": "new",
          "retailer": "Amazon",
          "price": 58.86,
          "URL": "https://www.amazon.com/dp/B07G14HTBZ",
          "timestamp": "2022-05-03T22:52:06.802Z"
        },
        ...
    ]
  },
  ...
]

Offers

Retrieving Offers for Product(s) in CSV Format

Cost: 3 credits per product requested when requesting all retailers, 2 credits per product when requesting a single retailer.

By default all responses are in JSON format, but you can also retrieve data in CSV format by adding ?format=csv to the request, like this:

GET /products/offers?ids=611247373064,611247369449&retailer=bestbuy.com&format=csv

When you do this, the response will be formatted as a CSV file, with columns for each of the different fields, and each product on its on row.

Each offer field will be a separate column, allowing for easy integration into spreadsheets and other tools or workflows.

shopsavvy,barcode,amazon,title,category,brand,color,mpn,model,image,currency-Best Buy,price-Best Buy,availability-Best Buy,condition-Best Buy,URL-Best Buy,timestamp-Best Buy
3ONn300xybP3y66ibqc1,611247373064,B07G14HTBZ,"Keurig K-Mini Single Serve Coffee Maker, Black","Grocery & Gourmet Food > Beverages > Coffee, Tea & Cocoa > Coffee > Single-Serve Capsules & Pods",Keurig,Matte Black,5000200237,K-MINI,https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/31jy5fSzyRL.jpg,USD,59.99,in,new,https://www.bestbuy.com/site/keurig-k-mini-single-serve-k-cup-pod-coffee-maker-matte-black/6358476.p?skuId=6358476&ref=NS&loc=101,2022-11-05T11:47:00.226Z
DrKWneG0MpFlZpwZXNYa,611247369449,B0788F3R8X,"Keurig K-Elite Single Serve K-Cup Pod Maker with with Strength and Temperature Control, Iced Coffee Capability, 12oz Brew Size, Brushed Silver","Home & Kitchen > Kitchen & Dining > Coffee, Tea & Espresso > Coffee Makers > Single-Serve Brewers",Keurig,Brushed Silver,5000197492,K-Elite,https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/411fEW99TlL.jpg,USD,129.99,,new,https://www.bestbuy.com/site/keurig-k-elite-single-serve-k-cup-pod-coffee-maker-brushed-silver/6203569.p?skuId=6203569,2022-11-05T11:33:16.004Z

Historical Offer Data

Retrieving Offers With Historical Offer Data

Cost: 3 credits per product requested when requesting all retailers, 2 credits per product when requesting a single retailer. Additionally, there is a cost of 1 credit per day of historical data requested.

Historical data can be requested by adding start and end parameters to the request. These should be formatted as YYYY-MM-DD. Here is an example:

GET /products/offers/history?ids=611247373064&start=2022-11-20&end=2022-11-27

Please note you'll be charged 1 credit for each day of historical data you request.

The response will be in the same format and schema as requests for offers, but each offer will include a history field, which will contain an array of historical changes for that specific offer. Each change will include these fields:

  • timestamp: An ISO 8601 formatted date and time representing when the change was seen by ShopSavvy.
  • price: The price of the offer at the time of the change. This will always be a number.
  • availability: The availability of the offer at the time of the change. This will only be present if the value is confirmed and known. It will be missing if availability is unknown. Will be either a string of "in" or "out"

Here's an example of a response with historical data:

[
    {
      "title": "Keurig K-Mini Single Serve Coffee Maker, Black",
      "category": "Grocery & Gourmet Food > Beverages > Coffee, Tea & Cocoa > Coffee > Single-Serve Capsules & Pods",
      "brand":"Keurig",
      "color":"Black",
      "model": "K-MINI",

      "shopsavvy": "3ONn300xybP3y66ibqc1",
      "barcode": 611247373064,
      "amazon": "B07G14HTBZ",
      "mpn": "5000200237",

      "images":[
      "https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/31jy5fSzyRL.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/411uxu%2Bg17L.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/41jEx1YoTQL.jpg",
      "https://images-na.ssl-images-amazon.com/images/I/41CanelWIlL.jpg",
      ],

      "offers": [
        {
          "id": "0IUouCFtZEhxeOablTPl",
          "availability":"in",
          "condition": "new",
          "retailer": "Amazon",
          "price": 74.96,
          "seller": "ACME Deals",
          "URL": "https://www.amazon.com/dp/B07G14HTBZ?m=A1GKQADQC2VI6E",
          "timestamp": "2022-05-01T22:36:33.236Z",
          "history": [
            {
              "timestamp": "2022-05-01T22:36:33.236Z",
              "price": 74.96,
              "availability": "in"
            },
            {
              "timestamp": "2022-05-02T22:36:33.236Z",
              "price": 70.99,
              "availability": "in"
            },
            {
              "timestamp": "2022-05-01T22:36:33.236Z",
              "price": 70.99,
              "availability": "out"
            },
            ...
          ]
        },
        ...
    ]
  },
  ...
]

Schedule Products

Enabling Scheduled Refreshes for Products

Cost: 1 credit per product scheduled + 3 credits every time each scheduled product is refreshed.

Enabling scheduled refreshes for products will cause ShopSavvy to refresh the pricing and availability data for the specified products on an interval you specify.

You can schedule one or more products using the same ids parameter as the GET /products and GET /products/offers endpoints.

Use the schedule parameter to specify how frequently you like the product(s) refreshed. This can be a string with a value of "hourly", "daily", or "weekly".

PUT /products/scheduled?ids=611247373064,611247369449&schedule=daily

This will begin refreshing the pricing and availability for the product(s), and return products that were just scheduled. Note: You will need to call the GET /products/offers endpoint whenever you want retrieve the latest data.

Schedule Products

Changing Refresh Schedule for Products

Cost: 1 credit per product scheduled + 3 credits every time each scheduled product is refreshed.

You can change how frequently previously scheduled product(s) are refreshed by calling the same endpoint but with a POST. Everything else works the same as enabling scheduled refreshes for new products.

Use the schedule parameter to specify how frequently you like the product(s) refreshed. This can be a string with a value of "hourly", "daily", or "weekly".

POST /products/scheduled?ids=611247373064&schedule=hourly&retailer=bestbuy.com

This will begin refreshing the pricing and availability for the product(s), and return products that had their refresh schedule changed. Note: You will need to call the GET /products/offers endpoint whenever you want retrieve the latest data.

Schedule Products

Disabling Scheduled Refreshes for Products

Cost: 0 credits per product scheduled.

Disabling scheduled refreshes for products will cause ShopSavvy to stop refreshing the pricing and availability data for the specified products.

DELETE /products/scheduled?ids=611247369449

Schedule Products

Retrieve Products Currently Enabled for Scheduled Refreshes

Cost: 0 credits.

GET /products/scheduled

This return all the products you currently have enabled for scheduled refreshes, along with each of their configuration and refresh interval.

[
  {
    "schedule":"hourly",
    "title": "Keurig K-Mini Single Serve Coffee Maker, Black",
    "category": "Grocery & Gourmet Food > Beverages > Coffee, Tea & Cocoa > Coffee > Single-Serve Capsules & Pods",
    "brand":"Keurig",
    "color":"Black",
    "model": "K-MINI",

    "shopsavvy": "3ONn300xybP3y66ibqc1",
    "barcode": 611247373064,
    "amazon": "B07G14HTBZ",
    "mpn": "5000200237",

    "images":[
    "https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/31jy5fSzyRL.jpg",
    "https://images-na.ssl-images-amazon.com/images/I/411uxu%2Bg17L.jpg",
    "https://images-na.ssl-images-amazon.com/images/I/41jEx1YoTQL.jpg",
    "https://images-na.ssl-images-amazon.com/images/I/41CanelWIlL.jpg",
    ],
  },
  {
    "schedule":"daily",
    "retailer":"bestbuy.com"
    "title": "Keurig K-Elite Single Serve K-Cup Pod Maker with with Strength and Temperature Control, Iced Coffee Capability, 12oz Brew Size, Brushed Silver",
    "category": "Home & Kitchen > Kitchen & Dining > Coffee, Tea & Espresso > Coffee Makers > Single-Serve Brewers",
    "brand":"Keurig",
    "color":"Silver",
    "model": "K-Elite",

    "shopsavvy": "DrKWneG0MpFlZpwZXNYa",
    "barcode": 611247369449,
    "amazon": "B0788F3R8X",
    "mpn": "5000197492",

    "images":[
    "https://x.shopsavvy.com/https://images-na.ssl-images-amazon.com/images/I/411fEW99TlL.jpg",
    "https://images-na.ssl-images-amazon.com/images/I/51bdqFw6lNL.jpg",
    "https://images-na.ssl-images-amazon.com/images/I/51-NbDX9S7L.jpg",
    "https://images-na.ssl-images-amazon.com/images/I/412o2pQ-swL.jpg"
    ],
  }
]

Tools

CSV to API Request Converter

This tool will allow you to upload a CSV file, choose a column to use as product identifiers, and it will give you the HTTP path to request from the API to get product or pricing data for each of those products in a single request.

Published

Legal

Subscribe for Updates

Get the latest news, and updates on ShopSavvy. You'll be glad you did!

TwitterInstagramFacebook

© 2024 Monolith Technologies, Inc. All rights reserved.