Buyers’ price offers: what the agent decided and what it did not

Buyers propose prices on the marketplace. The stored floor price is the agent’s only basis for negotiation. If there is no floor price for an item, it does not decide on a price offer but hands it over to a human. These handed-over offers are the work queue — and they lapse if nobody looks at them.

The inbox offer list shows price offers with the decision the agent made — or without a decision if it handed the offer over. Where it decided, decisionPriceCents gives the price where available. The needs_human filter narrows it to what a human has to decide.

What this case requires

• A marketplace channel with consent granted. Without it no price offers reach the agent.
• Stored floor prices. They are the agent’s only basis for negotiation; without them it does not decide.
• Someone who checks the filter regularly. An offer carries an expiry date.
• A line on counter-offers. How far a colleague goes below the floor price is a commercial decision, not a technical one.

The sequence

The table names the responsible call per stage and what exists afterwards. The reasoning for why a stage cannot be skipped follows below it.

Why each stage is needed

1. Look up the floor prices. GET /agent/items/prices lists minPriceCents per itemKey with updatedAt. Before a colleague judges an offer, they see the basis on which the agent would have decided — and whether that basis is still current.
2. Filter the open offers. GET /agent/inbox/offers knows status with pending, decided and needs_human. Each offer carries itemPriceCents, offerPriceCents, expiresAt, decision with accept, decline, counter, record or handoff, and where applicable decisionPriceCents.
3. Read the conversation. GET /agent/inbox/conversations/{conversationId} shows the history with actions, findings and suggestedReply. That way the colleague sees the history before replying.
4. Reply. POST /agent/inbox/conversations/{conversationId}/reply requires the conversation to have been taken over first with POST /agent/inbox/conversations/{conversationId}/takeover, and returns deliveryStatus. On a mailbox or marketplace channel the reply is queued for delivery; on the website it counts as delivered at once.
5. Mark as read. POST /agent/inbox/conversations/{conversationId}/read resets unreadCount. That sounds minor but keeps the work queue honest: what is read and answered disappears from the view of those looking for open items.

curl -H 'X-Api-Key: <API_KEY>' \
  'https://api.tapinomahub.com/hub/index.php/agent/inbox/offers?status=needs_human&limit=25'

What you end up with

In the end every price offer has a decision — from the agent where the floor price supports it, and from a colleague where it does not. No offer lapses because it sat in the wrong list.

Where to find this in the documentation

The binding field lists, error codes and sample responses live in this surface’s OpenAPI contract at docs.tapinomahub.com (tapinoma-agent). All use cases arranged by surface and role: overview of the use cases.