Getting Started with the Product Atlas API

The Product Atlas API is a read-only API that gives you product details and
attributes, across a curated set of retailers, using familiar field names and
identifiers. This page will get you making authenticated requests.

Base URL

https://atlas.usebutton.com/v1

Every endpoint in this reference is relative to that base URL. All requests
and responses are JSON.

Getting your API key

Product Atlas API keys are issued by your Button Partnerships contact and are
scoped to your organization. Self-serve key creation isn't available yet, so
reach out to your Button representative, or [email protected], to get
started.

Before your key is activated, you'll be asked to accept Button's Product
Atlas API Terms of Use as part of onboarding.

❗️
Keep your API key private

Only call the Product Atlas API from a server you control. Don't embed your
key in a mobile app or public webpage, and don't commit it to source control.

Authentication

Send your API key on every request, using either header:

Authorization: Bearer YOUR_API_KEY

X-Api-Key: YOUR_API_KEY

A missing or invalid key returns 401. A valid key that isn't entitled to
the request (for example, a retailer your organization isn't granted access
to) returns 403.

Make your first request

curl https://atlas.usebutton.com/v1/retailers \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "retailers": [
    { "slug": "amazon", "name": "Amazon" },
    { "slug": "walmart", "name": "Walmart" }
  ]
}

This list is scoped to your organization and can change over time, so treat
it as the live source of truth rather than hard-coding retailer slugs. See
Retailer Coverage for more.

Data freshness and normalization

Field values are not yet fully normalized. The Product Atlas API is
launching ahead of a full catalog normalization effort, so field completeness
and formatting (casing, units, category taxonomy) currently varies by
retailer. Use last_updated on a product as the freshness signal — don't
assume a fixed refresh interval.

Fields a retailer didn't provide are omitted from the response entirely,
rather than returned as null or an empty string.

Rate limits

Requests are rate-limited per organization. If you exceed the limit, you'll
get a 429 with a Retry-After header telling you how many seconds to wait
before retrying.

Exact request limits are still being finalized ahead of general
availability. Build your integration to respect Retry-After rather than
assuming a fixed number, and check with your Button representative for
current guidance.

Errors

Every error response shares one shape:

{
  "error": {
    "code": "not_found",
    "message": "product not found"
  }
}

code is a stable, machine-readable value — branch your error handling on
code, not on message, since the wording of message may change.

HTTP status	`code`	Meaning
`400`	`bad_request`	The request was malformed: a missing/invalid parameter, an unknown retailer slug, or a batch over the size limit.
`401`	`unauthorized`	The API key is missing or invalid.
`403`	`forbidden`	The key is valid, but not entitled to this request.
`404`	`not_found`	No matching product.
`429`	`rate_limited`	You're over your rate limit. Check `Retry-After`.
`500`	`internal_error`	Something went wrong on Button's side.
`502` / `504`	`upstream_error`	Button's internal catalog returned an error or timed out.

Getting help

Contact your Button account representative, or [email protected], for
help integrating.