> ## Documentation Index > Fetch the complete documentation index at: https://docs.stella-commerce.com/llms.txt > Use this file to discover all available pages before exploring further. # Post Intent Find And Buy > find-and-add + create a Stella-hosted checkout the customer taps to pay. Returns `{checkout_url, requires_confirmation: true}`. Stella NEVER auto-pays — the customer is always the final approver. Phase 6 decision C2. Budget consumption happens at ORDER creation in `CheckoutFinalizer.finalize` (decision A5), NOT here. The pre-flight 402 catches obvious cap breaches early but doesn't reserve budget — this means an agent COULD create N checkouts that cumulatively exceed the cap, but only the ones the customer actually pays for consume budget. ## OpenAPI ````yaml /api-reference/openapi.json post /api/agent/intent/find-and-buy openapi: 3.1.0 info: title: Agentic Commerce API description: |2- Agentic Commerce API - E-commerce Backend ## APIs ### Dashboard API (`/api/dashboard`) Authenticated endpoints for merchant management: - Products, Variants, Options - Inventory management - Orders and fulfillment - Customers - Collections ### Storefront API (`/api/storefront`) Public endpoints for client websites: - Product catalog - Collections - Cart management - Checkout ### Sync API (`/api/sync`) Integration endpoints for zunkiree-search: - Product sync - Availability checks - Order creation from AI widget version: 1.0.0 servers: [] security: [] paths: /api/agent/intent/find-and-buy: post: tags: - Agent - Agent Intent summary: Post Intent Find And Buy description: |- find-and-add + create a Stella-hosted checkout the customer taps to pay. Returns `{checkout_url, requires_confirmation: true}`. Stella NEVER auto-pays — the customer is always the final approver. Phase 6 decision C2. Budget consumption happens at ORDER creation in `CheckoutFinalizer.finalize` (decision A5), NOT here. The pre-flight 402 catches obvious cap breaches early but doesn't reserve budget — this means an agent COULD create N checkouts that cumulatively exceed the cap, but only the ones the customer actually pays for consume budget. operationId: post_intent_find_and_buy_api_agent_intent_find_and_buy_post parameters: - name: X-Site-ID in: header required: true schema: type: string title: X-Site-Id - name: authorization in: header required: false schema: anyOf: - type: string - type: 'null' title: Authorization requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentIntentFindAndBuyBody' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentIntentFindAndBuyResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: AgentIntentFindAndBuyBody: properties: query: type: string maxLength: 512 minLength: 1 title: Query quantity: type: integer maximum: 10 minimum: 1 title: Quantity default: 1 max_unit_price_cents: anyOf: - type: integer maximum: 10000000 minimum: 0 - type: 'null' title: Max Unit Price Cents shipping_address: additionalProperties: true type: object title: Shipping Address description: >- 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. email: anyOf: - type: string - type: 'null' title: Email description: >- Email for the order confirmation. Defaults to the agent's linked customer.email when omitted. type: object required: - query - shipping_address title: AgentIntentFindAndBuyBody description: |- 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. AgentIntentFindAndBuyResponse: properties: cart: $ref: '#/components/schemas/AgentCart' checkout_id: type: string format: uuid title: Checkout Id checkout_url: type: string title: Checkout Url summary: type: string title: Summary expires_in: type: integer title: Expires In description: >- 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: type: integer title: Total Cents currency: type: string title: Currency requires_confirmation: type: boolean title: Requires Confirmation default: true chosen: $ref: '#/components/schemas/AgentCatalogProduct' chosen_variant_id: type: string format: uuid title: Chosen Variant Id quantity_added: type: integer title: Quantity Added match_reasons: items: type: string type: array title: Match Reasons type: object required: - cart - checkout_id - checkout_url - summary - expires_in - total_cents - currency - chosen - chosen_variant_id - quantity_added - match_reasons title: AgentIntentFindAndBuyResponse description: |- 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). HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AgentCart: properties: id: type: string format: uuid title: Id currency: type: string title: Currency items: items: $ref: '#/components/schemas/AgentCartLineItem' type: array title: Items subtotal_cents: type: integer title: Subtotal Cents item_count: type: integer title: Item Count summary_for_llm: type: string title: Summary For Llm type: object required: - id - currency - items - subtotal_cents - item_count - summary_for_llm title: AgentCart description: |- 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. AgentCatalogProduct: properties: id: type: string format: uuid title: Id name: type: string title: Name slug: anyOf: - type: string - type: 'null' title: Slug description: anyOf: - type: string - type: 'null' title: Description vendor: anyOf: - type: string - type: 'null' title: Vendor product_type: anyOf: - type: string - type: 'null' title: Product Type tags: items: type: string type: array title: Tags image_url: anyOf: - type: string - type: 'null' title: Image Url price_min_cents: type: integer title: Price Min Cents price_max_cents: type: integer title: Price Max Cents currency: type: string title: Currency in_stock: type: boolean title: In Stock total_inventory: type: integer title: Total Inventory variant_count: type: integer title: Variant Count variants: items: $ref: '#/components/schemas/AgentCatalogVariant' type: array title: Variants summary_for_llm: type: string title: Summary For Llm type: object required: - id - name - slug - description - vendor - product_type - tags - image_url - price_min_cents - price_max_cents - currency - in_stock - total_inventory - variant_count - variants - summary_for_llm title: AgentCatalogProduct description: |- 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. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError AgentCartLineItem: properties: variant_id: type: string format: uuid title: Variant Id product_id: type: string format: uuid title: Product Id product_name: type: string title: Product Name variant_name: anyOf: - type: string - type: 'null' title: Variant Name sku: anyOf: - type: string - type: 'null' title: Sku quantity: type: integer title: Quantity price_cents: type: integer title: Price Cents line_total_cents: type: integer title: Line Total Cents type: object required: - variant_id - product_id - product_name - quantity - price_cents - line_total_cents title: AgentCartLineItem description: |- LLM-shape cart line. Fields chosen so an agent can render a confirmation message without a follow-up product fetch. AgentCatalogVariant: properties: id: type: string format: uuid title: Id title: type: string title: Title sku: anyOf: - type: string - type: 'null' title: Sku price_cents: type: integer title: Price Cents options: additionalProperties: true type: object title: Options inventory_quantity: type: integer title: Inventory Quantity in_stock: type: boolean title: In Stock type: object required: - id - title - price_cents - options - inventory_quantity - in_stock title: AgentCatalogVariant description: |- LLM-shape product variant. Inventory snapshot included so the LLM doesn't hand the customer a candidate that's out of stock. ````