--- title: "The Order Lifecycle — Discover, Order, Pay, Deliver | roji.ai" description: "The canonical reference for how a ROJI order runs: discovery, the fee preview, pay-at-order over card, ACH, or x402, the order state machine, the interaction primitives, the SLA clock rules, and the refund rails." doc_version: f5c7ab1426f5 last_updated: 2026-09-10 --- # The Order Lifecycle — Discover, Order, Pay, Deliver | roji.ai Developers Ordering The order lifecycle This is the contract between your agent, the business, and the platform. Everything on ROJI — money, communication, delivery, reputation — hangs off this state machine. ## Discover, then order Two calls stand between an agent and a real-world service. `search_services` filters the catalog by vertical, jurisdiction, price, and turnaround. `get_service` returns the listing in full: the **input schema** (exactly what the business needs from you), the **deliverable schema** (exactly what comes back), the price, the SLA, the refund window, and an itemized **fee preview**. Nothing is charged until your agent calls `order_service` with the accepted fee preview. Your agent never invents a spec, never names a price, and never negotiates — the business wrote the offer, your agent parameterizes it. ## The state machine ```text ┌──────────┐ │ draft │ agent parameterizes a listing; inputs validated └────┬─────┘ against the listing's declared input schema ▼ ┌──────────┐ fee preview returned: list price + platform fee + │ quoted │ processing, itemized. Nothing is charged yet. └────┬─────┘ ▼ ┌──────────┐ payment clears — destination charge or x402 — and │ placed │ settles to the business. ROJI never holds it. └────┬─────┘ ▼ ┌──────────────┐ business accepts, or the listing auto-accepts. │ accepted │ Rejected → automatic full refund. SLA clock starts. └──────┬───────┘ ▼ ┌──────────────┐ ┌──────────────┐ │ in_progress │◄──────►│ needs_input │ blocked: a Question, an Info └──────┬───────┘ └──────────────┘ Request, or a Checkpoint is ▼ waiting on your side — ┌──────────────┐ the SLA clock is paused │ delivered │ deliverable submitted, automated checks green; └──────┬───────┘ the refund window opens (7 days by default) ┌─────┴───────────────┐ ▼ ▼ ┌───────────┐ ┌────────────────────┐ │ completed │ │ refund_requested │──► business answers within 72h └───────────┘ └─────────┬──────────┘ (silence auto-approves) ▼ ┌──────────────────┐ │ refunded / │ contested → platform mediation, │ resolved │ decided from the order record └──────────────────┘ (cancelled before acceptance, and rejected by the business, both refund in full automatically — every path terminates) ``` Two things are gone compared to a managed marketplace, and their absence is the design: there is **no open pool and no claim race** — you picked the listing — and there is **no escrow**. Money is never in flight, never held by us, never waiting on a verdict. ## Pay at order The buyer pays the **list price plus ROJI's platform fee**. The business keeps 100% of its list price; the fee is collected as the application fee on the payment. Two rails do this, and both settle the same way. ### Card and ACH — a Stripe destination charge `order_service` creates a `PaymentIntent` with `transfer_data.destination` set to the business's connected account, `on_behalf_of` naming it as merchant of record, and `application_fee_amount` carrying ROJI's fee. The charge captures at order. Funds settle to the business on its normal Stripe payout schedule. ROJI's balance never holds your money, which means there is no hold to expire, no re-authorization window, and no capture that can fail three days after your agent moved on. ### x402 — the agent-native rail For agents that would rather pay a protocol than fill a card form, `order_service` answers **HTTP 402 Payment Required** with exact payment requirements for `list price + fee`: ```json { "error": "payment_required", "accepts": [{ "scheme": "exact", "network": "base", "asset": "USDC", "maxAmountRequired": "74750", "payTo": "0x…", "resource": "https://api.roji.ai/v1/orders/ord_…" }] } ``` Your agent pays with a standard `@x402/fetch`-style wrapper and retries; the order places on the retry. Settlement runs through Stripe Machine Payments — a crypto-deposit `PaymentIntent` in Base USDC that auto-captures to fiat — so the **business is always paid in dollars** and never touches crypto. **AP2 mandates** are accepted alongside either rail as cryptographic proof of what your Principal authorized, and bind to the spend-policy decision on the order. This is a deliberate bet on where the rails went in 2026, not a novelty: the x402 Foundation moved under the **Linux Foundation** in April 2026 with AWS, Cloudflare, Anthropic, and Circle among its members; AWS shipped x402 enforcement in CloudFront and WAF that June; and **Cloudflare's Monetization Gateway** launched in July 2026 doing edge-managed x402 charging for any resource — MCP tools explicitly included. The ecosystem is teaching agents to pay per call. ROJI is what they can buy with it. ### The fee preview is the contract Every quote is itemized and machine-readable before a cent moves — list price, platform fee at your current tier, processing at cost, total. Your agent can require explicit human approval above a threshold; spend policies (per-order caps, rolling budgets, vertical allowlists) are enforced platform-side, not by a prompt. Full fee math on the [pricing page](/pricing). ## The interaction primitives There is no free-text chat channel to parse. Everything said mid-order flows through typed objects: **Questions.** Either side asks; the asker attaches an answer schema — enum, boolean, number, text, or file. *"The signer's ID shows a middle initial but the deed doesn't. Proceed, or correct the deed first?"* arrives at your agent as `enum: ["proceed", "correct first"]`. Your agent answers in one call, or the question auto-escalates to your Principal. **Info Requests.** The business pulls missing inputs from your side. *"I need the signed authorization letter before I can file."* Your agent attaches it — or, if it doesn't have it, the request routes to your Principal as a no-login upload link. This is how an order with a gap gets unblocked instead of refunded. **Checkpoints.** Approval gates a listing declares ahead of an irreversible real-world act. *"Approve the completed filing packet before I submit it to the clerk."* The business submits the intermediate artifact; your agent — or your Principal, where the listing requires a human — approves or asks for a change before the point of no return. **Status Updates.** Lightweight progress signals — *"on site"*, *"draft 70% complete"* — delivered over webhooks so your orchestrator can plan around human latency. ## Delivery and its checks A deliverable is submitted against the schema the listing declared, and automated checks run **before** it can be marked delivered: schema conformance, manifest completeness, geotags, file integrity, malware scan. Structurally invalid work never reaches your agent. Those checks are free and unwaivable. What your agent then gets is typed data it can use immediately — structured findings, a validated answer set, a complete photo manifest, an attestation with its evidence bundle attached. Independent human QA returns later as a paid add-on for high-stakes work; it is not a payment gate and never was one here. ## Refunds, not verdicts Protection lives in the refund rail, which ROJI controls end to end: Four ways an order's money comes back Cancelled or rejected Cancel before the business accepts, or have the business decline: automatic, immediate, full refund. Nobody has done any work and nobody is owed anything. SLA breach The business misses the turnaround it published and the order refunds in full, automatically — no request, no review, no argument. The clock excludes any time the business spent waiting on you. Refund request Inside the listing's window (7 days after delivery by default, 3–30 configurable), your agent calls request_refund with a reason. The business approves or contests within 72 hours; silence auto-approves. Mediation A contested request goes to platform mediation, which decides from the order record — the listing as it stood, every input, every question, the delivery. Chargeback liability sits with the business as merchant of record. The honest trade against an escrow model: your agent pays before the work is done. What it gets in exchange is a verified counterparty (KYB, plus registry-checked licenses for regulated verticals), a published SLA with automatic teeth, a refund window we enforce rather than mediate, and reviews that only exist where money actually moved. ## Clock rules One rule makes machine-to-human commerce fair, and it's worth internalizing: **the SLA clock pauses whenever the business is waiting on you.** An unanswered Question directed at your agent, an unfulfilled Info Request, a Checkpoint sitting in your review queue — all stop the clock. It runs again the moment your side answers. "The business was slow" and "the agent was slow" stay distinguishable and measurable, and both feed reputation — your agent's median response time is on its public card, and businesses see it before they accept, so fast-answering agents get served first. Tool-by-tool surface: [MCP integration](/developers/mcp). Verticals, example listings, and typical prices: [the service directory](/categories). Build against it Get started ## Sitemap - [Every public page, as markdown](/sitemap.md) - [llms.txt](/llms.txt) · [AGENTS.md](/AGENTS.md) · [auth.md](/auth.md)