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

# update_request

> Change a Request

Change a saved Request after the person asks or agrees.

## Access

| Property | Value |
| - | - |
| OAuth scope | `purchases:write` |
| Effect | `reversible` |
| `readOnlyHint` | No |
| `destructiveHint` | Yes |
| `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_id` | string (uuid) | Yes | The Request’s id from list\_requests. |
| `expected_version` | integer | No | Optional. The Request version you last read. |
| `changes` | object | Yes | Only the fields to change; null clears one. |
| `changes.words` | string | No | What the person asked for, in their own words and language. |
| `changes.destination` | object | No | |
| `changes.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. |
| `changes.destination.city` | string | No | |
| `changes.destination.region` | string | No | State or region; derived from postal\_code when one is given. |
| `changes.destination.scope` | `national_parcel`, `regional`, `unknown` | No | |
| `changes.need_by` | string (date) or null | No | |
| `changes.time_horizon` | string or null | No | |
| `changes.delivery` | array of `shipping`, `pickup` | No | |
| `changes.all_items_required` | boolean or null | No | |
| `changes.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. |
| `changes.price_limit.amount_minor` | integer | Yes | |
| `changes.price_limit.includes_delivery_and_tax` | boolean | Yes | |
| `changes.items` | array of object | No | |
| `changes.items[].item_id` | string | No | Leave out to add a new item. |
| `changes.items[].remove` | `true` | No | True to delete this item. |
| `changes.items[].description` | string | No | |
| `changes.items[].quantity` | integer or null | No | How many; null when the person hasn’t said. |
| `changes.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. |
| `changes.items[].options` | array of object | No | Replaces this item’s options. |
| `changes.items[].options[].option_id` | string | No | Keep an existing option’s id; leave out for a new one. |
| `changes.items[].options[].description` | string | Yes | |
| `changes.items[].options[].product` | object | No | |
| `changes.items[].options[].product.brand` | string | No | |
| `changes.items[].options[].product.model` | string | No | |
| `changes.items[].options[].product.url` | string (uri) | No | |
| `changes.items[].options[].product.attributes` | array of object | No | |
| `changes.items[].options[].product.attributes[].name` | string | Yes | |
| `changes.items[].options[].product.attributes[].value` | string | Yes | |
| `changes.items[].terms` | object | No | |
| `changes.items[].terms.warranty_months_min` | integer or null | No | |
| `changes.items[].terms.returns_days_min` | integer or null | No | |
| `changes.items[].terms.authorized_seller_required` | boolean or null | No | |
| `changes.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. |
| `changes.items[].price_limit.amount_minor` | integer | Yes | |
| `changes.items[].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_id": {
>       "type": "string",
>       "format": "uuid",
>       "description": "The Request’s id from list_requests."
>     },
>     "expected_version": {
>       "description": "Optional. The Request version you last read.",
>       "type": "integer",
>       "exclusiveMinimum": 0,
>       "maximum": 9007199254740991
>     },
>     "changes": {
>       "type": "object",
>       "properties": {
>         "words": {
>           "type": "string",
>           "minLength": 5,
>           "maxLength": 4000,
>           "description": "What the person asked for, in their own words and language."
>         },
>         "destination": {
>           "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": {
>           "anyOf": [
>             {
>               "type": "string",
>               "minLength": 1,
>               "maxLength": 200
>             },
>             {
>               "type": "null"
>             }
>           ]
>         },
>         "delivery": {
>           "maxItems": 2,
>           "type": "array",
>           "items": {
>             "type": "string",
>             "enum": [
>               "shipping",
>               "pickup"
>             ]
>           }
>         },
>         "all_items_required": {
>           "type": [
>             "boolean",
>             "null"
>           ]
>         },
>         "price_limit": {
>           "anyOf": [
>             {
>               "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."
>             },
>             {
>               "type": "null"
>             }
>           ]
>         },
>         "items": {
>           "maxItems": 20,
>           "type": "array",
>           "items": {
>             "type": "object",
>             "properties": {
>               "item_id": {
>                 "description": "Leave out to add a new item.",
>                 "type": "string",
>                 "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,79}$"
>               },
>               "remove": {
>                 "description": "True to delete this item.",
>                 "type": "boolean",
>                 "const": true
>               },
>               "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": {
>                 "description": "Replaces this item’s 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
>                 }
>               },
>               "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": {
>                 "anyOf": [
>                   {
>                     "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."
>                   },
>                   {
>                     "type": "null"
>                   }
>                 ]
>               }
>             },
>             "additionalProperties": false
>           }
>         }
>       },
>       "additionalProperties": false,
>       "description": "Only the fields to change; null clears one."
>     },
>     "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_id",
>     "changes"
>   ],
>   "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"
>           ]
>         }
>       },
>       "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"
>       ],
>       "additionalProperties": {}
>     }
>   },
>   "required": [
>     "result"
>   ],
>   "additionalProperties": false
> }
> ```


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