Developers

Search Amazon, Walmart, Target, Best Buy and more, build carts and checkouts, and track orders from your own code. The REST API and the MCP server do exactly what the website does, with the same keys.

API keys

A key acts as your Supraise account: it can see your orders, saved addresses and gift wallet balance. Keep it secret and revoke it if it leaks.

Gift wallet. Add balance on supraise.com/shop (card, Apple Pay or Google Pay).GET /account returns the balance and a top_up_url. Checkouts and surprise plans are paid from the wallet first; when it covers the total the buyer pays in one click on continue_url, otherwise they pay the total by card. Money never moves through the API itself.

Basics

Base URL: https://supraise.com/api/v1 (production: https://supraise.com/api/v1). Requests and responses are JSON; prices are USD.

Authenticate with Authorization: Bearer <your key>. OAuth access tokens issued to MCP clients work too. Searching and reading products needs no key; carts, checkouts, orders, account and plans do.

Nothing is bought without payment. Creating a checkout charges nothing: it returns a continue_url where the buyer reviews the order and pays (gift wallet, card, Apple Pay or Google Pay). The retailer order is placed only after payment; then GET /checkouts/{id} shows the order ids.

Quickstart

1. Search (no key needed):

curl "https://supraise.com/api/v1/products/search?q=cast+iron+skillet&limit=3"

2. Pick a variant: take offers[0].variant_id from a result, or call GET /products/{id}?options=Size:10 and use selected_variant.id.

3. Create a checkout and send the buyer to continue_url to pay:

curl -X POST "https://supraise.com/api/v1/checkouts" \
  -H "Authorization: Bearer $SUPRAISE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{ "variant_id": "VARIANT_ID", "quantity": 1 }],
    "shipping_address": {
      "first_name": "Ada", "last_name": "Lovelace",
      "address_line1": "1 Main St", "city": "Austin", "state": "TX",
      "postal_code": "78701", "country": "US", "phone_number": "5125550100"
    }
  }'

4. After payment, check the status:

curl "https://supraise.com/api/v1/checkouts/CHECKOUT_ID" -H "Authorization: Bearer $SUPRAISE_API_KEY"

Endpoints

Endpoint	Key	What it does
GET /products/search ?q=trail+running+shoes&max_price=120&retailers=amazon,target&limit=5	optional	Search products across Amazon, Walmart, Target, Best Buy and more. (search_catalog)
GET /products ?ids=p_abc,p_def	optional	Fetch products you already found, by id. (lookup_catalog)
GET /products/{id} ?options=Size:10,Color:Black	optional	One product with options and variants; pass options to pick the variant_id. (get_product)
POST /carts {"lines":[{"variant_id":"p_abc.0","quantity":1}]}	required	Create a cart from variant ids and quantities. (create_cart)
GET /carts/{id}	required	Get a cart. (get_cart)
PATCH /carts/{id} {"lines":[{"variant_id":"p_abc.0","quantity":2}]}	required	Add or change lines (quantity 0 removes a line). (update_cart)
POST /checkouts {"cart_id":"cart_...","shipping_address":{...}}	required	Create a checkout from line_items and/or a cart_id. Returns continue_url, where the buyer reviews and pays. (create_checkout)
GET /checkouts/{id}	required	Checkout status, totals and order ids once paid. (get_checkout)
PATCH /checkouts/{id} {"email":"ada@example.com"}	required	Change an open checkout: quantities, remove_variant_ids, email, shipping_address. (update_checkout)
GET /orders ?query=skillet&status=shipped&limit=10	required	Your orders, newest first: purchases and surprise gifts. (search_orders)
GET /account	required	Saved addresses, gift wallet balance and surprise plans. (get_account)
POST /plans {"recipient":"self","budget":25,"cadence":"monthly","interests":["coffee"]}	required	Set up a recurring surprise gift. (create_surprise_plan)
GET /tools	optional	Every tool with its JSON input schema.
POST /tools/{name}	per tool	Call any tool by name with its arguments as the JSON body. Handy for agents.

Paths are relative to /api/v1. Request bodies use the same fields as the tool input schemas (GET /tools). Responses are the same objects the MCP tools return. GET /api/v1 lists everything as JSON.

Errors and rate limits

Errors always look like this:

{ "error": { "code": "invalid_request", "message": "shipping_address is missing: city" } }

400 invalid_request, invalid_json: fix the request; the message says what is wrong.
401 authentication_required or invalid_token: missing, wrong or revoked key.
404 not_found: unknown endpoint, or a cart, checkout or product that is not yours or does not exist.
429 rate_limited: wait for the seconds in the Retry-After header.
500 internal_error: our side; retry shortly.

Each key can make 120 requests per minute. Requests without a key are limited per IP address.

MCP

The MCP server at https://supraise.com/api/mcp exposes the same 12 tools. It works in Claude, ChatGPT, Cursor and any client that speaks MCP over streamable HTTP. Add it as a custom connector and sign in to Supraise when asked (OAuth), or send the same API key as a Bearer header:

{
  "mcpServers": {
    "supraise": {
      "url": "https://supraise.com/api/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Without a key, search and product tools still work; the rest ask you to sign in.