Skip to main content
For when the user already knows what they want and needs to know where it’s actually in stock.

​
When to use

  • Agent has a specific GTIN (from barcode, resolve-gtin, or local-product-search).
  • User asks “where can I actually buy this today?”
Don’t use this for discovery — use local-product-search instead. Closient’s search session takes a GTIN constraint and returns availability hits grouped by store. 
POST /search/api/v1/search/session
Content-Type: application/json

{
  "query": "gtin:00012345678905",
  "latitude": 48.4284,
  "longitude": -123.3656,
  "radius_km": 25,
  "in_stock": true
}

​
Response

Each hit has:
  • store — name, address, distance_km
  • offer — price, stock_status (in_stock / low_stock / out_of_stock / unknown), last_checked_at

​
Typical flow

  1. Start with local-product-search to find a candidate product → get gtin.
  2. Use this skill to check where to actually buy it near the user.
  3. Optionally use resolve-gtin for deeper product detail.

​
Planned (not yet shipped)

GET /retailers/api/v1/products/{gtin}/availability?lat=...&lon=...&radius_km=... — a direct geo-distance endpoint that skips the session. Use the session approach above until that lands.
  • local-product-search — start here if the user doesn’t have a GTIN
  • resolve-gtin — get product detail for the GTIN in the hits
  • check-recalls — confirm the product isn’t under recall before recommending