{"info":{"_postman_id":"651edbbe-252f-4547-9899-7f7b61def37a","name":"Button Product API","description":"

The Button Product API with support for:

\n\n

Notes

\n\n
\n



\n

Authentication

\n

Authentication to the Button Product API is done via the key query parameter.

\n

All requests must contain key. If you do not have a Product API key and think you should - reach out to support@usebutton.com.\n

\n



\n

API Location

\n

The Button Product API is located at:

\n

https://product-api.button-labs.com/preview/

\n

All endpoints are to support investigation of the Product API rather than their final integration point into the Button Product Suite.\n

\n



\n

Product Object

\n

The Product object represents a specific product at a specific retailer. Metadata is intentionally kept separate per-retailer (e.g. descriptions) to maintain merchandising.

\n

Fields

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldValue
idThe Button ID for this retailer product
retailerRetailer identifier (the root of the retailer domain, excluding tld & www)
product_idThe retailer's internal ID for this product
urlThe public URL for this product
titleThe retailer's displayed name for the product
descriptionThe retailer's on-site description for the product
image_urlProduct display image
pricePrice (string)
currencyCurrency code for the price
gtinThe GS1 GTIN for this product
mpnThe manufacturer's unique ID for this product
in_stockStock status - [\"Y\", \"N\", null]
skuThe retailer's stock keeping unit for this product
categoryRetailer's unstructured category (Note: Categories will likely change ahead of general availability)
manufacturerThe brand manufacturer of the product
\n



\n

Example

\n
{\n      \"id\": \"ed14bf7a4a0e8e2e897caa322b44acfcbaf96218\",\n      \"retailer\": \"target\",\n      \"product_id\": \"14709595\",\n      \"url\": \"https://www.target.com/p/justin-s-organic-dark-chocolate-peanut-butter-cups-1-4oz/-/A-14709595\",\n      \"title\": \"Justin's Organic Dark Chocolate Peanut Butter Cups - 1.4oz\",\n      \"description\": \"Dark Chocolate Peanut Butter Cup: If you’re reading this then you deserve a peanut butter cup.........\",\n      \"image_url\": \"https://target.scene7.com/is/image/Target/GUEST_5494b3b7-c074-439a-aee6-dbfa0a87b5ba?wid=1000&hei=1000\",\n      \"price\": \"2.19\",\n      \"currency\": \"USD\",\n      \"gtin\": \"894455000254\",\n      \"mpn\": \"14709595\",\n      \"in_stock\": \"Y\",\n      \"sku\": null,\n      \"category\": \"Food, Beverages & Tobacco > Food Items > Candy & Chocolate\",\n      \"manufacturer\": \"Justin's\"\n    }\n



\n



\n

Usage

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Authentication","slug":"authentication"},{"content":"API Location","slug":"api-location"},{"content":"Product Object","slug":"product-object"},{"content":"Usage","slug":"usage"}],"owner":"10028658","collectionId":"651edbbe-252f-4547-9899-7f7b61def37a","publishedId":"Szt7AqTj","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"0077FF"},"publishDate":"2020-05-21T19:31:03.000Z"},"item":[{"name":"Account Key Details","id":"feb483c2-5afb-40f0-9280-1b72bcff6e59","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://product-api.button-labs.com/preview/account?key={YOUR_PRODUCT_API_KEY}","description":"

Fetch an up-to-date Brand support list for the current Button Product API key.

\n

If you are using the Product Feed functionality, you will also find the list of feedUrls in this view

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldValue
retailersThe list of retailers available on your account
rate-limitThe maximum count / period that is permitted
feedUrlsThe map of retailer: feedUrl for feeds that are available
\n
","urlObject":{"protocol":"https","path":["preview","account"],"host":["product-api","button-labs","com"],"query":[{"description":{"content":"

Your Button Product API key

\n","type":"text/plain"},"key":"key","value":"{YOUR_PRODUCT_API_KEY}"}],"variable":[]}},"response":[{"id":"3150bb42-76c5-42e4-8095-87cce285e5d2","name":"Account Key Details","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://product-api.button-labs.com/preview/account?key={YOUR_PRODUCT_API_KEY}","protocol":"https","host":["product-api","button-labs","com"],"path":["preview","account"],"query":[{"key":"key","value":"{YOUR_PRODUCT_API_KEY}","description":"Your Button Product API key"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n\t\"meta\": {\n\t\t\"status\": \"ok\"\n\t},\n\t\"object\": {\n\t\t\"retailers\": [\n\t\t\t\"target\",\n\t\t\t\"bestbuy\",\n\t\t\t\"drizly\",\n\t\t\t\"cvs\",\n\t\t\t\"walgreens\"\n\t\t],\n\t\t\"rate-limit\": {\n\t\t\t\"period\": \"second\",\n\t\t\t\"count\": 1\n\t\t},\n \"feedUrls\": {\n \"drizly\": \"https://product-api.button-labs.com/preview/feed/drizly\"\n }\n\t}\n}"}],"_postman_id":"feb483c2-5afb-40f0-9280-1b72bcff6e59"},{"name":"URL → Product","id":"22987b1d-daa8-43da-8c8d-71f682971caa","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://product-api.button-labs.com/preview/product?url={URL}&key={YOUR_PRODUCT_API_KEY}","description":"

Fetch all matching Product records at the same retailer for the product identified by a supported retailer URL.

\n

Note: The response array may contain multiple items depending upon how a retailer represents multiple customizations of a single item (e.g. sizes)

\n","urlObject":{"protocol":"https","path":["preview","product"],"host":["product-api","button-labs","com"],"query":[{"description":{"content":"

A supported retailer URL to lookup

\n","type":"text/plain"},"key":"url","value":"{URL}"},{"description":{"content":"

Your Button Product API key

\n","type":"text/plain"},"key":"key","value":"{YOUR_PRODUCT_API_KEY}"}],"variable":[]}},"response":[{"id":"7ed706c1-a2b5-4c73-9f6b-49808d1b99b7","name":"Justin's Peanut Butter Cups","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://product-api.button-labs.com/preview/product?url=https://www.target.com/p/justin-s-dark-chocolate-peanut-butter-cups-4-7oz/-/A-21549971&key={YOUR_PRODUCT_API_KEY}","protocol":"https","host":["product-api","button-labs","com"],"path":["preview","product"],"query":[{"key":"url","value":"https://www.target.com/p/justin-s-dark-chocolate-peanut-butter-cups-4-7oz/-/A-21549971","description":"The supported retailer URL to lookup"},{"key":"key","value":"{YOUR_PRODUCT_API_KEY}","description":"Your Button Product API key"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"Cowboy"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Origin"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"82"},{"key":"Date","value":"Thu, 21 May 2020 16:02:43 GMT"},{"key":"Via","value":"1.1 vegur"}],"cookie":[],"responseTime":null,"body":"{\n\t\"meta\": {\n\t\t\"status\": \"ok\"\n\t},\n\t\"objects\": [\n\t\t{\n\t\t\t\"id\": \"47b67646bc79e3f4d20101160559e08cc585e626\",\n\t\t\t\"retailer\": \"target\",\n\t\t\t\"product_id\": \"21549971\",\n\t\t\t\"url\": \"https://www.target.com/p/justin-s-dark-chocolate-peanut-butter-cups-4-7oz/-/A-21549971\",\n\t\t\t\"title\": \"Justin's Dark Chocolate Peanut Butter Cups - 4.7oz\",\n\t\t\t\"description\": \"Justin's Dark Chocolate Peanut Butter Cups are just what you need for a mini dessert within arm's reach. The tasty chocolate and peanut butter treats are bite size and perfectly shareable. Individually wrapped, you can keep these out at the office or keep them at home for a family dessert. Gender: unisex.\",\n\t\t\t\"image_url\": \"https://target.scene7.com/is/image/Target/GUEST_79e2c5cb-5d9d-4a7b-b4f9-0858ee2a6ee8?wid=1000&hei=1000\",\n\t\t\t\"price\": \"4.99\",\n\t\t\t\"currency\": \"USD\",\n\t\t\t\"gtin\": \"855188003912\",\n\t\t\t\"mpn\": \"21549971\",\n\t\t\t\"sku\": null,\n\t\t\t\"category\": \"Food, Beverages & Tobacco > Food Items > Candy & Chocolate\",\n\t\t\t\"manufacturer\": \"Justin's\"\n\t\t}\n\t]\n}"}],"_postman_id":"22987b1d-daa8-43da-8c8d-71f682971caa"},{"name":"Retailer & Identifier → Product","id":"5612f506-0dae-4084-a5bb-5ce80aeb9582","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://product-api.button-labs.com/preview/product?retailer={RETAILER}&identifier={PRODUCT_ID}&key={YOUR_PRODUCT_API_KEY}","description":"

Lookup all matching product objects representing a retailer and identifier pair. Identifier can be either a sku or internal product_id.

\n

Note: The response array may contain multiple items depending upon how a retailer represents multiple customizations of a single item (e.g. sizes)

\n","urlObject":{"protocol":"https","path":["preview","product"],"host":["product-api","button-labs","com"],"query":[{"description":{"content":"

A retailer shortname, in the form of the domain of the retailer stripping the TLD, and www. E.g. target, or walmart. These can be confirmed from /preview/account.

\n","type":"text/plain"},"key":"retailer","value":"{RETAILER}"},{"description":{"content":"

The retailer-specific identifier for the product - this could be an SKU or internal product identifier.

\n","type":"text/plain"},"key":"identifier","value":"{PRODUCT_ID}"},{"description":{"content":"

Your Button Product API key

\n","type":"text/plain"},"key":"key","value":"{YOUR_PRODUCT_API_KEY}"}],"variable":[]}},"response":[{"id":"742b378e-9128-46ee-a993-3d3eb650068c","name":"Justin's Peanut Butter Cups","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://product-api.button-labs.com/preview/product?retailer=target&identifier=21549971&key={YOUR_PRODUCT_API_KEY}","protocol":"https","host":["product-api","button-labs","com"],"path":["preview","product"],"query":[{"key":"retailer","value":"target","description":"The shortname of the retailer, in the form of the domain of the retailer stripping the TLD, and `www`. E.g. `target`, or `walmart`"},{"key":"identifier","value":"21549971","description":"The retailer-specific identifier for the product - this could be an SKU or internal product identifier."},{"key":"key","value":"{YOUR_PRODUCT_API_KEY}","description":"Your Button Product API Key"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n\t\"meta\": {\n\t\t\"status\": \"ok\"\n\t},\n\t\"objects\": [\n\t\t{\n\t\t\t\"id\": \"47b67646bc79e3f4d20101160559e08cc585e626\",\n\t\t\t\"retailer\": \"target\",\n\t\t\t\"product_id\": \"21549971\",\n\t\t\t\"url\": \"https://www.target.com/p/justin-s-dark-chocolate-peanut-butter-cups-4-7oz/-/A-21549971\",\n\t\t\t\"title\": \"Justin's Dark Chocolate Peanut Butter Cups - 4.7oz\",\n\t\t\t\"description\": \"Justin's Dark Chocolate Peanut Butter Cups are just what you need for a mini dessert within arm's reach. The tasty chocolate and peanut butter treats are bite size and perfectly shareable. Individually wrapped, you can keep these out at the office or keep them at home for a family dessert. Gender: unisex.\",\n\t\t\t\"image_url\": \"https://target.scene7.com/is/image/Target/GUEST_79e2c5cb-5d9d-4a7b-b4f9-0858ee2a6ee8?wid=1000&hei=1000\",\n\t\t\t\"price\": \"4.99\",\n\t\t\t\"currency\": \"USD\",\n\t\t\t\"gtin\": \"855188003912\",\n\t\t\t\"mpn\": \"21549971\",\n\t\t\t\"sku\": null,\n\t\t\t\"category\": \"Food, Beverages & Tobacco > Food Items > Candy & Chocolate\",\n\t\t\t\"manufacturer\": \"Justin's\"\n\t\t}\n\t]\n}"}],"_postman_id":"5612f506-0dae-4084-a5bb-5ce80aeb9582"},{"name":"Search Products by GTIN","id":"071cffd4-3d07-46e4-8eee-2fedc47e34ca","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://product-api.button-labs.com/preview/product?gtin={PRODUCT_GTIN}&key={YOUR_PRODUCT_API_KEY}","description":"

Retrieve all product objects at included Retailers that match the provided gtin.

\n","urlObject":{"protocol":"https","path":["preview","product"],"host":["product-api","button-labs","com"],"query":[{"description":{"content":"

A valid product GTIN

\n","type":"text/plain"},"key":"gtin","value":"{PRODUCT_GTIN}"},{"description":{"content":"

Your Button Product API Key

\n","type":"text/plain"},"key":"key","value":"{YOUR_PRODUCT_API_KEY}"}],"variable":[]}},"response":[{"id":"77422114-cc90-402c-8437-2979a5c769f8","name":"Justin's Peanut Butter Cups","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://product-api.button-labs.com/preview/product?gtin=894455000254&key={YOUR_PRODUCT_API_KEY}","protocol":"https","host":["product-api","button-labs","com"],"path":["preview","product"],"query":[{"key":"gtin","value":"894455000254","description":"A valid product GTIN"},{"key":"key","value":"{YOUR_PRODUCT_API_KEY}","description":"Your Button Product API Key\n"}]}},"status":"OK","code":200,"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n\t\"meta\": {\n\t\t\"status\": \"ok\"\n\t},\n\t\"objects\": [\n\t\t{\n\t\t\t\"id\": \"c8e17fb43eaa5032c72d9dee3838224798aa3e32\",\n\t\t\t\"retailer\": \"luckyvitamin\",\n\t\t\t\"product_id\": \"110251\",\n\t\t\t\"url\": \"https://www.luckyvitamin.com/p-185153-justin-s-nut-butter-peanut-butter-cups-dark-chocolate-1-4-oz?site=google_base\",\n\t\t\t\"title\": \"Justin's Nut Butter - Peanut Butter Cups Dark Chocolate - 1.4 oz.\",\n\t\t\t\"description\": null,\n\t\t\t\"image_url\": \"https://www.luckyvitamin.com/images/product/xlarge/110251.jpg\",\n\t\t\t\"price\": \"2.27\",\n\t\t\t\"currency\": \"USD\",\n\t\t\t\"gtin\": \"00894455000254\",\n\t\t\t\"mpn\": \"894455000254\",\n\t\t\t\"category\": \"Food, Beverages & Tobacco > Food Items\",\n\t\t\t\"manufacturer\": \"Justin's\"\n\t\t},\n\t\t{\n\t\t\t\"id\": \"ed14bf7a4a0e8e2e897caa322b44acfcbaf96218\",\n\t\t\t\"retailer\": \"target\",\n\t\t\t\"product_id\": \"14709595\",\n\t\t\t\"url\": \"https://www.target.com/p/justin-s-organic-dark-chocolate-peanut-butter-cups-1-4oz/-/A-14709595\",\n\t\t\t\"title\": \"Justin's Organic Dark Chocolate Peanut Butter Cups - 1.4oz\",\n\t\t\t\"description\": \"Dark Chocolate Peanut Butter Cup: If you’re reading this then you deserve a peanut butter cup. Also, if you’re standing or sitting right now you deserve a peanut butter cup. You definitely earned one if you’re in a grocery store. Coffee shop – yes. At work? You get two. Unmentioned but still worthy are adults, children, people with or without hair and of course, breathers. Sincerely, Justin Gender: unisex.\",\n\t\t\t\"image_url\": \"https://target.scene7.com/is/image/Target/GUEST_5494b3b7-c074-439a-aee6-dbfa0a87b5ba?wid=1000&hei=1000\",\n\t\t\t\"price\": \"2.19\",\n\t\t\t\"currency\": \"USD\",\n\t\t\t\"gtin\": \"894455000254\",\n\t\t\t\"mpn\": \"14709595\",\n\t\t\t\"category\": \"Food, Beverages & Tobacco > Food Items > Candy & Chocolate\",\n\t\t\t\"manufacturer\": \"Justin's\"\n\t\t}\n\t]\n}"}],"_postman_id":"071cffd4-3d07-46e4-8eee-2fedc47e34ca"},{"name":"List all Product Feeds","id":"240b113e-a695-4ff2-8b19-27491403c1d3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://product-api.button-labs.com/preview/feeds?key={YOUR_PRODUCT_API_KEY}","description":"

List all Product Feed URLs available for your account.

\n

Format:\nretailer: url

\n","urlObject":{"protocol":"https","path":["preview","feeds"],"host":["product-api","button-labs","com"],"query":[{"key":"key","value":"{YOUR_PRODUCT_API_KEY}"}],"variable":[]}},"response":[{"id":"e9179746-71c0-47df-9772-d6c6178e6ca9","name":"List all Product Feeds","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://product-api.button-labs.com/preview/feeds?key={YOUR_PRODUCT_API_KEY}","protocol":"https","host":["product-api","button-labs","com"],"path":["preview","feeds"],"query":[{"key":"key","value":"{YOUR_PRODUCT_API_KEY}"}]}},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"{\n\t\"meta\": {\n\t\t\"status\": \"ok\"\n\t},\n\t\"object\": {\n \"retailer1\": \"https://product-api.button-labs.com/..../retailer1\",\n \"retailer2\": \"https://product-api.button-labs.com/..../retailer2\"\n }\n}"}],"_postman_id":"240b113e-a695-4ff2-8b19-27491403c1d3"},{"name":"Get Product Feed","id":"8cb67c5b-457e-448f-8f77-91034a1869c9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://product-api.button-labs.com/preview/feed/:retailer?key={YOUR_PRODUCT_API_KEY}","description":"

Raw Product Feeds are available for select retailers as CSVs.

\n

The structure ~matches the Product object with some flattening for the CSV use-case.

\n

All Product Feeds return a stream of text/csv for a valid retailer.

\n

You can find all feed URLs available for your account by calling /preview/feeds

\n

Fields

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldValue
idThe Button ID for this retailer product
retailerRetailer identifier (the root of the retailer domain, excluding tld & www)
product_idThe retailer's internal ID for this product - the SKU
urlThe public URL for this product
titleThe retailer's displayed name for the product
descriptionThe retailer's on-site description for the product
image_urlProduct display image
categoryRetailer's unstructured category (Note: Categories will likely change ahead of general availability)
manufacturerThe name of the manufacturer of this product
pricePrice (string)
currencyCurrency code for the price
msrpThe manufacturer-recommended price for this item
gtinThe GS1 GTIN for this product
mpnThe manufacturer's unique ID for this product
sizeThe description of the item size
colorThe color of the item
genderThe manufacturer described gender
in_stockStock status - [\"Y\", \"N\", null]
\n
","urlObject":{"protocol":"https","path":["preview","feed",":retailer"],"host":["product-api","button-labs","com"],"query":[{"description":{"content":"

If you don't know your API key, contact your Button representative.

\n","type":"text/plain"},"key":"key","value":"{YOUR_PRODUCT_API_KEY}"}],"variable":[{"description":{"content":"

e.g. apple. Available feeds can be fetched from /previews/feeds

\n","type":"text/plain"},"type":"string","value":"{RETAILER_NAME}","key":"retailer"}]}},"response":[{"id":"349d5742-b2b2-4975-a463-524fa2f11501","name":"Get Product Feeds","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://product-api.button-labs.com/preview/feed/:retailer?key={YOUR_PREVIEW_API_KEY}","protocol":"https","host":["product-api","button-labs","com"],"path":["preview","feed",":retailer"],"query":[{"key":"key","value":"{YOUR_PREVIEW_API_KEY}"}],"variable":[{"key":"retailer","value":"{RETAILER_NAME}","description":"e.g. `apple`. Available feeds can be fetched from `/previews/feeds`"}]}},"_postman_previewlanguage":null,"header":null,"cookie":[],"responseTime":null,"body":"Binary stream of CSV file"}],"_postman_id":"8cb67c5b-457e-448f-8f77-91034a1869c9"}],"event":[{"listen":"prerequest","script":{"id":"a9321724-d30f-4eee-bff3-992b75d17d1e","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"7fbba154-4f82-4b03-a2fc-d42894abac91","type":"text/javascript","exec":[""]}}],"variable":[{"key":"product_url","value":"https://www.target.com/p/justin-s-dark-chocolate-peanut-butter-cups-4-7oz/-/A-21549971"},{"key":"product_id","value":"21549971"},{"key":"retailer","value":"target"}]}