Skip to main content
POST
Post Intent Find And Buy

Headers

X-Site-ID
string
required
authorization
string | null

Body

application/json

Agent → Stella: POST /api/agent/intent/find-and-buy.

Same semantics as find-and-add, plus a Stella-hosted checkout that the customer taps to pay. Stella NEVER charges the card on the agent's behalf — the customer is always the final approver. Phase 6 decision C2.

query
string
required
Required string length: 1 - 512
shipping_address
Shipping Address · object
required

Shipping address dict. Must contain at least first_name, last_name, address1, city, country. Phase 6-C2 v1 doesn't validate the schema strictly — it passes through to CheckoutService.create_checkout which stores it as-is on checkouts.shipping_address. Agents should pass what their LLM-tool-call schema produces.

quantity
integer
default:1
Required range: 1 <= x <= 10
max_unit_price_cents
integer | null
Required range: 0 <= x <= 10000000
email
string | null

Email for the order confirmation. Defaults to the agent's linked customer.email when omitted.

Response

Successful Response

Response shape for POST /api/agent/intent/find-and-buy.

requires_confirmation is always True — the agent MUST surface checkout_url to the customer for final approval. Auto-paying on the agent's behalf is explicitly out of scope (Phase 6 decision C2; revisit if regulators ever say it's safe).

cart
AgentCart · object
required

LLM-shape cart snapshot. Mirrors the storefront cart but in integer-cents currency and with summary_for_llm for the one-line agent-readable digest.

checkout_id
string<uuid>
required
checkout_url
string
required
summary
string
required
expires_in
integer
required

Seconds until the chk_ token in the URL fragment expires. After this, the customer's tap returns a 401 and the agent must re-issue.

total_cents
integer
required
currency
string
required
chosen
AgentCatalogProduct · object
required

LLM-shape product.

summary_for_llm is the single-paragraph natural-language summary an LLM can read to decide if this matches a user's intent. The structured fields below it are for follow-up calls (cart adds, detail renders) and reasoning attribution. Keep this shape FLAT — LLMs handle nesting poorly.

chosen_variant_id
string<uuid>
required
quantity_added
integer
required
match_reasons
string[]
required
requires_confirmation
boolean
default:true