> ## 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.

# save_request

> Save a Request

Save a new free, private, non-binding Request for delivery in the US or Israel, when the person asks you to or says yes to what you showed them. Ask once, together, for what’s missing: how many, when they need it and their postal code (ZIP in the US). “A chair” means one; for a plural or a vague wish, never assume a number. If they skip something, save without it. A model can come later. Use it for a future purchase the person will buy later, with no rush or to wait for a better or group price: physical goods, not services, digital goods or anything needed within days. With several items, ask “If only some items come through, do you still want those?” once; the person may skip it. If they state a maximum for everything together, record it as the Request-wide price\_limit with includes\_delivery\_and\_tax true. A limit without “in total” or “each” is unclear. Ask once which they meant, or in a background task leave it out. Record no as all\_items\_required true, with the items they need marked required; record yes or a skip as false, the default, where each item settles on its own deal. Works well: a specific, comparable item (brand and model or accepted alternatives) that can wait days to weeks, about $50 to $100+, shipped within the buyer’s country. Works poorly: urgent or perishable goods, custom items, services, regulated or restricted goods, very cheap items. If possible\_duplicate\_of lists the same thing, ask the person which to keep. Relay save\_confirmation.

## Access

| Property | Value |
| - | - |
| OAuth scope | `purchases:write` |
| Effect | `reversible` |
| `readOnlyHint` | No |
| `destructiveHint` | No |
| `idempotentHint` | Yes |
| `openWorldHint` | No |

