Skip to content
Waltrack
Documentation

API documentation

Track Walmart products and read their price history from your code with the REST API, or from your AI assistant with the MCP server. One API key works for both, and for the Chrome extension.

Quickstart

  1. 1Create an account and an API key in your dashboard (it starts with wal_). Confirming your email adds 1500 free credits.
  2. 2Send an item ID or a Walmart link to POST /products. The price is checked right away and the product is checked again on its schedule.
  3. 3Read GET /products/{id} for the latest price and the price history.
1. Track a product
curl -X POST "https://www.waltrack.dev/api/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product":"5129929197","marketplace":"com","target_price":70,"wait":true}'
201 Created
{
  "product_id": "8f0b3c7e-2a4d-4e51-9c1a-6d2f1b9e7a30",
  "item_id": "5129929197",
  "marketplace": "com",
  "url": "https://www.walmart.com/ip/5129929197",
  "title": "Wireless Earbuds, Bluetooth 5.3, Noise Cancelling",
  "image": "https://i5.walmartimages.com/seo/…jpeg",
  "brand": "Example Audio",
  "currency": "USD",
  "price": 79.99,
  "first_price": 99.99,
  "lowest_price": 74.5,
  "highest_price": 99.99,
  "in_stock": true,
  "stock": "In stock",
  "coupon": null,
  "seller": "Walmart.com",
  "best_sellers_rank": null,
  "target_price": 70,
  "alert_on_drop": true,
  "interval_minutes": 1440,
  "status": "active",
  "last_error": null,
  "found_on": [],
  "checking": false,
  "last_checked_at": "2026-11-03T08:00:12.441Z",
  "next_check_at": "2026-11-04T08:00:12.441Z",
  "created_at": "2026-10-01T09:30:31.120Z"
}
2. Read its price history
curl -G "https://www.waltrack.dev/api/v1/products/8f0b3c7e-2a4d-4e51-9c1a-6d2f1b9e7a30" \
  --data-urlencode "days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK
{
  "product_id": "8f0b3c7e-2a4d-4e51-9c1a-6d2f1b9e7a30",
  "item_id": "5129929197",
  "marketplace": "com",
  "url": "https://www.walmart.com/ip/5129929197",
  "title": "Wireless Earbuds, Bluetooth 5.3, Noise Cancelling",
  "image": "https://i5.walmartimages.com/seo/…jpeg",
  "brand": "Example Audio",
  "currency": "USD",
  "price": 79.99,
  "first_price": 99.99,
  "lowest_price": 74.5,
  "highest_price": 99.99,
  "in_stock": true,
  "stock": "In stock",
  "coupon": null,
  "seller": "Walmart.com",
  "best_sellers_rank": null,
  "target_price": 70,
  "alert_on_drop": true,
  "interval_minutes": 1440,
  "status": "active",
  "last_error": null,
  "found_on": [],
  "checking": false,
  "last_checked_at": "2026-11-03T08:00:12.441Z",
  "next_check_at": "2026-11-04T08:00:12.441Z",
  "created_at": "2026-10-01T09:30:31.120Z",
  "history": [
    {
      "price": 99.99,
      "in_stock": true,
      "coupon": null,
      "seller": "Walmart.com",
      "checked_at": "2026-10-01T09:30:35.002Z"
    },
    {
      "price": 74.5,
      "in_stock": true,
      "coupon": null,
      "seller": "Example Audio Store",
      "checked_at": "2026-10-24T08:00:10.913Z"
    },
    {
      "price": 79.99,
      "in_stock": true,
      "coupon": null,
      "seller": "Walmart.com",
      "checked_at": "2026-11-03T08:00:12.441Z"
    }
  ]
}

Authentication

Every request carries your personal API key as a Bearer token. Create one key per tool or script in your dashboard: the key is shown once, and revoking it stops it right away. Keep keys on your server, never in browser code.

Header
Authorization: Bearer YOUR_API_KEY

Base URL: https://www.waltrack.dev/api/v1. Requests and responses are JSON. A missing or invalid key returns 401 with the code unauthorized.

Endpoints

Parameters, responses and code samples for each endpoint are in the API reference, where you can also try requests with your key.

Product object

Every product answer has the same fields: see the Product model in the API reference. Here are the values two of them can take.

last_error
CodeMeaning
email_not_verifiedThe account's email isn't confirmed yet, so it has no credits; the check runs as soon as it is.
insufficient_creditsThe last check was skipped for lack of credits; it's retried every 6 hours.
store_unavailableWalmart couldn't be read at the last check (refunded); retried within 30 minutes.
product_not_foundThe item ID has no page on Walmart (refunded).
Marketplaces
marketplaceStoreCurrency
comwalmart.com (United States)USD

Product states

Checks run in the background, so a product's fields tell where it stands. Test them in this order: the first match is the state the app and the extension show as a badge.

