{"openapi":"3.1.0","info":{"title":"Sam's Club API (Bowmark)","version":"e833508f87ff","description":"Sam's Club (samsclub.com) — club-priced product search, product detail, club-level stock, club locator, membership plans and more. search reads the site's own live catalog search for a keyword (name, member price, item id, thumbnail, rating). getProduct reads one product's full detail page (member price, non-member price where shown, images, brand, breadcrumb category, description, aggregate rating) for an item id or URL a search already returned. getInstantSavings reads the site's own live Instant Savings promotional catalog (was/now price, savings amount, expiry, purchase limit), paginated. browseCategory reads the live grid for one of the site's own department pages (name, price, was-price, rating, availability) given the site's own numeric category id. getFuelPrices reads a specific club's current fuel-center prices (per grade — unleaded, premium, diesel where sold) given the site's own numeric club id. findClubs reads the site's own club locator for a zip code — address, phone, hours and which real departments each nearby club has, as the site's own label strings (“Sam’s Fuel Station”, never “Fuel Center”). getMembershipPlans reads the site's own published Club/Plus membership tiers — current price, regular price, and the full stated benefit-by-tier comparison. The rest is not yet built.\n\nEvery function Bowmark has for Sam's Club (samsclub.com) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/samsclub/search":{"post":{"operationId":"search","summary":"Searches samsclub.com's live catalog for a keyword and returns matching products — name, member price, item id, thumbnail and rating — the way the site's own search bar does.","description":"Searches samsclub.com's live catalog for a keyword and returns matching products — name, member price, item id, thumbnail and rating — the way the site's own search bar does. No category/brand/price filter: `?cat_id=` was measured and found not to actually scope results (see index.ts's file-top note).\n\nCalls `bowmark.providers.samsclub.search`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<SamsclubCategoryItem[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"TypeScript: `string`"}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/samsclub/getInstantSavings":{"post":{"operationId":"getInstantSavings","summary":"Reads one page (47 rows) of samsclub.com's live Instant Savings promotional catalog — was/now price, savings amount, expiry text and purchase limit — for every item currently on the site's own rotatin","description":"Reads one page (47 rows) of samsclub.com's live Instant Savings promotional catalog — was/now price, savings amount, expiry text and purchase limit — for every item currently on the site's own rotating discount book. `page` is 1-based and defaults to 1; the catalog runs to roughly 700 items across ~15 pages.\n\nCalls `bowmark.providers.samsclub.getInstantSavings`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<SamsclubInstantSavingsItem[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"type":"number","description":"TypeScript: `number`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/samsclub/browseCategory":{"post":{"operationId":"browseCategory","summary":"Reads the current live grid (~50 rows) for one of samsclub.com's own department/category pages — name, price, was-price, rating and availability — given the site's own numeric category id (e.g.","description":"Reads the current live grid (~50 rows) for one of samsclub.com's own department/category pages — name, price, was-price, rating and availability — given the site's own numeric category id (e.g. `1040209` for \"Beer, Wine & Spirits\", found in the site's own `/browse/<slug>/<id>` URLs). No pagination: the site does not expose a stable further page for a department grid.\n\nCalls `bowmark.providers.samsclub.browseCategory`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<SamsclubCategoryItem[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"categoryId":{"type":"string","description":"TypeScript: `string`"}},"required":["categoryId"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/samsclub/getFuelPrices":{"post":{"operationId":"getFuelPrices","summary":"Reads the current live fuel-center prices at one club — dollars per gallon for each grade the club actually sells (Unleaded, Premium, and Diesel where offered) — given the site's own numeric club id (","description":"Reads the current live fuel-center prices at one club — dollars per gallon for each grade the club actually sells (Unleaded, Premium, and Diesel where offered) — given the site's own numeric club id (e.g. \"6372\", found in a `samsclub.com/club/<id>` URL). `prices` is empty when the club has no fuel center at all, which is a fact about the location, not a parse failure. Resolving a zip code to a club id is `findClubs`'s job, not this one's.\n\nCalls `bowmark.providers.samsclub.getFuelPrices`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<SamsclubFuelPrices>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clubId":{"type":"string","description":"TypeScript: `string`"}},"required":["clubId"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/samsclub/getProduct":{"post":{"operationId":"getProduct","summary":"Reads one product's full page — member price (and non-member price where the site shows one), breadcrumb category, images, brand, full bullet-point description and aggregate rating — for a usItemId or","description":"Reads one product's full page — member price (and non-member price where the site shows one), breadcrumb category, images, brand, full bullet-point description and aggregate rating — for a usItemId or product URL a search/browseCategory/getInstantSavings result already returned.\n\nCalls `bowmark.providers.samsclub.getProduct`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<SamsclubProduct>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idOrUrl":{"type":"string","description":"TypeScript: `string`"}},"required":["idOrUrl"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/samsclub/checkStock":{"post":{"operationId":"checkStock","summary":"Answers whether one item is in stock right now, and at what price, at a named club or the club Sam's Club considers nearest to a 5-digit zip.","description":"Answers whether one item is in stock right now, and at what price, at a named club or the club Sam's Club considers nearest to a 5-digit zip. A named-club request returns only that exact club; if the site selects another club, it returns an unavailable error instead of silently substituting it. Zip requests remain best-effort nearest-club results and return the answered club id/name.\n\nCalls `bowmark.providers.samsclub.checkStock`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<SamsclubStock>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"idOrUrl":{"type":"string","description":"TypeScript: `string`"},"location":{"anyOf":[{"type":"object","properties":{"clubId":{"type":"string"}},"required":["clubId"],"additionalProperties":true},{"type":"object","properties":{"zip":{"type":"string"}},"required":["zip"],"additionalProperties":true}],"description":"TypeScript: `{ clubId: string } | { zip: string }`"}},"required":["idOrUrl","location"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/samsclub/findClubs":{"post":{"operationId":"findClubs","summary":"Finds nearby Sam's Club warehouse locations for a 5-digit US zip — address, phone, hours, distance and which real customer-facing departments each club has, the way the site's own club finder does.","description":"Finds nearby Sam's Club warehouse locations for a 5-digit US zip — address, phone, hours, distance and which real customer-facing departments each club has, the way the site's own club finder does. `services` carries the SITE'S OWN label strings verbatim, curly apostrophes included (“Sam’s Fuel Station”, never “Fuel Center”) — a caller filters on a value read off a result, never one guessed from prose. Resolves clubId for getFuelPrices/checkStock's clubId argument.\n\nCalls `bowmark.providers.samsclub.findClubs`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<SamsclubClub[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zip":{"type":"string","description":"TypeScript: `string`"}},"required":["zip"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/samsclub/getMembershipPlans":{"post":{"operationId":"getMembershipPlans","summary":"Reads the site's own published membership tiers (Club, Plus) — the currently-displayed price, the regular price it discounts from when a promo is running, and the full stated benefit-by-tier compariso","description":"Reads the site's own published membership tiers (Club, Plus) — the currently-displayed price, the regular price it discounts from when a promo is running, and the full stated benefit-by-tier comparison (fuel savings, Sam's Cash rate, free shipping/delivery threshold, pharmacy/optical/tire savings, and more), the way the site's own plan-comparison page states it. Read-only: joining or paying for a membership is out of scope.\n\nCalls `bowmark.providers.samsclub.getMembershipPlans`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<SamsclubMembershipPlan[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}}}}}