The buyer also approves each permission on the consent page. See [Authentication](https://docs.populardemand.market/authentication.md).

## Arguments

| Field | Type | Required | Description |
| - | - | - | - |
| `request` | object | Yes | The Request: the person’s words, items they want, where and when. |
| `request.words` | string | Yes | What the person asked for, in their own words and language. |
| `request.country` | `US`, `IL` | No | Default `"US"`. |
| `request.destination` | object | No | Default `{}`. |
| `request.destination.postal_code` | string | No | A US ZIP (12345 or 12345-6789) or a 7-digit Israeli postal code. Optional when saving; required before an Offer can be prepared. |
| `request.destination.city` | string | No | |
| `request.destination.region` | string | No | State or region; derived from postal\_code when one is given. |
| `request.destination.scope` | `national_parcel`, `regional`, `unknown` | No | |
| `request.need_by` | string (date) or null | No | |
| `request.time_horizon` | string | No | |
| `request.delivery` | array of `shipping`, `pickup` | No | |
| `request.all_items_required` | boolean | No | |
| `request.items` | array of object | No | One item the person needs, with how many if known. Its options are the models they would accept: several options mean any one of them, not several purchases. Default `[]`. |
| `request.items[].item_id` | string | No | Optional stable id; one is assigned when left out. |
| `request.items[].description` | string | Yes | |
| `request.items[].quantity` | integer or null | No | How many; null when the person hasn’t said. |
| `request.items[].required` | boolean | No | Leave out unless the person says this item is optional. Optional items don’t count in the pool counts people see. |
| `request.items[].options` | array of object | No | The models the person would accept: several options mean any one of them, not several purchases. |
| `request.items[].options[].option_id` | string | No | Keep an existing option’s id; leave out for a new one. |
| `request.items[].options[].description` | string | Yes | |
| `request.items[].options[].product` | object | No | |
| `request.items[].options[].product.brand` | string | No | |
| `request.items[].options[].product.model` | string | No | |
| `request.items[].options[].product.url` | string (uri) | No | |
| `request.items[].options[].product.attributes` | array of object | No | |
| `request.items[].options[].product.attributes[].name` | string | Yes | |
| `request.items[].options[].product.attributes[].value` | string | Yes | |
| `request.items[].terms` | object | No | |
| `request.items[].terms.warranty_months_min` | integer or null | No | |
| `request.items[].terms.returns_days_min` | integer or null | No | |
| `request.items[].terms.authorized_seller_required` | boolean or null | No | |
| `request.items[].price_limit` | object | No | The most the person will pay for one unit of this item, in the currency’s smallest unit. Record it only when the person volunteers it. For a limit on the whole order, use the Request’s price\_limit. |
| `request.items[].price_limit.amount_minor` | integer | Yes | |
| `request.items[].price_limit.includes_delivery_and_tax` | boolean | Yes | |
| `request.price_limit` | object | No | The most the person will pay for the whole order, in the currency’s smallest unit (cents for USD). Record it only when the person volunteers it; never ask for one. It marks Offers above it and is not permission to spend. |
| `request.price_limit.amount_minor` | integer | Yes | |
| `request.price_limit.includes_delivery_and_tax` | boolean | Yes | |
| `request_key` | string | No | Optional. The same key repeats a change safely; one is derived when left out. |

> [accordion] Input JSON Schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "request": {
>       "type": "object",
>       "properties": {
>         "words": {
>           "type": "string",
>           "minLength": 5,
>           "maxLength": 4000,
>           "description": "What the person asked for, in their own words and language."
>         },
>         "country": {
>           "default": "US",
>           "type": "string",
>           "enum": [
>             "US",
>             "IL"
>           ]
>         },
>         "destination": {
>           "default": {},
>           "type": "object",
>           "properties": {
>             "postal_code": {
>               "description": "A US ZIP (12345 or 12345-6789) or a 7-digit Israeli postal code. Optional when saving; required before an Offer can be prepared.",
>               "type": "string",
>               "maxLength": 32
>             },
>             "city": {
>               "type": "string",
>               "minLength": 1,
>               "maxLength": 100
>             },
>             "region": {
>               "description": "State or region; derived from postal_code when one is given.",
>               "type": "string",
>               "minLength": 1,
>               "maxLength": 100
>             },
>             "scope": {
>               "type": "string",
>               "enum": [
>                 "national_parcel",
>                 "regional",
>                 "unknown"
>               ]
>             }
>           },
>           "additionalProperties": false
>         },
>         "need_by": {
>           "anyOf": [
>             {
>               "type": "string",
>               "format": "date"
>             },
>             {
>               "type": "null"
>             }
>           ]
>         },
>         "time_horizon": {
>           "type": "string",
>           "minLength": 1,
>           "maxLength": 200
>         },
>         "delivery": {
>           "maxItems": 2,
>           "type": "array",
>           "items": {
>             "type": "string",
>             "enum": [
>               "shipping",
>               "pickup"
>             ]
>           }
>         },
>         "all_items_required": {
>           "type": "boolean"
>         },
>         "items": {
>           "default": [],
>           "maxItems": 20,
>           "type": "array",
>           "items": {
>             "type": "object",
>             "properties": {
>               "item_id": {
>                 "description": "Optional stable id; one is assigned when left out.",
>                 "type": "string",
>                 "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,79}$"
>               },
>               "description": {
>                 "type": "string",
>                 "minLength": 3,
>                 "maxLength": 1000
>               },
>               "quantity": {
>                 "anyOf": [
>                   {
>                     "type": "integer",
>                     "minimum": 1,
>                     "maximum": 10000
>                   },
>                   {
>                     "type": "null"
>                   }
>                 ],
>                 "description": "How many; null when the person hasn’t said."
>               },
>               "required": {
>                 "description": "Leave out unless the person says this item is optional. Optional items don’t count in the pool counts people see.",
>                 "type": "boolean"
>               },
>               "options": {
>                 "maxItems": 20,
>                 "type": "array",
>                 "items": {
>                   "type": "object",
>                   "properties": {
>                     "option_id": {
>                       "description": "Keep an existing option’s id; leave out for a new one.",
>                       "type": "string",
>                       "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,79}$"
>                     },
>                     "description": {
>                       "type": "string",
>                       "minLength": 3,
>                       "maxLength": 500
>                     },
>                     "product": {
>                       "type": "object",
>                       "properties": {
>                         "brand": {
>                           "type": "string",
>                           "minLength": 1,
>                           "maxLength": 200
>                         },
>                         "model": {
>                           "type": "string",
>                           "minLength": 1,
>                           "maxLength": 200
>                         },
>                         "url": {
>                           "type": "string",
>                           "maxLength": 2000,
>                           "format": "uri"
>                         },
>                         "attributes": {
>                           "maxItems": 20,
>                           "type": "array",
>                           "items": {
>                             "type": "object",
>                             "properties": {
>                               "name": {
>                                 "type": "string",
>                                 "minLength": 1,
>                                 "maxLength": 100
>                               },
>                               "value": {
>                                 "type": "string",
>                                 "minLength": 1,
>                                 "maxLength": 100
>                               }
>                             },
>                             "required": [
>                               "name",
>                               "value"
>                             ],
>                             "additionalProperties": false
>                           }
>                         }
>                       },
>                       "additionalProperties": false
>                     }
>                   },
>                   "required": [
>                     "description"
>                   ],
>                   "additionalProperties": false
>                 },
>                 "description": "The models the person would accept: several options mean any one of them, not several purchases."
>               },
>               "terms": {
>                 "type": "object",
>                 "properties": {
>                   "warranty_months_min": {
>                     "anyOf": [
>                       {
>                         "type": "integer",
>                         "minimum": 0,
>                         "maximum": 120
>                       },
>                       {
>                         "type": "null"
>                       }
>                     ]
>                   },
>                   "returns_days_min": {
>                     "anyOf": [
>                       {
>                         "type": "integer",
>                         "minimum": 0,
>                         "maximum": 365
>                       },
>                       {
>                         "type": "null"
>                       }
>                     ]
>                   },
>                   "authorized_seller_required": {
>                     "type": [
>                       "boolean",
>                       "null"
>                     ]
>                   }
>                 },
>                 "additionalProperties": false
>               },
>               "price_limit": {
>                 "type": "object",
>                 "properties": {
>                   "amount_minor": {
>                     "type": "integer",
>                     "exclusiveMinimum": 0,
>                     "maximum": 100000000
>                   },
>                   "includes_delivery_and_tax": {
>                     "type": "boolean"
>                   }
>                 },
>                 "required": [
>                   "amount_minor",
>                   "includes_delivery_and_tax"
>                 ],
>                 "additionalProperties": false,
>                 "description": "The most the person will pay for one unit of this item, in the currency’s smallest unit. Record it only when the person volunteers it. For a limit on the whole order, use the Request’s price_limit."
>               }
>             },
>             "required": [
>               "description"
>             ],
>             "additionalProperties": false,
>             "description": "One item the person needs, with how many if known. Its options are the models they would accept: several options mean any one of them, not several purchases."
>           }
>         },
>         "price_limit": {
>           "type": "object",
>           "properties": {
>             "amount_minor": {
>               "type": "integer",
>               "exclusiveMinimum": 0,
>               "maximum": 100000000
>             },
>             "includes_delivery_and_tax": {
>               "type": "boolean"
>             }
>           },
>           "required": [
>             "amount_minor",
>             "includes_delivery_and_tax"
>           ],
>           "additionalProperties": false,
>           "description": "The most the person will pay for the whole order, in the currency’s smallest unit (cents for USD). Record it only when the person volunteers it; never ask for one. It marks Offers above it and is not permission to spend."
>         }
>       },
>       "required": [
>         "words"
>       ],
>       "additionalProperties": false,
>       "description": "The Request: the person’s words, items they want, where and when."
>     },
>     "request_key": {
>       "description": "Optional. The same key repeats a change safely; one is derived when left out.",
>       "type": "string",
>       "minLength": 8,
>       "maxLength": 64
>     }
>   },
>   "required": [
>     "request"
>   ],
>   "additionalProperties": false
> }
> ```

> [accordion] Output JSON Schema
>
> ```json theme={null}
> {
>   "type": "object",
>   "properties": {
>     "result": {
>       "type": "object",
>       "properties": {
>         "request_id": {
>           "type": "string"
>         },
>         "version": {
>           "type": "integer",
>           "minimum": -9007199254740991,
>           "maximum": 9007199254740991
>         },
>         "status": {
>           "type": "string",
>           "enum": [
>             "open",
>             "closed"
>           ]
>         },
>         "status_label": {
>           "type": [
>             "string",
>             "null"
>           ]
>         },
>         "words": {
>           "type": "string"
>         },
>         "country": {
>           "type": "string"
>         },
>         "currency": {
>           "type": "string"
>         },
>         "destination": {},
>         "need_by": {},
>         "time_horizon": {
>           "type": [
>             "string",
>             "null"
>           ]
>         },
>         "delivery": {
>           "type": "array"
>         },
>         "all_items_required": {
>           "type": [
>             "boolean",
>             "null"
>           ]
>         },
>         "items": {
>           "type": "array"
>         },
>         "price_limits": {
>           "type": "array"
>         },
>         "expires_at": {
>           "type": "string"
>         },
>         "next_step": {
>           "type": [
>             "string",
>             "null"
>           ]
>         },
>         "save_confirmation": {
>           "type": "object",
>           "additionalProperties": true
>         },
>         "possible_duplicate_of": {
>           "type": "array"
>         },
>         "duplicate_hint": {
>           "type": [
>             "string",
>             "null"
>           ]
>         }
>       },
>       "required": [
>         "request_id",
>         "version",
>         "status",
>         "status_label",
>         "words",
>         "country",
>         "currency",
>         "destination",
>         "need_by",
>         "time_horizon",
>         "delivery",
>         "all_items_required",
>         "items",
>         "price_limits",
>         "expires_at",
>         "next_step",
>         "possible_duplicate_of",
>         "duplicate_hint"
>       ],
>       "additionalProperties": {}
>     }
>   },
>   "required": [
>     "result"
>   ],
>   "additionalProperties": false
> }
> ```


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