States
StateWhenWhat to do
Checkingchecking is trueA check is due or running. Poll GET /products/{id} every few seconds, or pass wait.
Pausedstatus is "paused"Not checked, not charged. PATCH paused: false to resume.
Confirm your emaillast_error is "email_not_verified"The free credits come with the email confirmation; checks start right after it.
Waiting for creditslast_error is "insufficient_credits"The balance is empty; the check runs again by itself once credits are added (manage_url).
Not found on Walmartlast_error is "product_not_found"No page for this item ID on Walmart (refunded).
Retrying soonlast_error is "store_unavailable"Walmart couldn't be read (refunded). Retried automatically; nothing to do.
Queuedlast_checked_at is nullAdded, first check not done yet.
Out of stockin_stock is falseChecked, but no offer: price is null. With alert_on_drop, the owner gets an email when it's back.
In stockin_stock is trueChecked, with an offer at price (in currency).
filter on GET /products and list_products
filterProducts
allEvery tracked product (default).
dropsCheaper now than when the product was added.
targetAt or below its target price.
out_of_stockNo offer at the last check.
attentionThe last check didn't go through (last_error is set): no credits, not found or Walmart unavailable.
pausedPaused by you: not checked, not charged.

Recipes

Common integrations, in JavaScript (Node 18+). The first one defines api(method, path, body), a small fetch wrapper the others reuse. Keep the key on your server.

Track a product and get its price in one call

wait: true answers once the first check is done (up to 45 seconds). If it took longer, checking is still true: read the product again a bit later.

