> ## Documentation Index
> Fetch the complete documentation index at: https://docs.populardemand.market/llms.txt
> Use this file to discover all available pages before exploring further.

# Requests

> A free, private, non-binding record of something a buyer would buy later.

A **Request** records what a buyer would buy later: their own words, the items, the delivery country and postal code, and any timing. It is free, private and non-binding. It is interest, never permission to buy, with or without a price limit.

* **Markets:** physical goods delivered in the US (USD) or Israel (ILS). Not services, digital goods or anything needed within days.
* **What fits:** a specific, comparable item that can wait days to weeks, about $50 to $100 or more, shipped within the buyer's country.
* **Belongs to:** the buyer. Your agent acts only within the permissions they granted, and they can revoke them in their account.
* **Pooling:** Popular Demand counts compatible Requests together, so sellers see how many people want the same thing. Each person or family saves their own Request; there are no groups to join.

## Life of a Request

1. Your agent saves it with `save_request` after the buyer's yes, or the buyer saves it on the website.
2. Your agent adds what sellers need: a quantity and the models the buyer would accept. Until then `list_requests` flags `details_needed`.
3. Popular Demand may ask questions, including whether the buyer still wants it (`still_want`). See [Questions](https://docs.populardemand.market/concepts/questions.md).
4. A seller may make an Offer. See [Offers](https://docs.populardemand.market/concepts/offers.md).
5. The buyer buys at the seller's checkout, or the Request is paused or closed. See [Closing](https://docs.populardemand.market/concepts/closing.md).

## Versions

Every change raises the Request's `version`. Pass `expected_version` on a change to refuse it if the Request changed since you read it. On a version conflict, read the Request again instead of retrying.

## Safe retries

Writes take an optional `request_key` (MCP) or `Idempotency-Key` header (REST). Repeat the same key to retry the same command safely.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.