{"openapi":"3.1.0","info":{"title":"Waltrack API","version":"0.0.1","description":"Track Walmart prices and products: a watchlist checked on schedule, with price history and alerts. Authenticate with a personal API key from your account (Bearer token). Each price check of a tracked product costs 1 credit; a product checked daily uses about 30 credits a month. Failed checks are refunded. The same key works with the MCP server at /api/mcp, which also accepts a sign-in through OAuth, and the Chrome extension."},"externalDocs":{"description":"Documentation","url":"https://www.waltrack.dev/docs"},"servers":[{"url":"https://www.waltrack.dev/api/v1"}],"tags":[{"name":"Watchlist","description":"The products you track, checked on their schedule."},{"name":"Walmart data","description":"Search Walmart and read any product's shared price history."},{"name":"Account","description":"Your plan and your credits."}],"security":[{"bearerAuth":[]}],"paths":{"/account":{"get":{"operationId":"getAccount","tags":["Account"],"summary":"Plan and remaining credits","description":"Your plan, the credits left (monthly allowance and packs), how many products you track and the credits they use per month.","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"},"example":{"plan":"basic","plan_name":"Starter","credits":29588,"renews_at":"2026-12-01T09:12:44.000Z","products":42,"product_limit":50000,"fastest_interval_minutes":60,"monthly_credits":1260,"manage_url":"https://www.waltrack.dev/app"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"operationId":"searchWalmart","tags":["Walmart data"],"summary":"Search Walmart","description":"Walmart search results (sponsored included), to find the item ID of a product. Free, limited to 30 searches per hour.","parameters":[{"name":"query","in":"query","required":true,"description":"Keywords","schema":{"type":"string"},"example":"wireless earbuds"},{"name":"marketplace","in":"query","description":"Always com (walmart.com)","schema":{"type":"string","enum":["com"],"default":"com","description":"Always com (walmart.com)"},"example":"com"}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}}},"example":{"results":[{"item_id":"5129929197","title":"Wireless Earbuds, Bluetooth 5.3, Noise Cancelling","image":"https://i5.walmartimages.com/seo/…jpeg","price":79.99,"currency":"USD","rating":4.4,"reviews_count":12873}]}}}},"400":{"description":"invalid_option: A 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: More 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"store_unavailable: Walmart couldn't be read right now (GET /search). Nothing is charged; retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/history":{"get":{"operationId":"getItemHistory","tags":["Walmart data"],"summary":"Price history of any item ID","description":"Every price Waltrack read for an item ID on a marketplace over the period, whoever tracks it, oldest first, 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, limited to 600 reads per hour: no credit is used and nothing is read from Walmart, so an item ID nobody tracked yet has an empty history.","parameters":[{"name":"item_id","in":"query","required":true,"description":"Walmart item ID (the number at the end of a walmart.com/ip/ link)","schema":{"type":"string","pattern":"^[0-9]{6,13}$","description":"Walmart item ID (the number at the end of a walmart.com/ip/ link)"},"example":"5129929197"},{"name":"marketplace","in":"query","description":"Always com (walmart.com)","schema":{"type":"string","enum":["com"],"default":"com","description":"Always com (walmart.com)"},"example":"com"},{"name":"days","in":"query","description":"History period in days","schema":{"type":"integer","minimum":1,"maximum":730,"default":90,"description":"History period in days"},"example":"30"}],"responses":{"200":{"description":"History of the item ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemHistory"},"example":{"item_id":"5129929197","marketplace":"com","currency":"USD","lowest_price":74.5,"highest_price":99.99,"average_price":84.83,"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"}]}}}},"400":{"description":"invalid_product: product 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). invalid_option: A 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: More 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"operationId":"listProducts","tags":["Watchlist"],"summary":"List tracked products","description":"Your watchlist, newest first, with each product's latest state and its recent prices (trend). Filter with item_id (and marketplace) to know if a product is tracked, or with filter to get the same lists as the app's tabs.","parameters":[{"name":"item_id","in":"query","description":"Only this item ID","schema":{"type":"string","pattern":"^[0-9]{6,13}$","description":"Walmart item ID (the number at the end of a walmart.com/ip/ link)"},"example":"5129929197"},{"name":"marketplace","in":"query","description":"Only this Walmart store","schema":{"type":"string","enum":["com"],"description":"Only this Walmart store"}},{"name":"filter","in":"query","description":"Only the products of one of the app's watchlist filters. all: Every tracked product (default). drops: Cheaper now than when the product was added. target: At or below its target price. out_of_stock: No offer at the last check. attention: The last check didn't go through (last_error is set): no credits, not found or Walmart unavailable. paused: Paused by you: not checked, not charged.","schema":{"type":"string","enum":["all","drops","target","out_of_stock","attention","paused"],"default":"all","description":"Only the products of one of the app's watchlist filters. all: Every tracked product (default). drops: Cheaper now than when the product was added. target: At or below its target price. out_of_stock: No offer at the last check. attention: The last check didn't go through (last_error is set): no credits, not found or Walmart unavailable. paused: Paused by you: not checked, not charged."}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Products per page","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Products","content":{"application/json":{"schema":{"type":"object","required":["products","total","page"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total":{"type":"integer"},"page":{"type":"integer"}}},"example":{"products":[{"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","trend":[99.99,74.5,79.99]}],"total":1,"page":1}}}},"400":{"description":"invalid_product: product 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). invalid_option: A 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"trackProduct","tags":["Watchlist"],"summary":"Track a product","description":"Adds an item ID, a Walmart link or a short link (walmrt.us) to your watchlist. The first check runs in the background within seconds (checking is true until then): poll GET /products/{id}, or send wait: true to get the answer once it's done (up to 45 seconds). Each price check of a tracked product costs 1 credit; a product checked daily uses about 30 credits a month. Without credits the product is added and its first check waits. What Walmart answers shows on the product (last_error), never as an error here. Adding a product you already track returns it unchanged, with status 200.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product"],"properties":{"product":{"type":"string","description":"item ID (5129929197) or Walmart product link"},"marketplace":{"type":"string","enum":["com"],"default":"com","description":"Always com (walmart.com). A product link sets it on its own."},"target_price":{"type":["number","null"],"description":"Email the owner when the price goes at or below this amount. null removes it."},"interval_minutes":{"type":"integer","enum":[5,30,60,360,720,1440],"default":1440,"description":"Minutes between two checks (1440 = daily). 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."},"wait":{"type":"boolean","default":false,"description":"Answer once the first check is done (up to 45 seconds)"}}},"example":{"product":"5129929197","marketplace":"com","target_price":70,"wait":true}}}},"responses":{"200":{"description":"Already tracked: the product as it is, unchanged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"},"example":{"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"}}}},"201":{"description":"Tracked product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"},"example":{"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"}}}},"400":{"description":"invalid_product: product 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). unsupported_marketplace: The link is from a Walmart site other than walmart.com. invalid_option: A 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"paid_option: 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. product_limit: The account tracks as many products as its plan allows (50 on the free plan).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":{"code":"product_limit","message":"You've reached your plan's product limit. The free plan tracks up to 50 products."}}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}":{"get":{"operationId":"getProduct","tags":["Watchlist"],"summary":"Get a product and its price history","description":"The product's latest state and every price read of the period, oldest first. The history covers every read of this item ID on this marketplace, including those made before you added it, so a product added today can come with months of prices; created_at says when you added it. A history of more than 5000 points is thinned evenly, keeping its first and last point.","parameters":[{"name":"id","in":"path","required":true,"description":"product_id returned when the product was added","schema":{"type":"string","format":"uuid"},"example":"8f0b3c7e-2a4d-4e51-9c1a-6d2f1b9e7a30"},{"name":"days","in":"query","description":"History period in days","schema":{"type":"integer","minimum":1,"maximum":730,"default":90,"description":"History period in days"},"example":"30"}],"responses":{"200":{"description":"Product with history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductWithHistory"},"example":{"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"}]}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: No tracked product with this id on your account, or no such endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateProduct","tags":["Watchlist"],"summary":"Change alerts and checks","description":"Target price, drop alerts, check interval, or pause. Send only what changes.","parameters":[{"name":"id","in":"path","required":true,"description":"product_id returned when the product was added","schema":{"type":"string","format":"uuid"},"example":"8f0b3c7e-2a4d-4e51-9c1a-6d2f1b9e7a30"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target_price":{"type":["number","null"],"description":"Email the owner when the price goes at or below this amount. null removes it."},"interval_minutes":{"type":"integer","enum":[5,30,60,360,720,1440],"default":1440,"description":"Minutes between two checks (1440 = daily). 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."},"alert_on_drop":{"type":"boolean","description":"Email when the price drops or the product is back in stock"},"paused":{"type":"boolean","description":"Stop checking (and charging) for now; false resumes"}}},"example":{"target_price":65,"interval_minutes":360}}}},"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"},"example":{"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"}}}},"400":{"description":"invalid_option: A 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"paid_option: 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: No tracked product with this id on your account, or no such endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteProduct","tags":["Watchlist"],"summary":"Stop tracking a product","description":"Removes the product and its price history.","parameters":[{"name":"id","in":"path","required":true,"description":"product_id returned when the product was added","schema":{"type":"string","format":"uuid"},"example":"8f0b3c7e-2a4d-4e51-9c1a-6d2f1b9e7a30"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["deleted","product_id"],"properties":{"deleted":{"type":"boolean"},"product_id":{"type":"string","format":"uuid"}}},"example":{"deleted":true,"product_id":"8f0b3c7e-2a4d-4e51-9c1a-6d2f1b9e7a30"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: No tracked product with this id on your account, or no such endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{id}/check":{"post":{"operationId":"checkProduct","tags":["Watchlist"],"summary":"Check the price now","description":"Asks for a check right away (1 credit), at most once per 5 minutes; earlier calls return the product unchanged. A paused product has to be resumed first. The check runs in the background; with wait=true the answer waits for it. Read last_error if it didn't go through.","parameters":[{"name":"id","in":"path","required":true,"description":"product_id returned when the product was added","schema":{"type":"string","format":"uuid"},"example":"8f0b3c7e-2a4d-4e51-9c1a-6d2f1b9e7a30"},{"name":"wait","in":"query","description":"Answer once the check is done (up to 45 seconds)","schema":{"type":"boolean","default":false},"example":"true"}],"responses":{"200":{"description":"Product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"},"example":{"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"}}}},"400":{"description":"invalid_option: A 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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized: The API key is missing, revoked or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: No tracked product with this id on your account, or no such endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"generic: Unexpected error on our side. Retry in a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Personal API key (wal_…), created in your account."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_product","unsupported_marketplace","invalid_option","unauthorized","insufficient_credits","email_not_verified","paid_option","product_limit","not_found","product_not_found","method_not_allowed","rate_limited","generic","store_unavailable"],"description":"Stable code to branch on"},"message":{"type":"string","description":"Human-readable explanation"}}}}},"Account":{"type":"object","required":["plan","plan_name","credits","renews_at","products","product_limit","fastest_interval_minutes","monthly_credits","manage_url"],"properties":{"plan":{"type":"string","enum":["free","basic","pro","mega"],"description":"Plan id"},"plan_name":{"type":"string","description":"Display name of the plan"},"credits":{"type":"integer","description":"Credits left, packs included"},"renews_at":{"type":["string","null"],"format":"date-time","description":"Next renewal of a paid plan"},"products":{"type":"integer","description":"Tracked products"},"product_limit":{"type":"integer","description":"Products the plan allows"},"fastest_interval_minutes":{"type":"integer","enum":[5,30,60,360,720,1440],"description":"Shortest interval_minutes the account can choose now"},"monthly_credits":{"type":"integer","description":"Credits the active products use per 30 days at their intervals"},"manage_url":{"type":"string","format":"uri","description":"Where to change plan or buy a pack"}}},"SearchResult":{"type":"object","required":["item_id","title","image","price","currency","rating","reviews_count"],"properties":{"item_id":{"type":"string","description":"Walmart item ID (the number at the end of a walmart.com/ip/ link), to track or read its history"},"title":{"type":"string","description":"Product title"},"image":{"type":["string","null"],"format":"uri","description":"Main product image"},"price":{"type":["number","null"],"description":"Price shown in the results"},"currency":{"type":"string","description":"ISO 4217 code of the marketplace"},"rating":{"type":["number","null"],"description":"Average rating out of 5"},"reviews_count":{"type":["integer","null"],"description":"Number of reviews"}}},"Product":{"type":"object","required":["product_id","item_id","marketplace","url","title","image","brand","currency","price","first_price","lowest_price","highest_price","in_stock","stock","coupon","seller","best_sellers_rank","target_price","alert_on_drop","interval_minutes","status","last_error","found_on","checking","last_checked_at","next_check_at","created_at"],"properties":{"product_id":{"type":"string","format":"uuid","description":"Id of this watchlist entry"},"item_id":{"type":"string","description":"Walmart item ID (the number at the end of a walmart.com/ip/ link)"},"marketplace":{"type":"string","enum":["com"],"description":"Walmart store"},"url":{"type":"string","format":"uri","description":"Product page on Walmart"},"title":{"type":["string","null"],"description":"null until the first check"},"image":{"type":["string","null"],"format":"uri","description":"Main product image"},"brand":{"type":["string","null"],"description":"Brand shown by Walmart"},"currency":{"type":["string","null"],"description":"ISO code, e.g. USD, EUR, JPY"},"price":{"type":["number","null"],"description":"Latest price; null when there is no offer"},"first_price":{"type":["number","null"],"description":"Price at the first check"},"lowest_price":{"type":["number","null"],"description":"Lowest price seen"},"highest_price":{"type":["number","null"],"description":"Highest price seen"},"in_stock":{"type":["boolean","null"],"description":"null until the first check"},"stock":{"type":["string","null"],"description":"Walmart's availability text"},"coupon":{"type":["string","null"],"description":"Always null: Walmart pages show no coupons"},"seller":{"type":["string","null"],"description":"Seller of the offer shown (Buy Box)"},"best_sellers_rank":{"type":["string","null"],"description":"Always null: Walmart has no Best Sellers Rank"},"target_price":{"type":["number","null"],"description":"Alert threshold"},"alert_on_drop":{"type":"boolean","description":"Email when the price drops or the product is back in stock"},"interval_minutes":{"type":"integer","enum":[5,30,60,360,720,1440],"description":"Minutes between two checks"},"status":{"type":"string","enum":["active","paused"],"description":"Paused products aren't checked"},"last_error":{"type":["string","null"],"enum":["email_not_verified","insufficient_credits","store_unavailable","product_not_found"],"description":"Why the last check didn't go through, if it didn't"},"found_on":{"type":"array","items":{"type":"string","enum":["com"]},"description":"When last_error is product_not_found: marketplaces where the item ID exists"},"checking":{"type":"boolean","description":"A check is due or running; poll until it's false"},"last_checked_at":{"type":["string","null"],"format":"date-time","description":"When the last check ran"},"next_check_at":{"type":"string","format":"date-time","description":"When the next one is due"},"created_at":{"type":"string","format":"date-time","description":"When it was added"},"trend":{"type":"array","items":{"type":"number"},"description":"Only in lists: up to 30 prices of the last 30 days, oldest first"}}},"ProductWithHistory":{"type":"object","required":["product_id","item_id","marketplace","url","title","image","brand","currency","price","first_price","lowest_price","highest_price","in_stock","stock","coupon","seller","best_sellers_rank","target_price","alert_on_drop","interval_minutes","status","last_error","found_on","checking","last_checked_at","next_check_at","created_at","history"],"properties":{"product_id":{"type":"string","format":"uuid","description":"Id of this watchlist entry"},"item_id":{"type":"string","description":"Walmart item ID (the number at the end of a walmart.com/ip/ link)"},"marketplace":{"type":"string","enum":["com"],"description":"Walmart store"},"url":{"type":"string","format":"uri","description":"Product page on Walmart"},"title":{"type":["string","null"],"description":"null until the first check"},"image":{"type":["string","null"],"format":"uri","description":"Main product image"},"brand":{"type":["string","null"],"description":"Brand shown by Walmart"},"currency":{"type":["string","null"],"description":"ISO code, e.g. USD, EUR, JPY"},"price":{"type":["number","null"],"description":"Latest price; null when there is no offer"},"first_price":{"type":["number","null"],"description":"Price at the first check"},"lowest_price":{"type":["number","null"],"description":"Lowest price seen"},"highest_price":{"type":["number","null"],"description":"Highest price seen"},"in_stock":{"type":["boolean","null"],"description":"null until the first check"},"stock":{"type":["string","null"],"description":"Walmart's availability text"},"coupon":{"type":["string","null"],"description":"Always null: Walmart pages show no coupons"},"seller":{"type":["string","null"],"description":"Seller of the offer shown (Buy Box)"},"best_sellers_rank":{"type":["string","null"],"description":"Always null: Walmart has no Best Sellers Rank"},"target_price":{"type":["number","null"],"description":"Alert threshold"},"alert_on_drop":{"type":"boolean","description":"Email when the price drops or the product is back in stock"},"interval_minutes":{"type":"integer","enum":[5,30,60,360,720,1440],"description":"Minutes between two checks"},"status":{"type":"string","enum":["active","paused"],"description":"Paused products aren't checked"},"last_error":{"type":["string","null"],"enum":["email_not_verified","insufficient_credits","store_unavailable","product_not_found"],"description":"Why the last check didn't go through, if it didn't"},"found_on":{"type":"array","items":{"type":"string","enum":["com"]},"description":"When last_error is product_not_found: marketplaces where the item ID exists"},"checking":{"type":"boolean","description":"A check is due or running; poll until it's false"},"last_checked_at":{"type":["string","null"],"format":"date-time","description":"When the last check ran"},"next_check_at":{"type":"string","format":"date-time","description":"When the next one is due"},"created_at":{"type":"string","format":"date-time","description":"When it was added"},"history":{"type":"array","items":{"type":"object","required":["price","in_stock","coupon","seller","checked_at"],"properties":{"price":{"type":["number","null"],"description":"null when there was no offer"},"in_stock":{"type":["boolean","null"],"description":"Whether it was in stock"},"coupon":{"type":["string","null"],"description":"Coupon shown, if any"},"seller":{"type":["string","null"],"description":"Seller of the offer shown (Buy Box)"},"checked_at":{"type":"string","format":"date-time","description":"When Walmart was read"}}}}}},"ItemHistory":{"type":"object","required":["item_id","marketplace","currency","lowest_price","highest_price","average_price","history"],"properties":{"item_id":{"type":"string","description":"Walmart item ID (the number at the end of a walmart.com/ip/ link)"},"marketplace":{"type":"string","enum":["com"],"description":"Walmart store"},"currency":{"type":"string","description":"ISO 4217 code of the marketplace"},"lowest_price":{"type":["number","null"],"description":"Lowest price of the period"},"highest_price":{"type":["number","null"],"description":"Highest price of the period"},"average_price":{"type":["number","null"],"description":"Average of the period's prices"},"history":{"type":"array","items":{"type":"object","required":["price","in_stock","coupon","seller","checked_at"],"properties":{"price":{"type":["number","null"],"description":"null when there was no offer"},"in_stock":{"type":["boolean","null"],"description":"Whether it was in stock"},"coupon":{"type":["string","null"],"description":"Coupon shown, if any"},"seller":{"type":["string","null"],"description":"Seller of the offer shown (Buy Box)"},"checked_at":{"type":"string","format":"date-time","description":"When Walmart was read"}}}}}}}}}