JavaScript
async function api(method, path, body) {
  const res = await fetch(`https://www.waltrack.dev/api/v1${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.WALTRACK_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: body && JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
  return data;
}

const product = await api("POST", "/products", { product: "https://www.walmart.com/ip/5129929197", wait: true });
console.log(product.title, product.price, product.currency);

Send a daily digest of price drops

The filter parameter gives the same lists as the app's tabs. Run this once a day: it reads your watchlist, nothing is charged.

JavaScript
const { products } = await api("GET", "/products?filter=drops&limit=100");
for (const item of products) {
  const change = (item.price - item.first_price) / item.first_price;
  console.log(`${item.title}: ${item.price} ${item.currency} (${(change * 100).toFixed(1)} %)`);
}

Find products that need you

filter=attention lists the products whose last check didn't go through. Only waiting for credits and not found need an action; Walmart errors retry by themselves.

JavaScript
const { products } = await api("GET", "/products?filter=attention");
const blocked = products.filter((item) => item.last_error !== "store_unavailable");

Errors

Errors use the HTTP status and a JSON body with a stable code to branch on, and a message to show or log.

403 Forbidden
{
  "error": {
    "code": "product_limit",
    "message": "You've reached your plan's product limit. The free plan tracks up to 50 products."
  }
}
Error codes
HTTPCodeWhen
400invalid_productproduct is neither a Walmart item ID (the number at the end of a walmart.com/ip/ link) nor a Walmart product link, or item_id isn't a Walmart item ID (the number at the end of a walmart.com/ip/ link).
400unsupported_marketplaceThe link is from a Walmart site other than walmart.com.
400invalid_optionA setting isn't valid: marketplace (com), filter, interval_minutes (5, 30, 60, 360, 720, 1440), target_price, alert_on_drop or paused. Also when the body isn't a JSON object, a required argument is missing, or the product to check is paused.
401unauthorizedThe API key is missing, revoked or invalid.
402insufficient_creditsReading Walmart now costs 1 credit and the balance is empty.
402email_not_verifiedThe account's email isn't confirmed yet, so it has no credits to read Walmart with.
403paid_optionChecks faster than daily need a plan or a credit pack: every 60 minutes with a pack or Starter, 30 with Pro, 5 with Business.
403product_limitThe account tracks as many products as its plan allows (50 on the free plan).
404not_foundNo tracked product with this id on your account, or no such endpoint.
404product_not_foundWalmart has no product for this item ID. Refunded.
405method_not_allowedThe endpoint doesn't take this HTTP method; the Allow header lists the ones it does.
429rate_limitedMore than 30 searches or 600 history reads in an hour, too many reads of Walmart at once, or too many different products read today: 200 a day on the free plan, 1,000 with a credit pack, then 1,000 with Starter, 3,000 with Pro, 10,000 with Business. Histories and new watchlist entries count, once per product; your watchlist and the products already read today stay available. Retry later, or after midnight UTC for the daily limit.
500genericUnexpected error on our side. Retry in a moment.
502store_unavailableWalmart couldn't be read right now (GET /search). Nothing is charged; retry in a moment.

Billing & limits

  • Each price check of a tracked product costs 1 credit; a product checked daily uses about 30 credits a month. The first check, when a product is added, counts too. A check that fails on Walmart's side is refunded and retried.
  • Without credits, checks pause (nothing is charged) and resume once credits are back. The product's last_error is then insufficient_credits.
  • The free plan tracks 50 products, checked daily (interval_minutes 1440). A credit pack or a plan unlocks more products. Checks faster than daily need a plan or a credit pack: every 60 minutes with a pack or Starter, 30 with Pro, 5 with Business. Accepted values: 5, 30, 60, 360, 720, 1440.
  • Searching Walmart (GET /search) is free, limited to 30 searches per hour per account. The history of any item ID (GET /history) is free too, limited to 600 reads per hour. 429 beyond.

MCP server

The MCP server lets Claude, ChatGPT, Cursor or any MCP client track products and read price histories for you. It uses Streamable HTTP with stateless JSON responses at https://www.waltrack.dev/api/mcp. Clients that support OAuth, like Claude and ChatGPT, only need this URL: you sign in and allow them once. Others take an API key in the Authorization header, or ?key= for clients that only accept a URL. Your dashboard has one-click setups for each client.

Claude Code
claude mcp add --transport http waltrack https://www.waltrack.dev/api/mcp --header "Authorization: Bearer YOUR_API_KEY"
mcpServers config
{
  "mcpServers": {
    "waltrack": {
      "url": "https://www.waltrack.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Tools

get_accountRead-only

Current plan, remaining credits and how many products are tracked. Each price check of a tracked product costs 1 credit; a product checked daily uses about 30 credits a month.

Arguments
none
Returns
plan, plan_name, credits, renews_at, products, product_limit, fastest_interval_minutes, monthly_credits, manage_url
search_walmartRead-onlyReads Walmart

Search Walmart by keywords to find products and their item ID, with the price, rating and reviews shown in the results. Free, limited to 30 searches per hour.

Arguments
query, marketplace?
Returns
results: item_id, title, image, price, currency, rating, reviews_count
track_productChanges the watchlistReads Walmart

Add a Walmart product (item ID, link or short link) to the watchlist and check its price now (waits up to 45 seconds for the check). Each price check of a tracked product costs 1 credit; a product checked daily uses about 30 credits a month. Returns the current price; checking is still true if the check took longer, then read it later with get_price_history.

Arguments
product, marketplace?, target_price?, interval_minutes?
Returns
the tracked product: product_id, title, price, currency, lowest_price…
list_productsRead-only

The watchlist, newest first, with each product's latest price, lowest and highest price and recent trend. Use filter for questions like "what dropped?" (drops), "what reached my target?" (target), "what's out of stock?" (out_of_stock) or "anything wrong?" (attention).

Arguments
item_id?, marketplace?, filter?, page?, limit?
Returns
products (each with trend), total, page
get_price_historyRead-only

A tracked product with every price read of the period, oldest first, including reads made before it was added (created_at says when). A history of more than 5000 points is thinned evenly, keeping its first and last point. At most 2 price histories per request.

Arguments
product_id, days?
Returns
the product and history: price, in_stock, coupon, seller, checked_at
get_item_historyRead-only

Every price Waltrack read for an item ID on a marketplace, tracked by the user or not, with the lowest, highest and average of those prices. A history of more than 5000 points is thinned evenly, keeping its first and last point. Free and instant: nothing is read from Walmart, so an item ID nobody tracked yet has an empty history. Use it to judge a price before tracking. At most 2 price histories per request.

Arguments
item_id, marketplace?, days?
Returns
item_id, marketplace, currency, lowest_price, highest_price, average_price, history: price, in_stock, coupon, seller, checked_at
update_productChanges the watchlist

Set a target price, drop alerts, the check interval or pause a tracked product. Send only what changes. Checks faster than daily need a plan or a credit pack: every 60 minutes with a pack or Starter, 30 with Pro, 5 with Business.

Arguments
product_id, target_price?, interval_minutes?, alert_on_drop?, paused?
Returns
the updated product
check_productUses 1 creditReads Walmart

Read the product's price on Walmart right away (1 credit), at most once per 5 minutes; earlier calls return it unchanged. A paused product has to be resumed first. Waits up to 45 seconds for the check. Read last_error if the check didn't go through.

Arguments
product_id
Returns
the product with its latest price
untrack_productDeletes data

Remove a product from the watchlist, with its price history.

Arguments
product_id
Returns
deleted, product_id

Arguments and results use the same names as the REST API, so the product object and states apply as-is. A failed tool call returns its message with the error code in parentheses, e.g. (product_limit).

Try asking

  • Track this for me and tell me when it drops under $50: https://www.walmart.com/ip/5129929197
  • Which of my products are cheaper than when I added them?
  • Show the price history of the AirPods over the last 3 months.
  • Anything out of stock or broken on my watchlist?
  • Check the PS5 price on walmart.com now.

Start tracking

Create an account, confirm your email and get 1500 free credits to try the API.