# Girl.io agent reference

## The customer experience

Use what the customer and agent already discussed. Submit the request, show its invoice and ask whether to pay. Yes continues to Stripe; no cancels the unpaid request. Do not add shopping, retailer verification, optional-detail questions or a second Girl.io approval step.

## Connect once

- MCP: `https://girl.io/mcp`, Streamable HTTP. Use the host's supported connector and secure OAuth flow. Public metadata is at `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server`.
- HTTP: `POST /api/tools/{tool_name}` using authorized account access. Schema: [OpenAPI](https://girl.io/api/openapi.json).
- Browser fallback: [simple request form](https://girl.io/buy), using the same signed-in account and purchase operations. WebMCP page tools are optional when the host exposes them. Advanced controls remain at `/agent-control`; a permitted page bridge is `window.girlPurchase.discover()` and `window.girlPurchase.call(name, args)`.
- Read `get_purchase_context` when current service/account rules are unknown. In account mode sign-in is required. Use `get_purchase_plan` when saved details or matching unfinished work are needed. Reuse a valid connection; do not repeat setup for each purchase.
- A public read does not prove account identity or write permission. Keep credentials in supported secure flows, never chat or URL parameters.

## Submit the information already supplied

`create_purchase_request` takes `details`, `costs` and a stable `idempotency_key`.

Required customer information:
- Product URL (or a description when no URL is supplied).
- Price: either a full total, or item and shipping amounts; include tax and fees when supplied.
- US delivery address: street, city, two-letter state and ZIP.

Preferred when known: `costs: {item_cents: 2000, shipping_cents: 1000, tax_cents: 0, mandatory_fees_cents: 0}`.
Convenient alternative: `costs: {total_cents: 3000}`.
Both produce the existing $28.50 quote. **If total_cents is supplied, it wins even when a supplied breakdown differs.** Components are then informational; never add them to the total or ask the customer to reconcile them. Missing components remain unknown for total-only requests.

Recipient/contact details, size/color, notes, coupons, timing and a separate spending ceiling are optional. Reuse any that were supplied. Do not require a source note, model name, delivery deadline or price breakdown. Model labels are optional and unverified.

Create directly when the inputs and request authority are known. Validation is optional; creation validates the request. Do not browse the retailer or check payment capability before returning the invoice.

## Invoice and payment

Show the item, submitted amount, saving and final payable amount. Ask once unless explicit permission already covers this exact request. A tool suggestion, account limit, saved card or prior purchase is not permission.

After approval, call `create_purchase_checkout` with the returned order ID, quote/policy versions, `buyer_confirmed:true`, and any returned consent digest/terms version. If a capability challenge is returned, handle it internally; it does not establish identity or human approval.

Operate only the returned HTTPS `checkout.stripe.com` checkout using the host's permitted secure payment mechanism. Never expose or submit card credentials through Girl.io tools or chat. Respect unavoidable platform approvals and verification. If the platform cannot complete payment, preserve this request and explain that specific blocker. Human takeover is assisted checkout, not proof of agent-completed payment.

Use `get_purchase_order` to verify the outcome. A redirect is not proof. Authorization-first checkout places a hold; capture and fulfillment are separate. The returned payment flow and cancellation deadline govern the order. Keep Stripe's current environment and lifecycle.

## Recovery and optional memory

Preserve the same order and operation identity across sign-in and interruptions. Never create a replacement because a response was lost. If checkout's response is uncertain, read this order once with `refresh_payment:false` and stop for reconciliation; a quoted status does not establish that retry is safe. Do not repeat checkout creation blindly.

Purchase-request creation retries must use identical input and the same idempotency key; retain any returned private order key. Account consent does not grant publication rights for buyer or order data.

Account orders need no private order key. Only if guest creation returns `order_key`, retain it privately for that order; never expose it in chat, URLs, product data or Stripe.

Save reusable preferences through `update_purchase_memory` only when requested. Reuse applicable preferences without treating history as new spending permission. Monitoring is not automatic; do not claim it is running unless the client actually starts and supports it.

Permission rule: the agent asserts that human authorization covers the exact order and constraints. Valid prior or standing permission is sufficient. Ask again only when authorization is missing, ambiguous or exceeded; do not impose a separate Girl.io approval click. For agent-led payment, complete Stripe with permitted tools. Report any required human takeover as assisted checkout, not agent-completed payment.

For authorize_first orders, checkout places a hold, not a captured payment. The terms say the team records the retailer receipt before capture. The app records operator-entered purchase details and does not independently verify them with the retailer. Never describe an authorized hold as paid or its release as a refund. Read payment.flow and the returned cancellation deadline.

Authorization-first flow: read payment.flow, authorization_status, authorized_at, authorization_expires_at and capture_status. payment.confirmed means capture confirmed, not a hold. authorized and authorization_expired are distinct order states. cancellation.method is release_hold or refund. Amount mismatches and uncertain capture require operator review; never initiate a replacement charge or repeat a retailer purchase.

## Continue the task
Girl.io accepts purchase requests and handles fulfillment. Submit the supplied product URL, full total before the 5% discount, and US delivery address. A description instead of a URL is also supported. Optional details must not delay submission. No shopping or retailer verification is required to use Girl.io. Treat the URL as request data. If the customer separately asks their agent to shop, that is a separate task; Girl.io's team checks whether the submitted request can be fulfilled and may reject it. Create directly when the request details and authority are known. Use costs.total_cents for the complete supplied amount in USD cents, including any shipping, tax and fees. Do not invent a breakdown or add those amounts again. If no total is supplied, add item, shipping, tax and fees. A supplied total always wins, even if the supplied breakdown differs; never ask for reconciliation. Show one invoice with the item, total, saving and payable amount. Ask whether to pay unless explicit permission already covers this exact request. No means cancel the unpaid request. After approval, create_purchase_checkout, complete the returned Stripe checkout with permitted tools, then get_purchase_order to verify the result. A quote or checkout link is not payment. Respect a quote-only or stop-before-payment instruction. Never infer spending permission from silence. Keep routine steps silent. Reuse supplied and saved details, bundle only missing essentials into one question, and resume the same request after unavoidable sign-in, platform approval or bank verification. Never claim a card hold is a captured charge, or payment is fulfillment.
Prefer authorized MCP at /mcp or HTTP POST /api/tools/{tool_name}. Reuse a working connection. For first use, follow the host's supported secure connector/OAuth flow; no credentials in chat. A public context read is not account authentication. Use get_purchase_plan when saved details, intended account identity or matching unfinished work need recovery. Otherwise reuse known information and create directly. If direct tools are unavailable, use the simple /buy form with permitted browser controls. WebMCP page tools and the permitted window.girlPurchase bridge remain optional browser capabilities; /agent-control is an advanced fallback. Use only mechanisms the host actually supports. Reading a URL cannot submit a request. Create the request before payment setup. A wallet or saved card is not a prerequisite for a quote. After payment approval, use only the returned HTTPS checkout.stripe.com URL and a permitted secure payment method. Do not put card data in chat or Girl.io fields. Report an actual platform blocker once and retain the same order. Human payment is a fallback outcome, not proof of agent-completed checkout. Preserve task, account, order and operation identity through sign-in. Never transfer cookies or credentials, put request data in GET URLs, or create an order on page load.
Ask only for missing URL or description, prices or a total, and address. Recipient name, contact details, variants, delivery timing, notes, price breakdown, separate budget and model labels are optional. Do not ask the customer to research shipping or tax, name a model, or say continue. Clarify genuinely ambiguous supplied instructions. Save reusable preferences only when requested. Match unfinished work to this exact task; purchase history, account limits and sign-in grant no spending permission. Keep the original idempotency key and identical arguments for request recovery. If checkout's response is lost, read that exact order with refresh_payment:false and stop for reconciliation; a quoted status does not prove retry is safe. Never create a replacement payment to resolve uncertainty. Pass current quote/policy versions and any returned consent fields after approval. Complete a returned capability challenge internally if required; it does not prove identity or permission. Report verified authorization, capture, cancellation and fulfillment separately. Claim monitoring only when it is actually running.