Agentic commerce (ACP and UCP)

Mitosis exposes two agentic-commerce surfaces so a shopping agent can quote a buyer an exact price for a plan and hand the purchase to the account owner:

Both project the same checkout session. The catalog of purchasable items is GET /api/v1/commerce/catalog: every plan on monthly and annual billing, plus the Backups add-on. Amounts are integer minor units (cents), USD.

What a session does, and does not do

A session prices real items, records the buyer details the agent supplies, and reports totals, policy links, and an expiry (six hours). It does not take payment. Mitosis subscriptions are Stripe-billed to an account, and delegated payment credentials are not accepted yet, so complete moves the session to requires_escalation and returns a continue_url into the hosted billing page, where the account owner finishes. Both protocols model that hand-off natively, so an agent following either spec needs no special case.

Every plan starts with a free trial; nothing is charged until it ends. Tax is assessed by Stripe from the billing address at continue_url.

ACP walkthrough

# 1. Create a session for the Team plan, billed monthly
curl -X POST https://mitosislabs.ai/checkout_sessions \
  -H "Content-Type: application/json" \
  -H "API-Version: 2026-04-17" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"line_items":[{"item":{"id":"plan_team_monthly"},"quantity":1}],
       "buyer":{"email":"[email protected]","first_name":"Ada"}}'
# → 201 { "id": "cs_…", "status": "ready_for_payment", "totals": [...], "continue_url": "…" }
 
# 2. Read or update it
curl https://mitosislabs.ai/checkout_sessions/cs_…
curl -X POST https://mitosislabs.ai/checkout_sessions/cs_… \
  -H "Content-Type: application/json" -d '{"line_items":[{"item":{"id":"plan_scale_annual"}}]}'
 
# 3. Complete → escalation to the account owner
curl -X POST https://mitosislabs.ai/checkout_sessions/cs_…/complete \
  -H "Content-Type: application/json" -d '{"buyer":{"email":"[email protected]"}}'
# → 200 { "status": "requires_escalation", "continue_url": "https://mitosislabs.ai/billing?…" }
 
# 4. Or cancel
curl -X POST https://mitosislabs.ai/checkout_sessions/cs_…/cancel

Accepted request shapes: the 2026-04-17 line_items[].item.id form and the 2025-09-29 items[].id form. API-Version may be any released snapshot from 2025-09-29 to 2026-04-17; an unknown one is a 400 with code: "unsupported_version". Idempotency-Key replays return the original session with Idempotent-Replayed: true; reuse with a different body is a 422 idempotency_conflict.

Errors are ACP-shaped: { "type", "code", "message", "param"? }. Status enum used: not_ready_for_payment, ready_for_payment, requires_escalation, completed, canceled, expired.

UCP walkthrough

curl -X POST https://mitosislabs.ai/ucp/v1/checkout-sessions \
  -H "Content-Type: application/json" \
  -H 'UCP-Agent: profile="https://agent.example/profile.json"' \
  -H "Idempotency-Key: $(uuidgen)" -H "Request-Id: $(uuidgen)" \
  -d '{"line_items":[{"item":{"id":"plan_solo_monthly"},"quantity":1}]}'
# → 201 { "ucp": { "version": "2026-08-25", "status": "success", ... }, "id": "ucs_…",
#         "status": "ready_for_complete", "totals": [...], "continue_url": "…" }
curl -X PUT  https://mitosislabs.ai/ucp/v1/checkout-sessions/ucs_… -d '{"line_items":[…]}'
curl -X POST https://mitosislabs.ai/ucp/v1/checkout-sessions/ucs_…/complete
curl -X POST https://mitosislabs.ai/ucp/v1/checkout-sessions/ucs_…/cancel

The profile at /.well-known/ucp declares the dev.ucp.shopping service (REST, endpoint /ucp/v1), the dev.ucp.shopping.checkout capability, identity linking through the site's OAuth 2.1 authorization server, and one payment handler, ai.mitosislabs.hosted_billing, whose instrument is the hosted checkout itself. Its keys set is empty: responses are not signed yet.

Limits and auth

Both surfaces are public and rate-limited (60 requests per minute per address). No seller API key is issued to platforms yet; requests are accepted without an Authorization header. Signature/Timestamp headers are accepted and ignored until request signing ships. Everything here mirrors on the sandbox at https://dev.mitosislabs.ai with Stripe test mode.

Not supported: delegated payment (/agentic_commerce/delegate_payment), AP2 mandates, x402, MPP. Agents should not attempt to pay on a user's behalf; send the owner to continue_url.