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.
curl "https://atlas.usebutton.com/v1/products?url=https%3A%2F%2Fwww.amazon.com%2Fdp%2FB08N5WRWNW" \
-H "Authorization: Bearer YOUR_API_KEY"{
"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.
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:
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 — 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:
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:
curl "https://atlas.usebutton.com/v1/products?category=Electronics&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"{
"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. 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 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
for a note on data freshness and normalization before you build assumptions
around specific field values.