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

# Record whether an Offer fits

> Record a confirmed pre-check of one exact owned Offer and Request version: fits, needs_user or does_not_fit. Requires a stable Idempotency-Key and, for OAuth agents, offer_fit permission and this Request in scope. A conflict requires a fresh read and user reconciliation. This records intent only; it never accepts an Offer, orders or pays. Price limits never grant spending authority.



## OpenAPI

````yaml /api-reference/openapi/offers.json post /api/purchases/{id}/offers/{offerId}/validation
openapi: 3.1.0
info:
  title: 'Popular Demand Requests: Offers'
  version: 0.4.0
  x-api-version: '2026-11-20'
  description: >-
    Read a Request's Offers and record whether one fits. 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: Offers
    description: Read a Request's Offers and record whether one fits.
paths:
  /api/purchases/{id}/offers/{offerId}/validation:
    post:
      tags:
        - Offers
      summary: Record whether an Offer fits
      description: >-
        Record a confirmed pre-check of one exact owned Offer and Request
        version: fits, needs_user or does_not_fit. Requires a stable
        Idempotency-Key and, for OAuth agents, offer_fit permission and this
        Request in scope. A conflict requires a fresh read and user
        reconciliation. This records intent only; it never accepts an Offer,
        orders or pays. Price limits never grant spending authority.
      operationId: validateOffer
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Shared38'
        - name: offerId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Shared38'
        - 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:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                expected_offer_version:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                expected_request_version:
                  type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                verdict:
                  type: string
                  enum:
                    - fits
                    - needs_user
                    - does_not_fit
                  description: >-
                    fits: this exact Offer version matches the user's current
                    intent as you understand it. needs_user: you must ask the
                    user before deciding (for example a price above their stated
                    limit, or a changed term). does_not_fit: it does not match;
                    the Offer stops counting for this buyer.
                reason_code:
                  description: Optional main reason for needs_user or does_not_fit.
                  type: string
                  enum:
                    - price
                    - quantity
                    - product
                    - terms
                    - delivery
                    - timing
                    - seller
                    - other
                note:
                  description: >-
                    Optional short private note for the user. Never include
                    payment details.
                  type: string
                  minLength: 1
                  maxLength: 280
              required:
                - expected_offer_version
                - expected_request_version
                - verdict
              additionalProperties: false
      responses:
        '200':
          description: >-
            Private result; no-store/noindex. No payment or executable order is
            implied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferValidationReceipt'
          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:
    Shared38:
      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)$
    OfferValidationReceipt:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        validation:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/Shared38'
            offer_id:
              $ref: '#/components/schemas/Shared38'
            offer_version:
              type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            request_id:
              $ref: '#/components/schemas/Shared38'
            request_version:
              type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            owner_id:
              $ref: '#/components/schemas/Shared38'
            verdict:
              type: string
              enum:
                - fits
                - needs_user
                - does_not_fit
            reason_code:
              anyOf:
                - type: string
                  enum:
                    - price
                    - quantity
                    - product
                    - terms
                    - delivery
                    - timing
                    - seller
                    - other
                - type: 'null'
            note:
              type:
                - string
                - 'null'
            transport:
              type: string
              enum:
                - web
                - api
                - agent
                - email_agent
            agent_client_id:
              type:
                - string
                - 'null'
            recorded_at:
              $ref: '#/components/schemas/Shared23'
          required:
            - id
            - offer_id
            - offer_version
            - request_id
            - request_version
            - owner_id
            - verdict
            - reason_code
            - note
            - transport
            - agent_client_id
            - recorded_at
          additionalProperties: false
        demand:
          $ref: '#/components/schemas/Shared2'
        execution:
          type: object
          properties:
            mode:
              type: string
              enum:
                - authorization_hold
                - seller_price_guarantee
            money_backed:
              $ref: '#/components/schemas/Shared37'
            buyer_commits:
              type: string
            checkout:
              type: string
              enum:
                - popular_demand
                - seller
            terms_version:
              type: string
              enum:
                - c3_c5_v1
                - spg_v1
                - spg_v2
            deal:
              $ref: '#/components/schemas/Shared6'
          required:
            - mode
            - money_backed
            - buyer_commits
            - checkout
            - terms_version
          additionalProperties: false
        execution_available:
          type: boolean
          const: false
        message:
          description: What to tell the person.
          type: string
        agent_line:
          description: What the agent does next.
          type: string
      required:
        - validation
        - demand
        - execution_available
      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
    Shared23:
      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)))$
    Shared2:
      type: object
      properties:
        state:
          type: string
          enum:
            - not_counted
            - potential
            - validated
            - needs_user
            - committed
        reasons:
          type: array
          items:
            type: string
        price_qualified:
          type: boolean
          description: >-
            Label only: the stated price policy qualifies this price. Not
            authorization.
        price_position:
          $ref: '#/components/schemas/Shared24'
        above_limit_by_minor:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            - type: 'null'
        price_position_reason:
          $ref: '#/components/schemas/Shared17'
        request_committed_total_minor:
          description: >-
            Applies only to an Offer made while Popular Demand offered payment
            holds; otherwise 0.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        request_limit_minor:
          $ref: '#/components/schemas/Shared29'
        above_request_limit_by_minor:
          $ref: '#/components/schemas/Shared35'
        request_total_with_offer_minor:
          $ref: '#/components/schemas/Shared32'
        above_request_limit_with_offer_by_minor:
          $ref: '#/components/schemas/Shared26'
        agent_reason_code:
          anyOf:
            - type: string
              enum:
                - price
                - quantity
                - product
                - terms
                - delivery
                - timing
                - seller
                - other
            - type: 'null'
        validated_at:
          $ref: '#/components/schemas/Shared21'
        hold:
          $ref: '#/components/schemas/Shared16'
        payment_hold_available:
          type: boolean
          description: >-
            Applies only to an Offer made while Popular Demand offered payment
            holds; otherwise false.
        payment_hold_resumable:
          type: boolean
          description: >-
            Applies only to an Offer made while Popular Demand offered payment
            holds; otherwise false.
        payment_hold_opens_at:
          $ref: '#/components/schemas/Shared19'
        payment_hold_reauthorization:
          $ref: '#/components/schemas/Shared10'
      required:
        - state
        - reasons
        - price_qualified
        - price_position
        - above_limit_by_minor
        - agent_reason_code
        - validated_at
        - hold
        - payment_hold_available
        - payment_hold_resumable
        - payment_hold_opens_at
        - payment_hold_reauthorization
      additionalProperties: false
      description: >-
        Derived demand state: potential (fits the outcome), validated (the buyer
        agent's latest pre-check of this exact Offer version said fits),
        needs_user (the agent must ask the user), committed (an authorized card
        payment, only on an Offer made while Popular Demand offered payment
        holds). not_counted means no current claim, never a refusal unless
        reasons say the agent declined. Price position is a label, never a gate.
    Shared37:
      type: boolean
      description: >-
        True only for authorization_hold, on an Offer made while Popular Demand
        offered payment holds; false for a group-price Offer, where no buyer
        money passes through Popular Demand.
    Shared6:
      type: object
      properties:
        status:
          type: string
          enum:
            - open
            - ended
        ended_reason:
          anyOf:
            - type: string
              enum:
                - sold_out
                - date_passed
            - type: 'null'
        available_until:
          type:
            - string
            - 'null'
        link:
          $ref: '#/components/schemas/Shared41'
        code:
          description: >-
            What the buyer enters in the discount field at the seller’s
            checkout, if anything.
          type:
            - string
            - 'null'
        link_shows_code:
          description: >-
            Present when the link shows the buyer their own code to enter at the
            seller’s checkout, instead of opening the seller’s page.
          type: boolean
          const: true
        units_left:
          description: >-
            Present only when the price has a unit limit: the units still free
            now.
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - status
        - ended_reason
        - available_until
        - link
        - code
      additionalProperties: false
    Shared24:
      anyOf:
        - type: string
          enum:
            - no_limit
            - within_limit
            - above_limit
            - unknown
        - type: 'null'
      description: >-
        Label only: the current all-in price against the Request’s ceilings.
        Null without a current evaluation. unknown means a limit exists but
        cannot be compared yet (see price_position_reason). above_limit Offers
        are still delivered.
    Shared17:
      anyOf:
        - $ref: '#/components/schemas/Shared20'
        - type: 'null'
    Shared29:
      description: >-
        Label only: the tightest whole-Request all-in limit (the root price or a
        basket all-in ceiling). Null when the person has not set one.
      anyOf:
        - type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        - type: 'null'
    Shared35:
      description: >-
        Label only: how far the committed total exceeds the limit (0 when within
        it, null without a limit). Never a gate.
      anyOf:
        - type: integer
          minimum: 0
          maximum: 9007199254740991
        - type: 'null'
    Shared32:
      description: >-
        Label only: request_committed_total_minor plus this Offer's current
        all-in amount. Null when the all-in amount is unknown.
      anyOf:
        - type: integer
          minimum: 0
          maximum: 9007199254740991
        - type: 'null'
    Shared26:
      description: >-
        Label only: how far request_total_with_offer_minor would exceed the
        whole-Request limit (0 when within it, null without a limit or a known
        total). Never a gate.
      anyOf:
        - type: integer
          minimum: 0
          maximum: 9007199254740991
        - type: 'null'
    Shared21:
      anyOf:
        - $ref: '#/components/schemas/Shared23'
        - type: 'null'
    Shared16:
      anyOf:
        - $ref: '#/components/schemas/Shared18'
        - type: 'null'
    Shared19:
      anyOf:
        - $ref: '#/components/schemas/Shared23'
        - type: 'null'
      description: >-
        Applies only to an Offer made while Popular Demand offered payment
        holds; otherwise null.
    Shared10:
      anyOf:
        - $ref: '#/components/schemas/Shared11'
        - type: 'null'
      description: >-
        Applies only to an Offer made while Popular Demand offered payment
        holds; otherwise null.
    Shared41:
      description: >-
        This buyer’s own link to the seller’s deal page; give it only to the
        user. Popular Demand counts visits and, for a linked store, paid orders
        that used its codes.
      type:
        - string
        - 'null'
    Shared20:
      type: string
      enum:
        - all_in_cost_unknown
        - cost_scope_unknown
        - currency_mismatch
        - variant_price_unknown
      description: >-
        Why a limit cannot be compared yet: all_in_cost_unknown (some delivery,
        tax, duty or fee amount is missing), cost_scope_unknown (the seller did
        not split costs per item for a per-item all-in limit), currency_mismatch
        (a limit uses another currency) or variant_price_unknown (the store’s
        price for the size, colour or version the person chose is not known).
    Shared18:
      type: object
      properties:
        placed_at:
          $ref: '#/components/schemas/Shared23'
        simulated:
          type: boolean
      required:
        - placed_at
        - simulated
      additionalProperties: false
    Shared11:
      type: object
      properties:
        offer_version:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        kind:
          type: string
          enum:
            - lapse
            - capture_refused
        reauthorize_by:
          $ref: '#/components/schemas/Shared23'
      required:
        - offer_version
        - kind
        - reauthorize_by
      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.