# Look up a product by UPC, ASIN, URL or model number > GET /v1/products returns the product record for any barcode, ASIN, model number, MPN, URL or name, with a match object showing how each identifier matched. *Source: https://shopsavvy.com/data/documentation/product-details* · Part of the [ShopSavvy Data API documentation](https://shopsavvy.com/data/documentation.md) --- **Cost:** 1 credit per product found. Identifiers that match nothing cost nothing. 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 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 - Product Name - URL at any Retailer - ShopSavvy Product ID ## Examples **Example with barcodes:** ```bash curl -X GET "https://api.shopsavvy.com/v1/products?ids=611247373064,611247369449" \ -H "Authorization: Bearer ss_live_your_api_key_here" ``` **Example with product name:** ```bash curl -X GET "https://api.shopsavvy.com/v1/products?ids=iPhone%2015%20Pro" \ -H "Authorization: Bearer ss_live_your_api_key_here" ``` **Note:** When using a product name, the API uses full-text search to find the best matching product based on relevance and offer availability. ## How Identifiers Are Matched Each identifier is tried against these fields, in order, and the first field that matches wins: 1. **Barcode** (UPC / EAN / ISBN / GTIN). A full-length barcode (UPC-A, EAN-13, ISBN-13, GTIN-14) with a valid check digit is looked up **only** as a barcode (and a ShopSavvy Product ID). It is never re-interpreted as a model number, so a UPC can't come back as an unrelated product whose model number happens to be the same digits. 2. **ShopSavvy Product ID** 3. **Model number**, then **MPN** (skipped for inputs that look like product names, i.e. contain spaces) 4. **Amazon ASIN** 5. **Product URL** at any retailer (tracking parameters such as `utm_*` are stripped before matching) 6. **Product name** (full-text search, a best guess) Some identifiers are shared by more than one product in the catalog, such as a barcode a manufacturer reused or a model number used across several listings. When that happens the API returns the product with the most evidence behind it (the most verified offers on file, then the most watched), and the result is the same every time you ask. Every product in a response carries a `match` object that tells you which identifier produced it and how: ```json "match": { "identifier": "611247373064", "by": "barcode", "candidates": 1 } ``` | Field | Description | |-------|-------------| | `identifier` | The identifier exactly as you sent it. Use this to line results up with your request, because identifiers that match nothing are left out of `data`. | | `by` | Which field matched: `barcode`, `shopsavvy_id`, `asin`, `url`, `model`, `mpn`, or `name`. Everything except `name` is an exact match. Treat `name` as low confidence. | | `candidates` | How many products matched on that field. More than `1` means the identifier is shared and the best-evidence product was chosen. Always `1` for `name`. | ## Response Format The response will be a JSON object with success status, data array, and metadata including credits used. Products will each have the following fields. (Note: not all fields are available on all products). | Field | Description | |-------|-------------| | `title` | The name of the product. | | `title_short` | A shorter, human-friendly version of the title (when available). | | `slug` | URL-friendly slug for 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. | | `identifiers` | All known identifiers for the product (barcode, amazon, walmart, bestbuy, newegg, etc.). | | `description` | Product description text (single best available description). | | `categories` | Array of category path strings. | | `attributes` | Product specifications as a flat object (e.g., `{"Color": "Black", "Weight": "250g"}`). | | `rating` | Aggregated customer rating with `value` (out of 5) and `count` (total reviews). | | `score` | Expert quality scores on a **0-1 scale**: `overall`, `customer`, `professional`, plus an `aspects` object of per-aspect scores keyed by free-form aspect names drawn from the product's professional reviews (e.g. `value`, `features`, `reliability`, `quality` — the set varies per product). Only populated fields are included. Multiply by 10 or 100 if you want to display a /10 or /100 score. | | `keywords` | Array of relevant search keywords for the product. | | `match` | How your identifier matched this product: `identifier`, `by`, and `candidates` (see [How Identifiers Are Matched](https://shopsavvy.com/data/documentation/product-details#how-identifiers-are-matched)). Present on every endpoint that takes identifiers. | All response `meta` objects now include a `request_id` field — a unique identifier for every API request. Include this in any support inquiries. **Error Responses** include both a human-readable `error` string and a structured `error_detail` object with `code`, `message`, `action` (what to do), and `docs_url` (link to relevant documentation). ## Example Response ```json { "success": true, "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": "products/3ONn300xybP3y66ibqc1", "barcode": 611247373064, "amazon": "B07G14HTBZ", "mpn": "5000200237", "images": [ "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 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": "products/DrKWneG0MpFlZpwZXNYa", "barcode": 611247369449, "amazon": "B0788F3R8X", "mpn": "5000197492", "images": [ "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" ] } ], "meta": { "credits_used": 2, "credits_remaining": 998, "rate_limit_remaining": 58 } } ```