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

# Change a Request

> Versioned owner edit. In changes, a field you leave out stays as it is and null clears it. Listing an item’s options replaces that item’s options. Preserve original ID/source. Changes invalidate context-dependent evidence and cluster membership conservatively.



## OpenAPI

````yaml /api-reference/openapi/requests.json patch /api/purchases/{id}
openapi: 3.1.0
info:
  title: 'Popular Demand Requests: Requests'
  version: 0.4.0
  x-api-version: '2026-11-20'
  description: >-
    List, save, read, change and close Requests, confirm the buyer still wants
    one, and propose an exact product. Index of all areas:
    https://populardemand.market/api/openapi. Versioning policy: [API
    versioning](https://docs.populardemand.market/api-reference/introduction).
    Every /api and MCP response carries an API-Version header (2026-11-20).
    API-Version identifies the contract served by this deployment; it is not
    version negotiation. The current version is 2026-11-20. Sending an
    API-Version request header does not select an older contract. We choose a
    new YYYY-MM-DD date for a breaking change. Adding optional fields, endpoints
    or tools is additive when existing valid requests and documented meanings
    stay unchanged; clients should tolerate unknown response fields. Removing or
    renaming fields, making optional input required, or changing existing field
    types, meanings or authorization requirements is breaking. During early
    access, breaking changes may ship without notice; each one is listed with
    its date in the version changes. Hourly quotas are per UTC hour; a refused
    request answers 429 with Retry-After, RateLimit and RateLimit-Policy headers
    (IETF draft-ietf-httpapi-ratelimit-headers-11, work in progress:
    https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers-11)
    and error.retry_after_seconds; a successful REST request that counted
    against a per-caller quota carries RateLimit and RateLimit-Policy with the
    allowance left. Errors may carry error.hint, the next step to take. Popular
    Demand Request API. Lists contain Request summaries; individual detail reads
    retain evidence diagnostics and history; recorded observations are
    operator-only. Purchase conditions first. Confirmed explicit all-in ceilings
    and exploration require no individual-option upload. Agent research may
    remain private. Buyer agents compare market prices themselves. Product
    resolution may follow capture. US/USD and IL/ILS only. Integer minor units;
    one canonical intent is not a guaranteed buyer. Every new intent has
    execution_available=false. baseline_diagnostics explains read-time evidence
    eligibility. Mutation retries may return historical cached results; read the
    root again when current evidence/version matters. Verified same-origin
    browser sessions are also accepted on owner REST endpoints; cookie writes
    require Origin. OAuth client tokens require the exact MCP audience and an
    approved Popular Demand grant.
servers:
  - url: https://populardemand.market
security: []
tags:
  - name: Requests
    description: >-
      List, save, read, change and close Requests, confirm the buyer still wants
      one, and propose an exact product.
paths:
  /api/purchases/{id}:
    patch:
      tags:
        - Requests
      summary: Change a Request
      description: >-
        Versioned owner edit. In changes, a field you leave out stays as it is
        and null clears it. Listing an item’s options replaces that item’s
        options. Preserve original ID/source. Changes invalidate
        context-dependent evidence and cluster membership conservatively.
      operationId: updateFuturePurchase
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Shared19'
        - name: Idempotency-Key
          in: header
          required: true
          description: >-
            Stable key for one logical write. 8–64 characters. Reusing it with
            different input returns 409.
          schema:
            type: string
            minLength: 8
            maxLength: 64
        - name: API-Version
          in: header
          required: false
          description: >-
            Current contract only; no version negotiation. See
            https://docs.populardemand.market/api-reference/introduction.
          schema:
            type: string
            default: '2026-11-20'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRequest'
            examples:
              illustrative:
                summary: >-
                  Illustrative input: replace request, source, IDs and versions;
                  never submit as real demand.
                value:
                  expected_version: 1
                  changes:
                    price_limit:
                      amount_minor: 180000
                      includes_delivery_and_tax: true
      responses:
        '200':
          description: >-
            Private result; no-store/noindex. No payment or executable order is
            implied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseView'
          headers:
            RateLimit:
              description: >-
                Present when this REST request counted against a per-caller
                hourly quota: the allowance left after it and seconds until the
                window resets, e.g. "write";r=19;t=1200. One list member per
                quota counted.
              schema:
                type: string
            RateLimit-Policy:
              description: >-
                Present with RateLimit: the quota counted, e.g.
                "write";q=20;w=3600. Quotas shared beyond the caller (every
                caller, one network or one OAuth client) are reported only when
                they refuse.
              schema:
                type: string
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '400':
          description: Invalid input / confirmation needed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '401':
          description: Verified identity or approved OAuth grant required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '403':
          description: >-
            forbidden: missing permission; origin_not_allowed: foreign browser
            origin at MCP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '404':
          description: Not accessible to this identity / capability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '409':
          description: Version, lifecycle or idempotency conflict; read current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '413':
          description: Request body exceeds 32 KB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '429':
          description: >-
            A rate or resource cap was reached. Timed quotas carry Retry-After,
            RateLimit and RateLimit-Policy; untimed resource caps carry no reset
            headers.
          headers:
            Retry-After:
              description: >-
                Present only for a timed quota refusal: seconds until the next
                attempt. Untimed resource caps do not carry this header.
              schema:
                type: integer
            RateLimit:
              description: >-
                Present only when an actual limiter reports a timed quota
                refusal. Remaining quota and reset, e.g. "write";r=0;t=1200.
              schema:
                type: string
            RateLimit-Policy:
              description: >-
                Present only for an actual timed quota. The quota refused, e.g.
                "write";q=20;w=3600.
              schema:
                type: string
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
        '500':
          description: Safe internal error; retry the same logical request key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
        '503':
          description: >-
            Required configuration unavailable, bounded transient database
            failure or a payment provider that did not execute the request. A
            transient response has explicit retry advice (retryable,
            retry_after_seconds) and a matching Retry-After header. Reuse the
            identical logical command and key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseError'
          headers:
            API-Version:
              description: >-
                The served contract version; request headers do not select a
                historical version.
              schema:
                type: string
                const: '2026-11-20'
      security:
        - OwnerBearer: []
components:
  schemas:
    Shared19:
      type: string
      format: uuid
      pattern: >-
        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
    UpdateRequest:
      type: object
      properties:
        expected_version:
          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:
              $ref: '#/components/schemas/Shared15'
            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:
                - $ref: '#/components/schemas/Shared6'
                - 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:
                      $ref: '#/components/schemas/Shared2'
                  terms:
                    $ref: '#/components/schemas/Shared13'
                  price_limit:
                    anyOf:
                      - $ref: '#/components/schemas/Shared7'
                      - type: 'null'
                additionalProperties: false
            expires_at:
              $ref: '#/components/schemas/Shared11'
          additionalProperties: false
      required:
        - changes
      additionalProperties: false
    PurchaseView:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        blockers:
          type: array
          items:
            type: string
        next_actions:
          $ref: '#/components/schemas/Shared21'
        as_of:
          $ref: '#/components/schemas/Shared11'
        buyer_status:
          type: object
          properties:
            state:
              type: string
              enum:
                - closed
                - ended
                - not_confirmed
                - paused
                - bought
                - offer_ready
                - details_needed
                - confirm_needed
                - asking_sellers
                - no_offer
                - offer_ended
                - gathering_interest
            label:
              type: string
            details:
              $ref: '#/components/schemas/Shared16'
            matching_confirmation_counts:
              anyOf:
                - type: object
                  properties:
                    person:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    agent:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    unknown:
                      type: integer
                      minimum: 0
                      maximum: 9007199254740991
                  required:
                    - person
                    - agent
                    - unknown
                  additionalProperties: false
                - type: 'null'
            message:
              description: >-
                The line the person sees under the status, or null. It can have
                several lines (one per saved item, then a sentence), separated
                by newlines. Show it as given.
              type:
                - string
                - 'null'
            matching_people:
              anyOf:
                - type: integer
                  minimum: 0
                  maximum: 9007199254740991
                - type: 'null'
              description: >-
                With gathering_interest only: the largest of
                item_counts[].people (null when none is a number). Counts only,
                never who; no threshold is published. Null in other states.
            item_counts:
              description: >-
                With gathering_interest only: for each saved item, the people
                (this person included) for whom one seller could make a single
                offer of that exact product: it is among every counted person's
                accepted options, with the same market and a delivery one seller
                can serve. The largest such group per item; groups tied for
                largest each get an entry, except groups of the same people,
                which share one entry listing each product (any of them could be
                offered). Groups are never added together. people is null when
                the only group is people nearby for pickup and fewer than 5
                others are nearby, none included (message then says so; exact
                small local counts are not shown, and an empty area reads like a
                sparse one). Counts only, never who. Null in other states.
              anyOf:
                - type: array
                  items:
                    type: object
                    properties:
                      need_id:
                        type: string
                      label:
                        type: string
                      products:
                        type: array
                        items:
                          type: object
                          properties:
                            namespace:
                              type: string
                            item_id:
                              type: string
                          required:
                            - namespace
                            - item_id
                          additionalProperties: false
                      people:
                        anyOf:
                          - type: integer
                            exclusiveMinimum: 0
                            maximum: 9007199254740991
                          - type: 'null'
                    required:
                      - need_id
                      - label
                      - products
                      - people
                    additionalProperties: false
                - type: 'null'
          required:
            - state
            - label
            - message
            - matching_people
          additionalProperties: false
        exact_item_confirmation:
          $ref: '#/components/schemas/Shared3'
        id:
          $ref: '#/components/schemas/Shared19'
        status:
          type: string
          enum:
            - draft
            - active
            - closed
        version:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        original_raw_request:
          type: string
        raw_request:
          type: string
        country:
          type: string
          pattern: ^[A-Z]{2}$
          enum:
            - US
            - IL
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          enum:
            - USD
            - ILS
        destination:
          type: object
          properties:
            city:
              type: string
              minLength: 1
              maxLength: 100
            region:
              type: string
              minLength: 1
              maxLength: 100
            zip:
              type: string
              pattern: ^[a-zA-Z0-9 -]{3,12}$
            scope:
              default: unknown
              type: string
              enum:
                - national_parcel
                - regional
                - unknown
            postal_code:
              type: string
              maxLength: 32
          required:
            - scope
          additionalProperties: false
        time_horizon:
          type:
            - string
            - 'null'
        need_by:
          $ref: '#/components/schemas/Shared9'
        items:
          type: array
          items:
            type: object
            properties:
              item_id:
                type: string
              description:
                type: string
              quantity:
                anyOf:
                  - type: integer
                    exclusiveMinimum: 0
                    maximum: 9007199254740991
                  - type: 'null'
              required:
                type: boolean
              confirmed:
                type: boolean
              options:
                type: array
                items:
                  type: object
                  properties:
                    option_id:
                      type: string
                    description:
                      type: string
                    product:
                      anyOf:
                        - type: object
                          properties:
                            namespace:
                              type: string
                              minLength: 1
                              maxLength: 200
                            item_id:
                              type: string
                              minLength: 1
                              maxLength: 200
                          required:
                            - namespace
                            - item_id
                          additionalProperties: false
                        - type: 'null'
                    attributes:
                      $ref: '#/components/schemas/Shared18'
                    url:
                      type: string
                      format: uri
                  required:
                    - option_id
                    - description
                    - product
                  additionalProperties: false
              terms:
                type: object
                properties:
                  warranty_months_min:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: 'null'
                  returns_days_min:
                    anyOf:
                      - type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      - type: 'null'
                  authorized_seller_required:
                    type:
                      - boolean
                      - 'null'
                required:
                  - warranty_months_min
                  - returns_days_min
                  - authorized_seller_required
                additionalProperties: false
            required:
              - item_id
              - description
              - quantity
              - required
              - confirmed
              - options
              - terms
            additionalProperties: false
        price_limits:
          type: array
          items:
            type: object
            properties:
              limit_id:
                type: string
              item_id:
                type:
                  - string
                  - 'null'
              includes_delivery_and_tax:
                type: boolean
              amount_minor:
                type: integer
                exclusiveMinimum: 0
                maximum: 9007199254740991
              currency:
                type: string
                pattern: ^[A-Z]{3}$
                enum:
                  - USD
                  - ILS
              set_at:
                $ref: '#/components/schemas/Shared11'
            required:
              - limit_id
              - item_id
              - includes_delivery_and_tax
              - amount_minor
              - currency
              - set_at
            additionalProperties: false
        delivery:
          type: array
          items:
            type: string
            enum:
              - shipping
              - pickup
        all_items_required:
          type:
            - boolean
            - 'null'
        resolution_status:
          type: string
          enum:
            - unresolved
            - proposed
            - resolved
        research_status:
          type: string
          enum:
            - needs_research
            - provisional
            - reviewed
        source:
          type: string
        created_via:
          type: string
          enum:
            - web
            - api
            - agent
            - email
        draft_agent:
          description: >-
            While this is a draft an email agent sent: that agent's mailbox,
            which activation can make a delegate for this Request. Null
            otherwise.
          type:
            - string
            - 'null'
        origin_client_id:
          anyOf:
            - type: string
              maxLength: 2048
            - type: 'null'
        created_at:
          $ref: '#/components/schemas/Shared11'
        updated_at:
          $ref: '#/components/schemas/Shared11'
        expires_at:
          $ref: '#/components/schemas/Shared11'
        activated_at:
          $ref: '#/components/schemas/Shared9'
        last_reaffirmed_at:
          $ref: '#/components/schemas/Shared9'
        closed_at:
          $ref: '#/components/schemas/Shared9'
        closed_reason:
          type:
            - string
            - 'null'
        observations:
          type: array
          items:
            $ref: '#/components/schemas/Shared1'
        baseline:
          anyOf:
            - $ref: '#/components/schemas/Shared1'
            - type: 'null'
        pricing:
          $ref: '#/components/schemas/Shared14'
        baseline_diagnostics:
          type: object
          properties:
            status:
              type: string
              enum:
                - usable
                - missing
                - blocked
            checked_at:
              $ref: '#/components/schemas/Shared11'
            baseline_id:
              anyOf:
                - $ref: '#/components/schemas/Shared19'
                - type: 'null'
            reason_codes:
              $ref: '#/components/schemas/Shared20'
            observations:
              type: array
              items:
                type: object
                properties:
                  observation_id:
                    $ref: '#/components/schemas/Shared19'
                  eligible:
                    type: boolean
                  reasons:
                    $ref: '#/components/schemas/Shared20'
                required:
                  - observation_id
                  - eligible
                  - reasons
                additionalProperties: false
            history_limit_reached:
              type: boolean
          required:
            - status
            - checked_at
            - baseline_id
            - reason_codes
            - observations
            - history_limit_reached
          additionalProperties: false
        execution_available:
          type: boolean
          const: false
        execution_note:
          type: string
        offer_email:
          type: object
          properties:
            request_enabled:
              type: boolean
            permitted:
              type: boolean
            questions_emailed:
              type: boolean
              description: >-
                Whether questions about this Request are emailed to the user.
                False while email updates for it are off: tell the user they
                could miss an offer, and answer questions you receive.
            consent_url:
              description: Owner-only URL.
              type:
                - string
                - 'null'
          required:
            - request_enabled
            - permitted
            - questions_emailed
            - consent_url
          additionalProperties: false
        reachability:
          type: array
          items:
            type: object
            properties:
              channel:
                type: string
                enum:
                  - email
                  - poll
              status:
                type: string
                enum:
                  - active
                  - revoked
              verified_at:
                $ref: '#/components/schemas/Shared9'
              expected_check_hours:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
              last_polled_at:
                $ref: '#/components/schemas/Shared9'
              last_delivered_at:
                $ref: '#/components/schemas/Shared9'
            required:
              - channel
              - status
              - verified_at
              - expected_check_hours
              - last_polled_at
              - last_delivered_at
            additionalProperties: false
        agent_events:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Shared19'
              event_name:
                type: string
                enum:
                  - request.research_updated
                  - request.plan_prepared
                  - request.plan_context_changed
                  - request.question_asked
                  - request.payment_updated
              status:
                type: string
                enum:
                  - active
                  - revoked
              expires_at:
                $ref: '#/components/schemas/Shared11'
              last_delivered_at:
                $ref: '#/components/schemas/Shared9'
            required:
              - id
              - event_name
              - status
              - expires_at
              - last_delivered_at
            additionalProperties: false
        polling_access:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Shared19'
              expires_at:
                $ref: '#/components/schemas/Shared11'
              last_polled_at:
                $ref: '#/components/schemas/Shared9'
            required:
              - id
              - expires_at
              - last_polled_at
            additionalProperties: false
        email_delivery:
          type: string
          enum:
            - local_inbox
            - configured
            - unconfigured
        history:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              occurred_at:
                $ref: '#/components/schemas/Shared11'
              payload:
                type: object
                propertyNames:
                  type: string
                additionalProperties: {}
            required:
              - type
              - occurred_at
              - payload
            additionalProperties: false
        compatible_demand:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Shared19'
              title:
                type: string
              compatibility_rule:
                type: string
              geography_scope:
                type: string
              active_intents:
                type: string
              count_kind:
                type: string
                const: active_requests
              executable_units:
                type: number
                const: 0
              observed_at:
                $ref: '#/components/schemas/Shared11'
            required:
              - id
              - title
              - compatibility_rule
              - geography_scope
              - active_intents
              - count_kind
              - executable_units
              - observed_at
            additionalProperties: false
        possible_duplicate_of:
          description: >-
            Open Requests of the same owner that closely match this new one: the
            same exact product references, the same top Need option set or the
            same words, with an overlapping destination. The new Request was
            saved anyway. If one is for the same thing, ask the person which to
            keep, then update or close the other so they are counted once.
          maxItems: 5
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Shared19'
              match:
                type: string
                enum:
                  - same_products
                  - same_options
                  - same_text
            required:
              - id
              - match
            additionalProperties: false
        duplicate_hint:
          type:
            - string
            - 'null'
        save_confirmation:
          type: object
          properties:
            saved:
              type: boolean
              const: true
            status:
              type: string
              enum:
                - draft
                - active
                - closed
            counts_as:
              type: string
              enum:
                - interest_with_price_limit
                - interest_only
            message:
              type: string
            order_created:
              type: boolean
              const: false
            payment_taken:
              type: boolean
              const: false
            deal_promised:
              type: boolean
              const: false
          required:
            - saved
            - status
            - counts_as
            - message
            - order_created
            - payment_taken
            - deal_promised
          additionalProperties: false
        needs_attention:
          type: array
          items:
            type: string
            enum:
              - new_offer
              - open_question
              - details_needed
              - still_want
              - offer_ending
        attention:
          $ref: '#/components/schemas/Shared10'
        next_step:
          description: The one next step, or null.
          type:
            - string
            - 'null'
        message:
          description: What to tell the person.
          type: string
        agent_line:
          description: What the agent does next.
          type: string
        open_questions:
          description: >-
            Questions to answer with POST /api/purchases/{id}/answers before
            their deadline.
          type: array
          items:
            type: object
            propertyNames:
              type: string
            additionalProperties: {}
        notifications:
          type: object
          properties:
            request_id:
              type:
                - string
                - 'null'
            offer_alerts:
              type:
                - boolean
                - 'null'
            check_frequency:
              type: string
            check_channels:
              type: string
            agent_reachability:
              type: array
              items:
                type: object
                properties:
                  channel:
                    type: string
                  enabled:
                    type: boolean
                  expected_check_hours:
                    type:
                      - number
                      - 'null'
                required:
                  - channel
                  - enabled
                  - expected_check_hours
                additionalProperties: false
          required:
            - request_id
            - offer_alerts
            - check_frequency
            - check_channels
            - agent_reachability
          additionalProperties: false
        supplier_text_is_untrusted:
          type: boolean
          const: true
        untrusted_text_fields:
          maxItems: 20
          type: array
          items:
            type: string
      required:
        - blockers
        - next_actions
        - as_of
        - id
        - status
        - version
        - original_raw_request
        - raw_request
        - country
        - currency
        - destination
        - time_horizon
        - need_by
        - items
        - price_limits
        - delivery
        - all_items_required
        - resolution_status
        - research_status
        - source
        - created_via
        - origin_client_id
        - created_at
        - updated_at
        - expires_at
        - activated_at
        - last_reaffirmed_at
        - closed_at
        - closed_reason
        - observations
        - baseline
        - pricing
        - baseline_diagnostics
        - execution_available
        - execution_note
        - reachability
        - agent_events
        - polling_access
        - email_delivery
        - history
        - compatible_demand
      additionalProperties: false
    PurchaseError:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
            retryable:
              type: boolean
              const: true
            retry_after_seconds:
              type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            hint:
              type: string
            errors:
              maxItems: 20
              type: array
              items:
                type: object
                properties:
                  path:
                    type: string
                  message:
                    type: string
                required:
                  - path
                  - message
                additionalProperties: false
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    Shared15:
      anyOf:
        - $ref: '#/components/schemas/Shared17'
        - type: 'null'
    Shared6:
      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.
    Shared2:
      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:
          $ref: '#/components/schemas/Shared5'
      required:
        - description
      additionalProperties: false
    Shared13:
      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
    Shared7:
      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.
    Shared11:
      type: string
      format: date-time
      pattern: >-
        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
    Shared21:
      type: array
      items:
        type: object
        properties:
          code:
            type: string
          actor:
            type: string
          message:
            type: string
        required:
          - code
          - actor
          - message
        additionalProperties: false
    Shared16:
      description: >-
        With details_needed only: item (the exact item, quantity or delivery
        method is missing) or pickup_only (it accepts only pickup, which is not
        arranged for now; add delivery, with the user’s say-so, to have it
        counted).
      type: string
      enum:
        - item
        - pickup_only
    Shared3:
      anyOf:
        - $ref: '#/components/schemas/Shared4'
        - type: 'null'
    Shared9:
      anyOf:
        - $ref: '#/components/schemas/Shared11'
        - type: 'null'
    Shared18:
      maxItems: 20
      type: array
      items:
        $ref: '#/components/schemas/Shared22'
    Shared1:
      type: object
      properties:
        outcome_description:
          type: string
          minLength: 3
          maxLength: 500
        item_minor:
          default: null
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 100000000
            - type: 'null'
        shipping_minor:
          default: null
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100000000
            - type: 'null'
        tax_minor:
          default: null
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100000000
            - type: 'null'
        duties_minor:
          default: null
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100000000
            - type: 'null'
        total_minor:
          default: null
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 100000000
            - type: 'null'
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          enum:
            - USD
            - ILS
        source_url:
          type: string
          maxLength: 2000
          format: uri
        seller_name:
          type: string
          minLength: 1
          maxLength: 200
        observed_at:
          $ref: '#/components/schemas/Shared11'
        valid_until:
          $ref: '#/components/schemas/Shared11'
        availability:
          type: string
          enum:
            - available
            - unavailable
            - unknown
        terms:
          $ref: '#/components/schemas/Shared8'
        confidence_note:
          type: string
          minLength: 10
          maxLength: 2000
        id:
          $ref: '#/components/schemas/Shared19'
        review_status:
          type: string
          enum:
            - provisional
            - verified
            - rejected
      required:
        - outcome_description
        - item_minor
        - shipping_minor
        - tax_minor
        - duties_minor
        - total_minor
        - currency
        - source_url
        - seller_name
        - observed_at
        - valid_until
        - availability
        - terms
        - confidence_note
        - id
        - review_status
      additionalProperties: {}
    Shared14:
      type: object
      properties:
        status:
          type: string
          enum:
            - exploratory
            - price_specified
        amount_minor:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            - type: 'null'
        label:
          type: string
      required:
        - status
        - amount_minor
      additionalProperties: false
    Shared20:
      type: array
      items:
        type: string
        enum:
          - context_changed
          - future_observation
          - superseded
          - needs_review
          - rejected
          - not_comparable
          - incomplete_total
          - unavailable
          - availability_unknown
          - expired
    Shared10:
      description: Each needs_attention flag in words.
      type: array
      items:
        $ref: '#/components/schemas/Shared12'
    Shared17:
      type: string
      format: date
      pattern: >-
        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
    Shared5:
      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:
          $ref: '#/components/schemas/Shared18'
      additionalProperties: false
    Shared4:
      type: object
      properties:
        confirmed_by:
          type: string
          enum:
            - person
            - agent
        confirmed_at:
          $ref: '#/components/schemas/Shared11'
        request_version:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
      required:
        - confirmed_by
        - confirmed_at
        - request_version
      additionalProperties: false
    Shared22:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        value:
          type: string
          minLength: 1
          maxLength: 100
      required:
        - name
        - value
      additionalProperties: false
    Shared8:
      type: object
      properties:
        warranty:
          type: string
          maxLength: 2000
        returns:
          type: string
          maxLength: 2000
        delivery:
          type: string
          maxLength: 2000
        legitimacy:
          type: string
          maxLength: 2000
        comparable:
          default: false
          type: boolean
        all_in_confirmed:
          default: false
          type: boolean
      required:
        - warranty
        - returns
        - delivery
        - legitimacy
        - comparable
        - all_in_confirmed
      additionalProperties: false
    Shared12:
      type: object
      properties:
        flag:
          type: string
          enum:
            - new_offer
            - open_question
            - details_needed
            - still_want
            - offer_ending
            - request_ending
        message:
          type:
            - string
            - 'null'
        agent_line:
          type:
            - string
            - 'null'
      required:
        - flag
        - message
        - agent_line
      additionalProperties: false
  securitySchemes:
    OwnerBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        An OAuth access token for the buyer resource (audience, issuer and
        signature checked). Its scopes and the active grant the person approved
        are both enforced.

````

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