Recipe. Quote. Order. Results.

What you receive

One online lab report with sample photos and descriptions, the recipe actually made, preparation notes, one maker’s aroma and flavor observations when performed, and a next-step recommendation. Choose one recipe or a comparison of up to three preparations.

Supported trials use active catalog ingredients and processes, up to 500 g per preparation and eight non-water ingredients. The starter weighing limit is 0.1 g in 0.01 g increments. Ingredient stock is assumed replenishable; held ingredients and unsupported methods remain excluded. Exact quantities are preserved.

Instrument assays, consumer panels, nutrition, microbiology and shelf-life studies are outside this package. Results describe actual observations; missing evidence stays explicit.

1. Create a recipe

Call POST /api/v2/ideas, then POST /api/v2/ideas/{id}/generate. Orderable recipes include services.quote. Unsupported requests return a reason and an alternative to choose.

Or supply exact ingredients using recipe.source: ingredients. Exact recipe fields. The quote checks that the chosen quantities, method and requested work fit current capabilities.

2. Get the quote

POST /api/v2/order-quotes

{
  "recipe": {
    "source": "idea",
    "ideaId": "YOUR_IDEA_UUID",
    "ideaRevision": 3
  },
  "variationIds": []
}

Show the returned quote.totalCents as “Test Trial for $XX”. Prices depend on the exact ingredients, quantities, process and selected preparations. A null total cannot be ordered: explain the gap and offer a supported alternative.

Use proposed variationIds only after showing their changed ingredient amounts. Optional shipping is included in the full quoted total. Preserve the returned quote.scopeHash.

3. Start checkout

Show the recipe, total and trial terms. After the customer agrees, call POST /api/v2/orders:

{
  "selection": {
    "recipe": {
      "source": "idea",
      "ideaId": "YOUR_IDEA_UUID",
      "ideaRevision": 3
    },
    "variationIds": []
  },
  "quoteHash": "RETURNED_QUOTE_SCOPE_HASH",
  "shareWithTeam": true,
  "contactEmail": "you@example.com",
  "checkout": {
    "acceptQuote": true
  }
}

Send X-Deconfound-Api-Key and a stable Idempotency-Key. The response contains the frozen order, accepted quote and pending payment. No second lab offer or order confirmation is needed. The price stays fixed for this scope.

Website customers log in before ordering; their verified account email is used. API clients supply contactEmail. Neither a guest session nor an API key can access another customer’s orders.

4. Place the order

Read paymentMode from GET /api/v2/lab-status. In the current test mode, show “Place order · $XX” with a small “Test mode · No charge” label. After the customer confirms placement, call POST /api/v2/orders/{id}/test-payment with its own stable idempotency key:

{"outcome":"succeeded"}

Success returns orderStatus: ordered_pending_lab: Ordered - Pending Lab. Failed or cancelled attempts remain awaiting_checkout. The lab receives the order and can prepare it and publish the report.

This is a local payment simulation, not Stripe test mode. No card details are collected or money charged. Checkout does not fabricate preparation, a dispatch date or report evidence.

Continue an older request

An older priced request may have no checkout consent. Show its original saved recipe, price and terms, then use POST /api/v2/orders/{id}/checkout with a stable key after explicit acceptance:

{
  "revision": 3,
  "quoteHash": "SAVED_QUOTE_SCOPE_HASH",
  "acceptQuote": true
}

Use the actual current revision and saved quote hash. The endpoint keeps the original price and initializes checkout on the same order. If the record already contains a real revised or accepted offer, its explicit contract is preserved. Historical offer compatibility.

Optional research samples

Add deliverables: ["photo", "taste", "ship"] and destination: {country:"US",region:"CA",postalCode:"94133"}. Supported ZIP codes receive a cold-packed overnight shipping allowance within the order total, based on distance from San Francisco, CA 94133.

Shipped samples are for research only and are not for human or animal consumption. The allowance covers one insulated parcel and up to 100 g per version, at most three versions / 300 g total, subject to actual yield. It is not a live carrier quote. Overnight transit begins after dispatch. Unsupported destinations produce no delivered order price; choose a supported destination or report only.

GET /api/shipping/postal-code?zip=94133 returns city and state. Quotes retain the resolved destination. Provide the full shipping address before dispatch.

Track the order and report

GET /api/v2/orders/{id} and GET /api/v2/orders return orderStatus. Follow the state through awaiting checkout, Ordered - Pending Lab, preparation and completion. Payment remains a separate record.

GET /api/v2/orders/{id}/results returns the published sample descriptions, photos and analysis in output, plus any advanced batch evidence in results. Published output may be complete while advanced records remain not started. Photos require the owner’s credentials. No email is sent automatically.

Retries and availability

Save request bodies and idempotency keys before sending. Retry an uncertain operation with the identical body and key; do not create a duplicate. Read the order for its current state. A changed selection needs a new quote and explicit acceptance.

LAB_PAUSED stops new ordering and payment attempts until intake reopens. Existing records and exact successful-command replays remain available. Unsupported ingredients, processes or scope cannot be bypassed by a prompt or client price.

Agent access

Native MCP at /mcp uses the same scoped API key. Use quote_order, place_order, prepare_order_checkout for older saved requests, and get_order_results. Payment simulation is an explicit REST/browser action. MCP connection and examples.