Skip to main content
Negotiations are Tavryn’s core output. When the agent detects a savings opportunity on a contract — idle seats, usage decline, or an approaching renewal — it opens a negotiation and runs a multi-round back-and-forth with the vendor simulator (or a real vendor contact). Each negotiation tracks every round, the current offer on the table, the target price Tavryn is working toward, and any reviewer verdict. You can inspect, influence, and close negotiations programmatically through the endpoints below.

The Negotiation Object

The following fields appear in negotiation responses across all endpoints.
string
UUID of the negotiation record.
string
UUID of the contract this negotiation is tied to.
string
Current lifecycle state of the negotiation. One of:
number
Number of offer-counter-offer cycles completed so far.
number
The most recent price Tavryn put on the table (in USD).
number
The price Tavryn is aiming to close at, derived from the waste heuristic and market benchmarks.
number
Projected or confirmed annual savings in USD (original_price - final_price).
string | null
Human reviewer decision when the negotiation entered pending_review or pending_approval. One of:

How Negotiations Start

You do not need to open negotiations manually. Tavryn triggers them in two ways:
  1. Daily cron — Tavryn’s procurement engine runs every day, scans all active contracts approaching renewal, scores them for savings potential using seat-optimization and usage-decline heuristics, and opens negotiations autonomously.
  2. On-demand via POST /api/agent/run-now — You can trigger an immediate scan for a specific business (or all businesses) at any time. See the Agent API for details.
To start a negotiation directly against a single contract, use POST /api/agent/negotiate/{contractId}.

Get Negotiation Status

Retrieve the current negotiation state, full contract record, and vendor memory for a contract.

Path Parameters

string
required
UUID of the contract whose negotiation status you want to retrieve.

Response

boolean
true if an active or historical negotiation record exists for this contract.
object | null
The negotiation object as described above, or null if no negotiation has been opened yet.
object
The full contract record including the linked vendor.
object | null
Tavryn’s vendor memory for this business — prior negotiation outcomes, concession patterns, and relationship context used to calibrate future offers.

Example Response


Start or Advance a Negotiation

Open a new negotiation or push an existing one forward by submitting a new round with optional parameter overrides.
This endpoint is rate-limited to 20 requests per minute per contract. Exceeding the limit returns HTTP 429 with a resetMs field indicating when the window resets.

Path Parameters

string
required
UUID of the contract to negotiate.

Request Body

All body fields are optional. Omitting them lets Tavryn use its default negotiation strategy.
number
Maximum number of offer-counter-offer rounds before the agent walks away. Integer between 1 and 20. Defaults to the agent’s internal strategy setting.
number
Maximum price (in USD) Tavryn will accept before abandoning the negotiation. Must be a positive number. Use this to enforce hard budget caps.
number
Explicit target price (in USD) you want Tavryn to negotiate toward. Overrides the heuristic-derived target.

Response

object
The outcome of the negotiation loop, including the final round state, accepted flag, vendor counter message, and updated savings figures.

Example Request


Draft Vendor Outreach Email

Generate a professional outreach email to kick off a negotiation with a real vendor contact.

Path Parameters

string
required
UUID of the contract for which to draft outreach.

Response

object
The generated email draft, including subject line, body text, and the vendor contact address Tavryn resolved from the contract record.

Example Response


Submit a Vendor Reply

Feed a vendor’s email response back into Tavryn so the agent can parse their position, update the negotiation state, and formulate the next offer.

Path Parameters

string
required
UUID of the contract the reply pertains to.

Request Body

The endpoint accepts both JSON and multipart/form-data (for email webhook ingestion). In form-data payloads, Tavryn looks for rawReply, text, body, or html fields.
string
required
The raw text of the vendor’s reply. Cannot be empty.
boolean
Set to true to manually signal that the vendor has agreed to accept payment in USDC on the Arc network, bypassing the AI’s extraction of that consent from the reply text.

Response

object
The parsed reply outcome — detected counter-offer price, sentiment classification, updated negotiation status, and the next action Tavryn will take.

Record Off-Chain Savings

Manually record a negotiated saving when the deal was closed outside Tavryn (phone call, direct email, etc.) without an on-chain USDC payment.

Path Parameters

string
required
UUID of the contract where savings were achieved.

Request Body

string
required
UUID of the negotiation record to close out.
number
required
The agreed final annual price in USD. Must be positive.
string
Optional free-text note explaining how the deal was closed (e.g., "Agreed over phone with account manager").

Response

object
Confirmation that the negotiation has been marked completed, the savings amount recorded, and the contract’s current_price updated.

Example Request

Example Response