---
updatedAt: 2026-09-09T17:06:53.000Z
---

Fetch the complete documentation index at: https://developer.usebutton.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Looking Up Products

There are three ways to look up a product. Pick whichever matches what you
already have on hand.

## By product URL

If you have a link to a retailer's product page — for example, a creator
pasted one into your app — send it straight through. This is the fastest way
to turn a pasted link into a product tile with no manual data entry.

```shell
curl "https://atlas.usebutton.com/v1/products?url=https%3A%2F%2Fwww.amazon.com%2Fdp%2FB08N5WRWNW" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "retailer": "amazon",
  "retailer_name": "Amazon",
  "product_id": "B08N5WRWNW",
  "title": "Echo Dot (4th Gen)",
  "price": 49.99,
  "currency": "USD",
  "availability": "in_stock",
  "product_url": "https://www.amazon.com/dp/B08N5WRWNW",
  "last_updated": "2026-07-20T12:04:33Z"
}
```

URL-encode the `url` parameter. If the URL doesn't resolve to a product in
the catalog, you'll get a `404`.

You don't need to identify the retailer yourself — Product Atlas resolves
that server-side. If your own code wants to know the retailer before calling
the API (to pick a UI, for example), see
[Mapping a URL to a retailer](./retailer-coverage.md#mapping-a-url-to-a-retailer).

## By retailer and product ID

If you already know which retailer a product is on and its ID there — an
Amazon ASIN, a Walmart item ID, or another retailer's own SKU-style
identifier — look it up directly:

```shell
curl https://atlas.usebutton.com/v1/products/amazon/B08N5WRWNW \
  -H "Authorization: Bearer YOUR_API_KEY"
```

This returns the same product shape as a URL lookup. `retailer` must be one
of the slugs from [`GET /v1/retailers`](./retailer-coverage.md) — don't guess
at or hard-code a slug.

## By GTIN

If you have a GTIN (a UPC, EAN, or similar barcode number) rather than a
retailer-specific ID, use it directly:

```shell
curl "https://atlas.usebutton.com/v1/products?gtin=012345678905" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

You can optionally add `&retailer=amazon` to scope the lookup to one
retailer; if the product resolves to a different retailer, you'll get a
`404` rather than a result from the unscoped retailer.

`gtin` and `url` are mutually exclusive — provide exactly one identifier per
request.

## Browsing by category

To browse rather than look up a specific product, query by category and page
through the results:

```shell
curl "https://atlas.usebutton.com/v1/products?category=Electronics&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json
{
  "products": [ ... ],
  "meta": {
    "next_cursor": "MjA",
    "count": 20
  }
}
```

Pass `next_cursor` back as the `cursor` parameter to get the next page; an
empty `next_cursor` means there are no more results. Note that `count` can be
smaller than `limit` even when more results exist — some items on a page may
be filtered out if your organization isn't entitled to that retailer — so
always page based on `next_cursor`, not on whether `count` reached `limit`.

`category` can't be combined with `gtin` or `url`.

## Looking up several products at once

To fetch up to 50 products in one call, see `POST /v1/products/batch-lookup`
in the [API reference](../api/openapi.yaml). Each item you send, and each
error, echoes its `retailer` and `product_id` so you can correlate results
back to your request — a batch with some items not found still returns
`200`, with those items listed under `errors` and a `meta` block
(`total`/`found`/`not_found`/`other_errors`) summarizing the outcome.

## What you get back

All four lookup paths return the same `Product` shape: a fixed, external
field allow-list (title, price, images, identifiers, and so on) — see the
[API reference](../api/openapi.yaml) for the full field list. Only fields on
that list are ever returned; nothing else in Button's internal catalog is
exposed. Read [Getting Started](./getting-started.md#data-freshness-and-normalization)
for a note on data freshness and normalization before you build assumptions
around specific field values.