Skip to main content
POST
Record whether an Offer fits

Authorizations

Authorization
string
header
required

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.

Headers

Idempotency-Key
string
required

Stable key for one logical write. 8–64 characters. Reusing it with different input returns 409.

Required string length: 8 - 64
API-Version
string
default:2026-11-20

Current contract only; no version negotiation. See https://docs.populardemand.market/api-reference/introduction.

Path Parameters

id
string<uuid>
required
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)$
offerId
string<uuid>
required
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)$

Body

application/json
expected_offer_version
integer
required
Required range: x <= 9007199254740991
expected_request_version
integer
required
Required range: x <= 9007199254740991
verdict
enum<string>
required

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.

Available options:
fits,
needs_user,
does_not_fit
reason_code
enum<string>

Optional main reason for needs_user or does_not_fit.

Available options:
price,
quantity,
product,
terms,
delivery,
timing,
seller,
other
note
string

Optional short private note for the user. Never include payment details.

Required string length: 1 - 280

Response

Private result; no-store/noindex. No payment or executable order is implied.

validation
object
required
demand
object
required

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.

execution_available
boolean
required
execution
object
message
string

What to tell the person.

agent_line
string

What the agent does next.