Developer API

Last updated October 2026

CheckBeforeYouShop tracks what dozens of shopping portals pay at each store - cashback, airline miles, and card points - with rate history and verdicts. The same data powers this public JSON API. It's free to use with attribution, read-only, and CORS-open, so browser apps and AI agents can call it directly.

Base URL

https://checkbeforeyoushop.com

Response shape

Every endpoint returns the same envelope:

{
  "data": { ... },              // the payload
  "data_as_of": "2026-07-17T…", // freshness (ISO 8601)
  "source": "CheckBeforeYouShop",
  "attribution": "Data from CheckBeforeYouShop …",
  "disclosure": "Rates are read from each portal's pages …"
}

Rates are points-native: each is returned in its own unit (pct_cash, miles_per_dollar, points_per_dollar, flat_cash, …) with a human rate_display. We never convert miles to a dollar value for you. Where a portal has a live outbound link, store responses include a go_url.

Every rate also carries a rate_kind, and the two kinds are not comparable:

earn_rate: a return on what you spend (8%, 3 mi/$). This is what a store-vs-store or portal-vs-portal comparison should rank on.
one_time_bonus: a fixed payment for a single qualifying purchase (11,200 miles, $150). It does not scale with spend, usually pays once per account, and often requires a new subscription or service. Ranking it against an earn rate by raw number is always wrong: 11,200 is not "bigger than" 3.

Endpoints

Method	Path	Returns
`GET`	`/api/v1/search.json?q=nike`	Resolve a store or portal name to its page + slug.
`GET`	`/api/v1/merchants/{slug}.json`	Every portal’s live rate for one store, the best rate per unit, and a verdict. The flagship endpoint.
`GET`	`/api/v1/portals.json`	The tracked-portal directory: currency paid, stores tracked, data freshness.
`GET`	`/api/v1/portals/{portal}.json`	One portal’s profile plus its current top rates.
`GET`	`/api/v1/highs.json`	Rates at or near the highest we have recorded right now. Earn rates are listed first; one-time bonuses follow (check rate_kind).

Example

curl https://checkbeforeyoushop.com/api/v1/merchants/nike.json

MCP server (for AI assistants)

The same data is available as a read-only Model Context Protocol server, so AI assistants (ChatGPT, Claude, Perplexity) can call it as a live tool: the cross-portal "which portal pays the most at store X" answer that a single-portal cashback app can't give. No auth, stateless streamable HTTP; add it by URL:

https://checkbeforeyoushop.com/mcp

Read-only tools, each returning the same attribution + data_as_of envelope:

compare_portal_rates: every portal's rate for a store, best-per-unit, + verdict
get_best_rate · get_rate_history · get_portal
search_stores · list_signup_bonuses · get_best_play (stacking)

History window: get_rate_history returns the last 21 days of raw changes. The verdict on compare_portal_rates and the REST store response uses our full recorded archive. get_best_rate returns a current rate without a verdict. These MCP tools do not return structured percentile or highest-yet fields. Need deeper raw history? Get in touch.

Choose a rewards program

Collect Delta SkyMiles? Ask your assistant to show the Delta SkyMiles Shopping row for the store, even when another program has a higher miles-per-dollar rate. The row is in all_rates; best_per_unit only lists the leader for each unit group. A missing Delta row means no tracked Delta rate was returned for that store.

Check the resolved store and market, especially for names with regional listings. For freshness, use that row's last_confirmed_at and is_stale. The response's data_as_of is the newest confirmation anywhere in the store response and may be newer than the program you asked about.

Examples on GitHub

The public developer kit includes the REST API specification, MCP configuration examples, and a Python example that can show one program's rates. The API is hosted here; the kit helps you build with it.

Fair use

Free with attribution: credit CheckBeforeYouShop and link each item's page_url.
Responses are edge-cached; please cache on your side and don't hammer the endpoints.
Rates change and can go stale: surface data_as_of and the disclosure, and send users to the portal to confirm before they shop.

Building an AI shopping agent? Point it at the MCP server above - that's the whole integration, and it covers cashback and airline miles across every portal we track.