{"openapi":"3.1.0","info":{"title":"Wilby API","version":"0.73.1","description":"Wilby records what a customer authorized, enforces it on every payment, and signs every step. Amounts are in cents. Keys starting `oh_test_` use the sandbox; `oh_live_` move real money."},"servers":[{"url":"https://dev.usewilby.com"}],"tags":[{"name":"Stores","description":"The businesses you take payments for."},{"name":"Orders","description":"An order: what the customer authorized, enforced on every payment."},{"name":"Incremental Charges and Tips","description":"Charging more after the order: inside the customer's limit it goes through; above it, the customer decides."},{"name":"Customer Permissions","description":"Limits customers set for their own orders and for their AI agents."},{"name":"Outside Agent Permissions","description":"Permissions signed elsewhere: Google AP2, Mastercard Verifiable Intent, Agentic Commerce Protocol."},{"name":"Bank Payments","description":"ACH debits with a signed customer authorization, returns and their health."},{"name":"Platform-Run Payments","description":"For platforms that charge through their own processor: ask, charge, then report."},{"name":"Disputes","description":"Chargebacks and the signed evidence sent with them."},{"name":"Records","description":"Signed records anyone can check."},{"name":"Reports","description":"Totals, daily figures, stores and order exports, and live dashboards to share. Exports carry no customer names or contact details."},{"name":"Ready-Made Screens","description":"Wilby's customer screens on your own website (/kit/v1/wilby.js): your server asks for a screen pass; the screens call /v1/client with it. One customer, 30 minutes, no money moves."},{"name":"Webhooks","description":"Signed notifications for every step."},{"name":"Sandbox","description":"Test-only helpers. Refused with live keys."},{"name":"Agent API","description":"For AI agents acting for a customer (also available as an MCP server at /mcp)."},{"name":"Agent Storefront","description":"Your stores in Claude and ChatGPT under your name: customers sign in with your account, Wilby runs the limits, approvals and records."},{"name":"AI Agents on Your Website","description":"See which AI agents browse your own website, apply your rules and the customer's limits at checkout, and record the agent on the order. The visit check uses a website key (wk_…) that can do nothing else."},{"name":"Public","description":"No key needed: verification keys, records and daily checkpoints."}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Platform API key (oh_test_… or oh_live_…)"},"assistantKey":{"type":"http","scheme":"bearer","description":"Agent key from /agent/v1/connect (oha_…)"},"websiteKey":{"type":"http","scheme":"bearer","description":"Website key (wk_test_… or wk_live_…): only for POST /v1/agent-checks"}}},"paths":{"/v1/keys":{"get":{"tags":["Public"],"summary":"Public signing keys","operationId":"get_v1_keys","security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/merchants":{"post":{"tags":["Stores"],"summary":"Add or update a store","description":"Set `processor` to the store's processor (`stripe` live; `test` or `test_noholds` in the sandbox) and `processor_account_ref` to its account there.","operationId":"post_v1_merchants","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["external_ref","name","processor","processor_account_ref"],"properties":{"external_ref":{"description":"Your own id for it.","type":"string","minLength":1,"maxLength":200},"name":{"description":"A name.","type":"string","minLength":1,"maxLength":200},"processor":{"description":"The payment processor (stripe, square, braintree, adyen, paypal).","type":"string","maxLength":40},"processor_account_ref":{"description":"The store's account id at its processor.","type":"string","minLength":1,"maxLength":200},"settings":{"description":"Settings for this store.","type":"object"}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders":{"post":{"tags":["Orders"],"summary":"Create an order","description":"Records what the customer authorized. `amount_cents` is the order's price: for a fixed price, the price itself (set `max_amount_cents` to the same amount); if the final price can change, the estimate, and `max_amount_cents` is the most that may be charged without asking. `display_ref` is the order number your customer knows; customer pages show it instead of `external_ref`. With `agent_mandates`, the order comes from an outside agent and its signed permission is checked first. An AI agent checking out on your own website: add `agent_check_id` from POST /v1/agent-checks; Wilby applies your Agent Access Policy, your agent rules and the customer's own limits, records the agent, and when the customer must approve first returns `customer_approval.url` (until they do, confirming or charging the order is refused with `customer_approval_needed`).","operationId":"post_v1_orders","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["merchant_external_ref","customer","purpose","amount_cents"],"properties":{"merchant_external_ref":{"description":"Your own id for the store.","type":"string","minLength":1,"maxLength":200},"customer":{"description":"The customer: `external_ref` (your id for them), and optionally `payment_method_ref` and `customer_contact`.","type":"object","additionalProperties":false,"required":["external_ref"],"properties":{"external_ref":{"description":"Your own id for it.","type":"string","minLength":1,"maxLength":200},"payment_method_ref":{"description":"Your processor's id for the customer's saved card or bank account.","type":"string","minLength":1,"maxLength":200}}},"external_ref":{"description":"Your own id for it.","type":"string","minLength":1,"maxLength":200},"display_ref":{"description":"Your order number as customers know it (shown on Wilby's pages).","type":"string","minLength":1,"maxLength":40},"purpose":{"description":"What the order is for, in plain words.","type":"string","minLength":1,"maxLength":500},"order_type":{"description":"Your kind of order (your own word).","type":"string","maxLength":60},"pricing_terms":{"description":"Your pricing terms for the order (your own keys), shown to the customer.","type":"object"},"currency":{"description":"The currency (USD).","type":"string","pattern":"^[A-Za-z]{3}$"},"amount_cents":{"description":"An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.","type":"integer","minimum":1,"maximum":10000000000},"max_amount_cents":{"description":"The most that may be charged for the order without asking the customer again.","type":"integer","minimum":0,"maximum":10000000000},"expires_at":{"description":"When it expires (ISO 8601, UTC).","type":"string","maxLength":40},"estimate_basis":{"description":"How you worked out the estimate (for example \"by weight\").","type":"object","additionalProperties":false,"required":["source"],"properties":{"source":{"description":"Where it came from.","type":"string","enum":["customer_estimate","last_order","store_typical","store_quote"]},"entered_amount_cents":{"description":"The amount you entered, for comparison with the suggestion.","type":"integer","minimum":0,"maximum":10000000000}}},"agent_mandates":{"description":"Signed permissions an outside agent platform sent with the order (AP2 or Verifiable Intent): checkout, payment and the customer's open permissions.","type":"object","additionalProperties":false,"properties":{"format":{"description":"The format of the file or credential.","type":"string","enum":["ap2","vi","acp"]},"checkout":{"description":"A signed checkout permission (what the customer agreed to buy).","type":"string","maxLength":60000},"payment":{"description":"A payment: its amount, status and processor reference.","type":"string","maxLength":60000},"l1":{"description":"Test tools: the issuer layer of a Verifiable Intent credential.","type":"string","maxLength":60000},"l2_checkout":{"description":"Verifiable Intent: the customer's signed checkout permission.","type":"string","maxLength":60000},"l2_payment":{"description":"Verifiable Intent: the customer's signed payment permission.","type":"string","maxLength":60000},"l3_checkout":{"description":"Verifiable Intent: the agent's signed checkout.","type":"string","maxLength":60000},"l3_payment":{"description":"Verifiable Intent: the agent's signed payment.","type":"string","maxLength":60000},"platform_kid":{"description":"The agent platform's key id.","type":"string","maxLength":200},"complete_request":{"description":"The full signed request the agent platform sent, for Wilby to check.","type":"string","maxLength":60000},"signature":{"description":"The signature.","type":"string","maxLength":2000},"timestamp":{"description":"When it was signed.","type":"string","maxLength":64},"checkout_session":{"description":"The agent platform's checkout session the signed permission belongs to.","type":"object"},"allowance":{"description":"In a signed permission: what the customer allowed (amounts, stores, dates).","type":"object"}}},"agent_signature":{"description":"The agent's signed HTTP request (RFC 9421 message signature: method, URL, headers, signature) so Wilby can check which agent sent it.","type":"object","additionalProperties":false,"required":["signature_input","signature","authority","path"],"properties":{"signature_input":{"description":"The Signature-Input header of the signed request.","type":"string","maxLength":2000},"signature":{"description":"The signature.","type":"string","maxLength":2000},"signature_agent":{"description":"The Signature-Agent header (who the agent says it is).","type":"string","maxLength":500},"authority":{"description":"The request address (host) in a signed HTTP request.","type":"string","maxLength":300},"path":{"description":"Which way to integrate, or a path.","type":"string","maxLength":2000},"method":{"description":"The HTTP method of the signed request.","type":"string","maxLength":10},"query":{"description":"The query string of the signed request.","type":"string","maxLength":2000},"headers":{"description":"The request headers that were signed.","type":"object","additionalProperties":{"type":"string","maxLength":2000}}}},"agent_check_id":{"description":"The id of an agent check (`POST /v1/agent-checks`) to attach to an order.","type":"string","pattern":"^ach_[0-9a-z]{20}$"}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"get":{"tags":["Orders"],"summary":"List orders","description":"Newest first, each with its `summary`. Filter by `customer_external_ref`, `merchant_external_ref`, `stage`; `limit` up to 50; next page: `before` = the `next_before` you got.","operationId":"get_v1_orders","parameters":[{"name":"customer_external_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id for the customer."},{"name":"merchant_external_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id for the store."},{"name":"stage","in":"query","required":false,"schema":{"type":"string","maxLength":30},"description":"Where the order is: created, confirmed, authorized, captured, cancelled, expired, disputed."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50},"description":"How many to return (paging)."},{"name":"before","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"List only items created before this id or time (paging)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/website-keys":{"post":{"tags":["AI Agents on Your Website"],"summary":"Create a website key","description":"A website key (`wk_…`) can only call POST /v1/agent-checks: it can't read orders, charge or change anything, so it is safe on a web server or in a Cloudflare Worker. Shown once. Optional `name`.","operationId":"post_v1_website_keys","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name.","type":"string","minLength":1,"maxLength":60}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"get":{"tags":["AI Agents on Your Website"],"summary":"List your website keys","description":"Their start (`key_prefix`), when each was made and last used, and whether it was revoked. Never the keys themselves.","operationId":"get_v1_website_keys","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/website-keys/{id}/revoke":{"post":{"tags":["AI Agents on Your Website"],"summary":"Revoke a website key","description":"It stops working at once on this server and within a minute everywhere.","operationId":"post_v1_website_keys_id_revoke","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^wky_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/agent-checks/report":{"get":{"tags":["AI Agents on Your Website"],"summary":"Agents on your website","description":"Last 30 days (or `days`, up to 90), per agent: visits by level, and how many reached checkout, ordered or were turned away. Daily totals only, kept 13 months: no IP addresses, pages or shoppers.","operationId":"get_v1_agent_checks_report","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90},"description":"A number of days, or the days of the week (0 = Sunday) for hours."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/agent-checks/{id}":{"get":{"tags":["AI Agents on Your Website"],"summary":"One check and what came of it","description":"The level, agent and clue (with `browser_signals` and `buyer_hints` when there were any), whether it was allowed, the order it was used for, and whether the customer still has to approve that order.","operationId":"get_v1_agent_checks_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^ach_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/authorizations/suggest":{"get":{"tags":["Orders"],"summary":"Suggest the amount to hold","description":"From this customer's own history at this store. Debit and prepaid cards are held closer to what the customer entered.","operationId":"get_v1_authorizations_suggest","parameters":[{"name":"merchant_external_ref","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id for the store."},{"name":"customer_external_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id for the customer."},{"name":"amount_cents","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":10000000000},"description":"An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount."},{"name":"card_funding","in":"query","required":false,"schema":{"type":"string","enum":["credit","debit","prepaid"]},"description":"The card type: credit, debit or prepaid."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get an order","description":"`summary` is screen-ready: `status_label` and `next_step` in plain words, `money` (estimate, up to without asking, paid, held, tip, refunded, final), `waiting_extra`, and each incremental charge with its title, note, card label and how it was decided. Webhooks carry the same block.","operationId":"get_v1_orders_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/confirm":{"post":{"tags":["Orders"],"summary":"Store confirms the order","operationId":"post_v1_orders_id_confirm","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/authorize":{"post":{"tags":["Orders"],"summary":"Take the payment","description":"Places a hold for the estimate on cards (a charge where holds aren't possible, a debit for bank accounts). Retries never charge twice.","operationId":"post_v1_orders_id_authorize","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/capture":{"post":{"tags":["Orders"],"summary":"Set the final price","description":"Captures the final amount from the hold and releases the rest, or refunds the difference. Above what was paid: ask for an incremental charge first. Optional `measure` `{\"unit\": \"lb\", \"value\": 24}`: what was weighed (goods sold by weight), signed into the record and shown on UCP orders as the settled measure.","operationId":"post_v1_orders_id_capture","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["capture_cents"],"properties":{"capture_cents":{"description":"The final amount captured for the order.","type":"integer","minimum":0,"maximum":10000000000},"measure":{"description":"What was measured for the final price: `value` and `unit` (for example 18.4 lb).","type":"object","additionalProperties":false,"required":["unit","value"],"properties":{"unit":{"description":"The unit (lb, kg, hour, item…).","type":"string","enum":["lb","kg","oz","g"]},"value":{"description":"The measured value.","type":"number","exclusiveMinimum":0,"maximum":1000000}}}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/cancel":{"post":{"tags":["Orders"],"summary":"Cancel the order","description":"Releases any hold and refunds anything taken.","operationId":"post_v1_orders_id_cancel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"reason":{"description":"Why, as a code or in words. On an incremental charge: the store's reason the customer sees.","type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/incremental-charges":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Charge an incremental charge","description":"Inside the customer's limit it is charged at once; above it, the customer gets a link with the reason and evidence and approves in one tap. Optional: `reason_title` (your own one-line reason, shown in bold), `card_label` (\"Visa •••• 4242\", shown as \"Charged To\"), `return_url` (where the page sends the customer after they answer).","operationId":"post_v1_orders_id_incremental_charges","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["amount_cents","reason","evidence"],"properties":{"amount_cents":{"description":"An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.","type":"integer","minimum":1,"maximum":10000000000},"reason":{"description":"Why, as a code or in words. On an incremental charge: the store's reason the customer sees.","type":"string","enum":["over_estimate","add_on","special_handling","damage_fee","other","extra_parts","extra_labor","substitution","price_change"]},"note":{"description":"A note in plain words.","type":"string","maxLength":500},"before_work":{"description":"True when the incremental charge is asked before the work is done (the customer sees \"before we continue\").","type":"boolean"},"approval_window_minutes":{"description":"How long the customer has to answer an incremental charge request (minutes).","type":"integer","minimum":5,"maximum":1440},"reason_title":{"description":"A short title for the reason (shown as the heading).","type":"string","minLength":1,"maxLength":80},"card_label":{"description":"How the card is shown to the customer, like \"Visa •••• 4242\".","type":"string","minLength":1,"maxLength":40},"return_url":{"description":"Where Wilby's pages send the customer when they are done (https, or your app's own link).","type":"string","minLength":1,"maxLength":500},"agent_mandates":{"description":"Signed permissions an outside agent platform sent with the order (AP2 or Verifiable Intent): checkout, payment and the customer's open permissions.","type":"object","additionalProperties":false,"properties":{"format":{"description":"The format of the file or credential.","type":"string","enum":["ap2","vi","acp"]},"checkout":{"description":"A signed checkout permission (what the customer agreed to buy).","type":"string","maxLength":60000},"payment":{"description":"A payment: its amount, status and processor reference.","type":"string","maxLength":60000},"l1":{"description":"Test tools: the issuer layer of a Verifiable Intent credential.","type":"string","maxLength":60000},"l2_checkout":{"description":"Verifiable Intent: the customer's signed checkout permission.","type":"string","maxLength":60000},"l2_payment":{"description":"Verifiable Intent: the customer's signed payment permission.","type":"string","maxLength":60000},"l3_checkout":{"description":"Verifiable Intent: the agent's signed checkout.","type":"string","maxLength":60000},"l3_payment":{"description":"Verifiable Intent: the agent's signed payment.","type":"string","maxLength":60000},"platform_kid":{"description":"The agent platform's key id.","type":"string","maxLength":200},"complete_request":{"description":"The full signed request the agent platform sent, for Wilby to check.","type":"string","maxLength":60000},"signature":{"description":"The signature.","type":"string","maxLength":2000},"timestamp":{"description":"When it was signed.","type":"string","maxLength":64},"checkout_session":{"description":"The agent platform's checkout session the signed permission belongs to.","type":"object"},"allowance":{"description":"In a signed permission: what the customer allowed (amounts, stores, dates).","type":"object"}}},"agent_signature":{"description":"The agent's signed HTTP request (RFC 9421 message signature: method, URL, headers, signature) so Wilby can check which agent sent it.","type":"object","additionalProperties":false,"required":["signature_input","signature","authority","path"],"properties":{"signature_input":{"description":"The Signature-Input header of the signed request.","type":"string","maxLength":2000},"signature":{"description":"The signature.","type":"string","maxLength":2000},"signature_agent":{"description":"The Signature-Agent header (who the agent says it is).","type":"string","maxLength":500},"authority":{"description":"The request address (host) in a signed HTTP request.","type":"string","maxLength":300},"path":{"description":"Which way to integrate, or a path.","type":"string","maxLength":2000},"method":{"description":"The HTTP method of the signed request.","type":"string","maxLength":10},"query":{"description":"The query string of the signed request.","type":"string","maxLength":2000},"headers":{"description":"The request headers that were signed.","type":"object","additionalProperties":{"type":"string","maxLength":2000}}}},"customer_contact":{"description":"How to reach the customer for a one-time code: `label` (the name on their passkey) and `email`. Kept 7 days, never in the signed record.","type":"object","additionalProperties":false,"properties":{"label":{"description":"A short name shown to people.","type":["string","null"],"maxLength":80},"email":{"description":"An email address (shown masked when read back).","type":["string","null"],"maxLength":254}}},"evidence":{"description":"Proof for an incremental charge (photos, notes, files): `type`, `label`, `file_ref`, `meta`.","type":"array","minItems":1,"maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["type","sha256"],"properties":{"type":{"description":"What kind it is.","type":"string","enum":["scale_reading","photo","receipt","delivery","customer_message","device_record","other"]},"sha256":{"description":"SHA-256 fingerprint.","type":"string","pattern":"^[0-9a-f]{64}$"},"file_ref":{"description":"Your reference to a file you keep (a photo, a document). Wilby stores its fingerprint, not the file.","type":"string","maxLength":500},"label":{"description":"A short name shown to people.","type":"string","maxLength":120},"meta":{"description":"Extra details about a piece of evidence (your own keys and values).","type":"object"}}}}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/incremental-charges/preview":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Check whether an incremental charge would need approval","description":"A dry run for your store screen: `decision` is `inside_limit`, `needs_approval`, `request_pending` or `not_allowed`, with `room_cents` (how much more can still be charged without asking). Nothing is created or recorded.","operationId":"post_v1_orders_id_incremental_charges_preview","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["amount_cents"],"properties":{"amount_cents":{"description":"An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.","type":"integer","minimum":1,"maximum":10000000000}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/decline":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Record a decline made in your own app","description":"For a customer signed in to your app who taps Decline. No Face ID or code is needed (declining charges nothing). Recorded as \"declined in the platform's app\"; the `incremental_charge.declined` webhook follows.","operationId":"post_v1_incremental_charges_id_decline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"note":{"description":"A note in plain words.","type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/passkey/begin":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Approve inside your app or on your website: get the Face ID prompt","description":"Works for your registered apps and, since 0.66.3, for your own websites listed in `passkey_websites.in_page` (GET /v1/settings): your page shows the prompt itself with `navigator.credentials`. Returns WebAuthn `options` for this exact extra (its id and amount are in the challenge). `kind` is `register` the first time (create a passkey, finish, then begin again) or `authenticate`. Your app passes `options` to the phone's passkey sheet. Needs your apps in settings (`apps`). Since 0.67.0, send the customer's `user_agent` (optional, never kept): the answer adds `likely_on_another_device` (lead with \"Set Up {lock} on {device}\" through `new_phone/send` instead of the passkey sheet), `device` (`lock`: \"Face ID\", \"Touch ID\", \"Fingerprint or Screen Lock\", \"Windows Hello\"; `name`: \"This Phone\"…) and `code_approval_available`. Never a dead end: if the sheet is cancelled or finds nothing, offer \"Set Up {lock} on {device}\" (new_phone) and, on a device that can't hold a passkey, \"Approve With a Code\" (code/send).","operationId":"post_v1_incremental_charges_id_passkey_begin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":["object","null"],"additionalProperties":false,"properties":{"customer_contact":{"description":"How to reach the customer for a one-time code: `label` (the name on their passkey) and `email`. Kept 7 days, never in the signed record.","type":"object","additionalProperties":false,"properties":{"label":{"description":"A short name shown to people.","type":["string","null"],"maxLength":80},"email":{"description":"An email address (shown masked when read back).","type":["string","null"],"maxLength":254}}},"user_agent":{"description":"The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.","type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/passkey/finish":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Approve inside your app or on your website: send the signed answer","description":"An answer made on one of your websites in `passkey_websites.in_page` is accepted and recorded as approved on your website, with its address; any other website is refused. Send `ceremony_id` and the passkey `response` from the phone. Wilby checks the signature against the customer's passkey; the incremental charge is approved (recorded as approved with Face ID in your app) and charged if Wilby charges for you. `incremental_charge.approved` follows.","operationId":"post_v1_incremental_charges_id_passkey_finish","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ceremony_id","response"],"properties":{"ceremony_id":{"description":"The id of a Face ID / Touch ID / fingerprint prompt. Send it back when finishing.","type":"string","maxLength":40},"response":{"description":"The browser's WebAuthn answer, passed through unchanged."},"user_agent":{"description":"The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.","type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/passkey/new_phone/send":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Set up this device: text a code","description":"Since 0.67.0, also when `likely_on_another_device` is true or the passkey sheet was cancelled or found nothing. For a customer who set up Face ID on another phone (`begin` gave `authenticate`, `new_phone_available` is true, but this phone has no passkey). Sends `customer.code_requested` to your webhook for you to text. Returns `code_id`.","operationId":"post_v1_incremental_charges_id_passkey_new_phone_send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":["object","null"],"additionalProperties":false,"properties":{"user_agent":{"description":"The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.","type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/passkey/new_phone/verify":{"post":{"tags":["Incremental Charges and Tips"],"summary":"New phone: check the code, get a set-up prompt","description":"Send `code_id` and `code`. A wrong code returns `wrong_code` with tries left. The right code returns a `passkey_prompt` with `kind: register`: create the passkey, send it to `/passkey/finish`, then call `/passkey/begin` again to approve. The customer's other passkeys keep working.","operationId":"post_v1_incremental_charges_id_passkey_new_phone_verify","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["code_id","code"],"properties":{"code_id":{"description":"The id of a sent code. Send it back with the code the customer types.","type":"string","maxLength":40},"code":{"description":"A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.","type":"string","maxLength":12},"user_agent":{"description":"The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.","type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/code/send":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Approve with a code alone: send the code","description":"For a device that can't hold a passkey (no screen lock, an old browser). Sends `customer.code_requested` to your webhook for you to text (or Wilby texts it, if set up). The code is for this exact extra and amount. Returns `code_id`. Optional `user_agent` for the report by device (never kept).","operationId":"post_v1_incremental_charges_id_code_send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":["object","null"],"additionalProperties":false,"properties":{"user_agent":{"description":"The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.","type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/code/verify":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Approve with a code alone: check the code","description":"Send `code_id` and `code`. A wrong code returns `wrong_code` with tries left. The right code approves the extra (`decided_via: one_time_code`, recorded as approved with a texted code) and `incremental_charge.approved` follows.","operationId":"post_v1_incremental_charges_id_code_verify","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["code_id","code"],"properties":{"code_id":{"description":"The id of a sent code. Send it back with the code the customer types.","type":"string","maxLength":40},"code":{"description":"A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.","type":"string","maxLength":12},"user_agent":{"description":"The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.","type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/passkey/report":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Report what happened on the device","description":"Optional. Tell Wilby what happened on your page or in your app, so \"Approvals by Device\" covers it: `step` (authenticate, register, setup, code), `outcome` (cancelled, no_passkey_here, failed, rescue_shown, rescue_setup, rescue_code, rescue_retry, rescue_other…), a short `reason` (the browser's error name) and the customer's `user_agent`. Only the device kind, browser and system are kept, 13 months. Answers 204.","operationId":"post_v1_incremental_charges_id_passkey_report","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["step","outcome"],"properties":{"step":{"description":"Which step: begin, finish, set_up_send, set_up_verify, code_send, code_verify, report.","type":"string","enum":["authenticate","register","setup","code"]},"outcome":{"description":"How it ended.","type":"string","enum":["ok","cancelled","no_passkey_here","failed","error","wrong_code","rescue_shown","rescue_setup","rescue_code","rescue_retry","rescue_other"]},"reason":{"description":"Why, as a code or in words. On an incremental charge: the store's reason the customer sees.","type":"string","maxLength":80},"user_agent":{"description":"The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.","type":"string","maxLength":1000}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/approval-step":{"post":{"tags":["Incremental Charges and Tips"],"summary":"The approve helper's one route (Wilby.approve)","description":"Since 0.67.2. Your website loads /kit/v1/approve.js and calls `Wilby.approve({ incrementalChargeId, send })`; `send` posts the helper's body to your server, which forwards it here unchanged with your API key (only for the signed-in customer's own charge) and returns Wilby's answer, errors included. `step` is one of begin, finish, set_up_send, set_up_verify, code_send, code_verify, report; each does what the matching route above does. `status: \"approved\"` means the customer said yes, not that money moved: keep showing a charging state until your charge has had its chance, then show \"Approved\" or the decline. The helper runs the whole device side: Face ID / Touch ID / fingerprint, \"Set Up {lock} on {device}\" with a texted code, \"Approve With a Code\", and Wilby's page for browsers that can't (Safari before 18, Firefox). Your website must be in `passkey_websites.in_page`.","operationId":"post_v1_incremental_charges_id_approval_step","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["step"],"properties":{"step":{"description":"Which step: begin, finish, set_up_send, set_up_verify, code_send, code_verify, report.","type":"string","enum":["begin","finish","set_up_send","set_up_verify","code_send","code_verify","report"]},"incremental_charge_id":{"description":"The incremental charge's id (`top_…`).","type":"string","maxLength":40},"user_agent":{"description":"The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.","type":"string","maxLength":1000},"ceremony_id":{"description":"The id of a Face ID / Touch ID / fingerprint prompt. Send it back when finishing.","type":"string","maxLength":40},"response":{"description":"The browser's WebAuthn answer, passed through unchanged."},"code_id":{"description":"The id of a sent code. Send it back with the code the customer types.","type":"string","maxLength":40},"code":{"description":"A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.","type":"string","maxLength":12},"report_step":{"description":"Which approval step is being reported.","type":"string","enum":["authenticate","register","setup","code"]},"outcome":{"description":"How it ended.","type":"string","enum":["ok","cancelled","no_passkey_here","failed","error","wrong_code","rescue_shown","rescue_setup","rescue_code","rescue_retry","rescue_other"]},"reason":{"description":"Why, as a code or in words. On an incremental charge: the store's reason the customer sees.","type":"string","maxLength":80}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/approval-attempts":{"get":{"tags":["Incremental Charges and Tips"],"summary":"Where approving gets stuck, by device","description":"Last `days` (1–90, default 30), by device, browser and system, worst first: approved, cancelled, no passkey here, failed, set up here, and the most common reasons. Covers Wilby's page, the web script and your server's passkey steps. Also on the dashboard (Waiting).","operationId":"get_v1_approval_attempts","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90},"description":"A number of days, or the days of the week (0 = Sunday) for hours."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/link":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Get a fresh approval link for a waiting incremental charge","description":"To send it again. Earlier links for it stop working (they say a newer link was sent). Same answer-by time.","operationId":"post_v1_incremental_charges_id_link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/incremental-charges/{id}/cancel":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Withdraw a request the store sent","description":"While it waits for the customer (for example the store typed the wrong amount), or after the customer approved it while nothing has been paid for it yet (you run the charges and the price changed, or the charge was declined). Nothing more is charged, the customer's link shows \"Request Withdrawn\", `customer_status` becomes `withdrawn`, the order goes back to where it was, and `incremental_charge.cancelled` is sent. Once a payment was reported for it, this is refused with `already_paid`: refund instead.","operationId":"post_v1_incremental_charges_id_cancel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"description":"Why, as a code or in words. On an incremental charge: the store's reason the customer sees.","type":"string","minLength":1,"maxLength":300}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/tip-link":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Get a tip link for the customer","operationId":"post_v1_orders_id_tip_link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"valid_days":{"description":"How many days the link works.","type":"integer","minimum":1,"maximum":30}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/customers/overage-link":{"post":{"tags":["Customer Permissions"],"summary":"Get a link where the customer sets their own limits","description":"Optional `return_url`: where the page sends the customer after saving.","operationId":"post_v1_customers_overage_link","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["customer_external_ref"],"properties":{"customer_external_ref":{"description":"Your own id for the customer.","type":"string","minLength":1,"maxLength":200},"return_url":{"description":"Where Wilby's pages send the customer when they are done (https, or your app's own link).","type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/customers/mandate-link":{"post":{"tags":["Customer Permissions"],"summary":"Get a link where the customer gives an AI agent a limited permission, or sees and turns off their agents","description":"With `manage_only: true` the link opens \"Your AI Agents\": every agent the customer allowed, what it ordered and spent, Turn Off, Turn Off All, and Get Proof (a signed, shareable proof of what they allowed, when they turned it off, and that nothing happened after). Put it behind a \"Your AI Agents\" button in your app: call this when the button is tapped, so each link is fresh.","operationId":"post_v1_customers_mandate_link","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["customer_external_ref"],"properties":{"customer_external_ref":{"description":"Your own id for the customer.","type":"string","minLength":1,"maxLength":200},"payment_method_ref":{"description":"Your processor's id for the customer's saved card or bank account.","type":"string","minLength":1,"maxLength":200},"agent_name":{"description":"The agent's display name, as the customer named it or as the platform reports it.","type":"string","maxLength":60},"per_order_cents":{"description":"The most per order.","type":"integer","minimum":100,"maximum":10000000000},"monthly_cents":{"description":"The most per month.","type":"integer","minimum":100,"maximum":10000000000},"merchant_external_refs":{"description":"Your own ids for the stores.","type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":200}},"days":{"description":"A number of days, or the days of the week (0 = Sunday) for hours.","type":"integer","enum":[30,90,180,365]},"valid_hours":{"description":"How many hours the link works.","type":"integer","minimum":1,"maximum":168},"manage_only":{"description":"True for a link that only lets the customer manage existing permissions.","type":"boolean"},"bank":{"description":"Bank account details for an ACH debit authorization.","type":"object","additionalProperties":false,"properties":{"bank_name":{"description":"The bank's name.","type":"string","maxLength":80},"account_last4":{"description":"Last 4 digits of the bank account.","type":"string","pattern":"^[0-9]{4}$"},"processor_mandate_ref":{"description":"The bank mandate's id at your processor.","type":"string","maxLength":200},"range_cents":{"description":"The allowed amount range.","type":["integer","null"],"minimum":0,"maximum":10000000}}}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/mandates":{"get":{"tags":["Customer Permissions"],"summary":"List agent permissions","operationId":"get_v1_mandates","parameters":[{"name":"customer_external_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id for the customer."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/trusted-issuers":{"get":{"tags":["Outside Agent Permissions"],"summary":"List agent platforms and card issuers whose permissions can be accepted","operationId":"get_v1_trusted_issuers","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/trusted-issuers/{id}/enable":{"post":{"tags":["Outside Agent Permissions"],"summary":"Trust a platform or issuer for your stores","operationId":"post_v1_trusted_issuers_id_enable","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^tis_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/trusted-issuers/{id}/disable":{"post":{"tags":["Outside Agent Permissions"],"summary":"Stop trusting a platform or issuer","operationId":"post_v1_trusted_issuers_id_disable","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^tis_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/sandbox/test-store":{"post":{"tags":["Sandbox"],"summary":"Make a fresh test store","description":"Sandbox records are permanent like live ones, so instead of resetting, start over with a new store.","operationId":"post_v1_sandbox_test_store","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"description":"A name.","type":"string","minLength":1,"maxLength":80}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/sandbox/payments-path":{"post":{"tags":["Sandbox"],"summary":"Switch who charges the card in your sandbox","description":"`wilby_charges` (Wilby holds and charges through your processor account) or `you_charge` (you charge with your own processor and report). Applies at once.","operationId":"post_v1_sandbox_payments_path","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["path"],"properties":{"path":{"description":"Which way to integrate, or a path.","type":"string","enum":["wilby_charges","you_charge"]}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/sandbox/emails":{"get":{"tags":["Sandbox"],"summary":"Emails Wilby would have sent to test addresses","description":"Codes emailed to reserved test addresses (example.com, .test, .example, .invalid) are kept here instead of sent, newest first, for one day. Filter with `to`.","operationId":"get_v1_sandbox_emails","parameters":[{"name":"to","in":"query","required":false,"schema":{"type":"string","maxLength":254},"description":"End date (YYYY-MM-DD) or end of the range."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/sandbox/outside-mandates":{"post":{"tags":["Sandbox"],"summary":"Sign a test AP2, Verifiable Intent or ACP permission","description":"Uses built-in test issuers so you can try outside permissions end to end.","operationId":"post_v1_sandbox_outside_mandates","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"format":{"description":"The format of the file or credential.","type":"string","enum":["ap2","vi","acp"]},"user_public_jwk":{"description":"Test tools: the customer device's public key (P-256 JWK).","type":"object"},"complete_request":{"description":"The full signed request the agent platform sent, for Wilby to check.","type":"string","maxLength":60000},"agent_public_jwk":{"description":"Test tools: the agent's public key (P-256 JWK) for a test credential.","type":"object"},"per_order_cents":{"description":"The most per order.","type":"integer","minimum":100,"maximum":10000000000},"monthly_cents":{"description":"The most per month.","type":"integer","minimum":100,"maximum":10000000000},"merchant_external_refs":{"description":"Your own ids for the stores.","type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":200}},"days":{"description":"A number of days, or the days of the week (0 = Sunday) for hours.","type":"integer","minimum":1,"maximum":365}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/mandates/{id}/credentials":{"get":{"tags":["Outside Agent Permissions"],"summary":"Get the signed mandates for a permission","operationId":"get_v1_mandates_id_credentials","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^dlg_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/credentials":{"get":{"tags":["Outside Agent Permissions"],"summary":"Get the signed permissions kept with an order","operationId":"get_v1_orders_id_credentials","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/mandates/{id}/revoke":{"post":{"tags":["Customer Permissions"],"summary":"Turn a permission off","operationId":"post_v1_mandates_id_revoke","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^dlg_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/approvals":{"post":{"tags":["Platform-Run Payments"],"summary":"Ask for a signed yes or no before charging","operationId":"post_v1_orders_id_approvals","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["kind","amount_cents"],"properties":{"kind":{"description":"What kind it is. On an approval: authorize, capture, charge or refund. On a payment report: what happened.","type":"string","enum":["authorize","charge","capture","void","refund","replace_hold"]},"amount_cents":{"description":"An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.","type":"integer","minimum":0,"maximum":10000000000}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/hold":{"post":{"tags":["Platform-Run Payments"],"summary":"Take the hold in one call (agent orders)","description":"Since 0.68.0. Confirms the order if needed, asks Wilby for an authorize approval for `amount_cents`, and records your hold (`processor`, `processor_ref`, `status`), the same as /confirm, /approvals and /payments in a row. Use it for an order an agent placed through your storefront, after you answered /orders or when `order.created` arrives. If Wilby doesn't allow it: 409 `not_allowed` (release the hold, cancel your order).","operationId":"post_v1_orders_id_hold","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["amount_cents","processor","processor_ref","status"],"properties":{"amount_cents":{"description":"An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.","type":"integer","minimum":0,"maximum":10000000000},"processor":{"description":"The payment processor (stripe, square, braintree, adyen, paypal).","type":"string","minLength":1,"maxLength":40},"processor_ref":{"description":"The payment's id at the processor (for example a Stripe PaymentIntent).","type":"string","minLength":1,"maxLength":200},"status":{"description":"Where it stands. On an incremental charge: pending, approved, declined, expired, cancelled.","type":"string","enum":["succeeded","failed","pending"]},"rail":{"description":"How the money moves: card or ach.","type":"string","enum":["card","ach","instant_bank","rtp","fednow","cash","other"]},"failure_reason":{"description":"Why it failed.","type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/payments":{"post":{"tags":["Platform-Run Payments"],"summary":"Report a payment you made","description":"See the Platform Integration guide for what to report for each store action. When an AI agent paid, add `agent_payment` (`paid_with`: link_agent_wallet, mastercard_agent_pay, visa_intelligent_commerce, agent_one_time_token, paypal_wallet, google_pay, saved_card, bank_debit or other; optional `agent` and `reference`): recorded as reported by you. A payment the customer chose themselves (tip, something they added, a payment link they paid) is sent with `customer_initiated`: it needs no approval and never counts toward their limit. For an incremental charge, send `incremental_charge_id`. A failed charge for an approved extra: `status: \"failed\"` with `incremental_charge_id` and `failure_reason`; the incremental charge shows \"Approved, Payment Failed\" until a later charge with the same `incremental_charge_id` pays it.","operationId":"post_v1_orders_id_payments","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["kind","amount_cents","processor","processor_ref","status"],"properties":{"kind":{"description":"What kind it is. On an approval: authorize, capture, charge or refund. On a payment report: what happened.","type":"string","enum":["authorize","charge","capture","void","refund","replace_hold"]},"amount_cents":{"description":"An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.","type":"integer","minimum":0,"maximum":10000000000},"processor":{"description":"The payment processor (stripe, square, braintree, adyen, paypal).","type":"string","minLength":1,"maxLength":40},"processor_ref":{"description":"The payment's id at the processor (for example a Stripe PaymentIntent).","type":"string","minLength":1,"maxLength":200},"status":{"description":"Where it stands. On an incremental charge: pending, approved, declined, expired, cancelled.","type":"string","enum":["succeeded","failed","pending"]},"approval_id":{"description":"The id of the approval Wilby gave (the signed yes for a payment).","type":"string","pattern":"^evt_[0-9a-z]{20}$"},"incremental_charge_id":{"description":"The incremental charge's id (`top_…`).","type":"string","pattern":"^top_[0-9a-z]{20}$"},"failure_reason":{"description":"Why it failed.","type":"string","maxLength":200},"rail":{"description":"How the money moves: card or ach.","type":"string","enum":["card","ach","instant_bank","rtp","fednow","cash","other"]},"paid_with":{"description":"How it was paid (card, Google Pay, bank, agent token).","type":"string","enum":["chatgpt_wallet"]},"agent_request":{"description":"The agent's signed HTTP request (RFC 9421 message signature) that asked for the payment.","type":"object","additionalProperties":false,"required":["signature_input","signature","authority","path"],"properties":{"signature_input":{"description":"The Signature-Input header of the signed request.","type":"string","maxLength":2000},"signature":{"description":"The signature.","type":"string","maxLength":2000},"signature_agent":{"description":"The Signature-Agent header (who the agent says it is).","type":"string","maxLength":300},"authority":{"description":"The request address (host) in a signed HTTP request.","type":"string","maxLength":255},"path":{"description":"Which way to integrate, or a path.","type":"string","maxLength":2000}}},"payment_account_reference":{"description":"The card network's Payment Account Reference (PAR), when your processor gives it.","type":"string","maxLength":64},"agent_payment":{"description":"The payment as the agent platform made it (for agent-paid orders): how it was paid and its reference.","type":"object","additionalProperties":false,"required":["paid_with"],"properties":{"paid_with":{"description":"How it was paid (card, Google Pay, bank, agent token).","type":"string","enum":["link_agent_wallet","mastercard_agent_pay","visa_intelligent_commerce","agent_one_time_token","paypal_wallet","google_pay","saved_card","bank_debit","other"]},"agent":{"description":"The AI agent, by its short name (claude, chatgpt, gemini, copilot, perplexity, grok, other).","type":"string","enum":["claude","chatgpt","gemini","copilot","perplexity","meta","other"]},"reference":{"description":"The payment's reference at the agent platform.","type":"string","maxLength":200}}},"customer_initiated":{"description":"A payment the customer started themselves after the order (`tip`, `add_on`, `payment_link`, `other`).","type":"object","additionalProperties":false,"required":["purpose"],"properties":{"purpose":{"description":"What the order is for, in plain words.","type":"string","enum":["tip","add_on","payment_link","other"]},"note":{"description":"A note in plain words.","type":"string","maxLength":200}}}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/event-types":{"get":{"tags":["Webhooks"],"summary":"List event types","operationId":"get_v1_event_types","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/webhook-endpoints":{"post":{"tags":["Webhooks"],"summary":"Add a webhook endpoint","description":"Returns the signing secret once.","operationId":"post_v1_webhook_endpoints","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["url"],"properties":{"url":{"description":"An address.","type":"string","minLength":8,"maxLength":500},"events":{"description":"Webhook event types to send (`order.*`, `incremental_charge.approved`…), or `*` for all.","type":"array","minItems":1,"maxItems":40,"uniqueItems":true,"items":{"type":"string","enum":["*","order.*","payment.*","refund.*","charge.*","incremental_charge.*","authorization.*","tip.*","evidence.*","dispute.*","customer.*","credential.*","order.created","order.confirmed","order.authorized","order.authorization_failed","order.captured","order.cancelled","order.expired","payment.authorized","payment.captured","payment.charged","payment.voided","payment.refunded","payment.authorize_failed","payment.charge_failed","payment.capture_failed","payment.void_failed","payment.refund_failed","payment.reported","payment.reported_unapproved","payment.cleared","payment.returned","refund.waiting_for_bank","charge.approval","incremental_charge.requested","incremental_charge.approved","incremental_charge.declined","incremental_charge.expired","incremental_charge.charge_failed","incremental_charge.cancelled","authorization.captured_early","authorization.reauthorized","authorization.expired","authorization.expiring_soon","tip.added","evidence.added","refund.goodwill","dispute.opened","dispute.sent_to_review","dispute.resolved","dispute.chargeback_received","customer.code_requested","credential.issued"]}},"description":{"description":"Plain text describing it. On an order: what was ordered.","type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","operationId":"get_v1_webhook_endpoints","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/webhook-endpoints/{id}":{"post":{"tags":["Webhooks"],"summary":"Update a webhook endpoint","operationId":"post_v1_webhook_endpoints_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^whe_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"url":{"description":"An address.","type":"string","minLength":8,"maxLength":500},"events":{"description":"Webhook event types to send (`order.*`, `incremental_charge.approved`…), or `*` for all.","type":"array","minItems":1,"maxItems":40,"uniqueItems":true,"items":{"type":"string","enum":["*","order.*","payment.*","refund.*","charge.*","incremental_charge.*","authorization.*","tip.*","evidence.*","dispute.*","customer.*","credential.*","order.created","order.confirmed","order.authorized","order.authorization_failed","order.captured","order.cancelled","order.expired","payment.authorized","payment.captured","payment.charged","payment.voided","payment.refunded","payment.authorize_failed","payment.charge_failed","payment.capture_failed","payment.void_failed","payment.refund_failed","payment.reported","payment.reported_unapproved","payment.cleared","payment.returned","refund.waiting_for_bank","charge.approval","incremental_charge.requested","incremental_charge.approved","incremental_charge.declined","incremental_charge.expired","incremental_charge.charge_failed","incremental_charge.cancelled","authorization.captured_early","authorization.reauthorized","authorization.expired","authorization.expiring_soon","tip.added","evidence.added","refund.goodwill","dispute.opened","dispute.sent_to_review","dispute.resolved","dispute.chargeback_received","customer.code_requested","credential.issued"]}},"description":{"description":"Plain text describing it. On an order: what was ordered.","type":"string","maxLength":200},"enabled":{"description":"Whether it is turned on.","type":"boolean"}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"delete":{"tags":["Webhooks"],"summary":"Remove a webhook endpoint","operationId":"delete_v1_webhook_endpoints_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^whe_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/webhook-endpoints/{id}/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotate an endpoint's signing secret","operationId":"post_v1_webhook_endpoints_id_rotate_secret","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^whe_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/webhook-endpoints/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Send a signed test ping","operationId":"post_v1_webhook_endpoints_id_test","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^whe_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/webhook-deliveries":{"get":{"tags":["Webhooks"],"summary":"List deliveries and their results","operationId":"get_v1_webhook_deliveries","parameters":[{"name":"order_id","in":"query","required":false,"schema":{"type":"string","maxLength":40},"description":"The order's id (`prm_…`)."},{"name":"endpoint_id","in":"query","required":false,"schema":{"type":"string","maxLength":40},"description":"A webhook endpoint's id."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","delivered","failed","cancelled"]},"description":"Where it stands. On an incremental charge: pending, approved, declined, expired, cancelled."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"How many to return (paging)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/webhook-deliveries/{id}/retry":{"post":{"tags":["Webhooks"],"summary":"Retry a delivery now","operationId":"post_v1_webhook_deliveries_id_retry","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^whd_[0-9a-f]{32}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/analytics/summary":{"get":{"tags":["Reports"],"summary":"Totals for a date range","operationId":"get_v1_analytics_summary","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","maxLength":10},"description":"Start date (YYYY-MM-DD) or start of the range."},{"name":"to","in":"query","required":false,"schema":{"type":"string","maxLength":10},"description":"End date (YYYY-MM-DD) or end of the range."},{"name":"merchant_id","in":"query","required":false,"schema":{"type":"string","maxLength":40},"description":"Wilby's id for the store (`mer_…`)."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","maxLength":64},"description":"An IANA time zone, like America/New_York."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/analytics/daily":{"get":{"tags":["Reports"],"summary":"Day-by-day figures","operationId":"get_v1_analytics_daily","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","maxLength":10},"description":"Start date (YYYY-MM-DD) or start of the range."},{"name":"to","in":"query","required":false,"schema":{"type":"string","maxLength":10},"description":"End date (YYYY-MM-DD) or end of the range."},{"name":"merchant_id","in":"query","required":false,"schema":{"type":"string","maxLength":40},"description":"Wilby's id for the store (`mer_…`)."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","maxLength":64},"description":"An IANA time zone, like America/New_York."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/analytics/stores":{"get":{"tags":["Reports"],"summary":"Figures per store","operationId":"get_v1_analytics_stores","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","maxLength":10},"description":"Start date (YYYY-MM-DD) or start of the range."},{"name":"to","in":"query","required":false,"schema":{"type":"string","maxLength":10},"description":"End date (YYYY-MM-DD) or end of the range."},{"name":"merchant_id","in":"query","required":false,"schema":{"type":"string","maxLength":40},"description":"Wilby's id for the store (`mer_…`)."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","maxLength":64},"description":"An IANA time zone, like America/New_York."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/analytics/orders.csv":{"get":{"tags":["Reports"],"summary":"Export orders as CSV (no customer names or contact details)","operationId":"get_v1_analytics_orders_csv","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","maxLength":10},"description":"Start date (YYYY-MM-DD) or start of the range."},{"name":"to","in":"query","required":false,"schema":{"type":"string","maxLength":10},"description":"End date (YYYY-MM-DD) or end of the range."},{"name":"merchant_id","in":"query","required":false,"schema":{"type":"string","maxLength":40},"description":"Wilby's id for the store (`mer_…`)."},{"name":"tz","in":"query","required":false,"schema":{"type":"string","maxLength":64},"description":"An IANA time zone, like America/New_York."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/analytics/dashboard-link":{"post":{"tags":["Reports"],"summary":"Make a private live-dashboard link (for one store or all)","operationId":"post_v1_analytics_dashboard_link","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"merchant_id":{"description":"Wilby's id for the store (`mer_…`).","type":"string","maxLength":40},"valid_hours":{"description":"How many hours the link works.","type":"integer","minimum":1,"maximum":720},"label":{"description":"A short name shown to people.","type":"string","maxLength":80},"tz":{"description":"An IANA time zone, like America/New_York.","type":"string","maxLength":64}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/dashboard/open":{"post":{"tags":["Reports"],"summary":"Open Dashboard from your admin (one-time link)","description":"Returns a one-time `url` (15 minutes) to the hosted Dashboard: orders, waiting, AI agents, settings. Name the staff member in `staff_name`; with `can_edit` they may change which agents may order, signed under their name. Opens an 8-hour session.","operationId":"post_v1_dashboard_open","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["staff_name"],"properties":{"staff_name":{"description":"The name of the person opening the Dashboard.","type":"string","minLength":1,"maxLength":80},"staff_ref":{"description":"Your id for that person.","type":"string","minLength":1,"maxLength":120},"can_edit":{"description":"Whether this dashboard link can change settings (or only view).","type":"boolean"},"merchant_id":{"description":"Wilby's id for the store (`mer_…`).","type":"string","maxLength":40},"tz":{"description":"An IANA time zone, like America/New_York.","type":"string","maxLength":64},"page":{"description":"Which page to open.","type":"string","enum":["overview","orders","waiting","assistants","readiness","listing","setup"]},"order_id":{"description":"The order's id (`prm_…`).","type":"string","pattern":"^prm_[0-9a-z]{20}$"}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/analytics/dashboard-link/{id}":{"delete":{"tags":["Reports"],"summary":"Turn a dashboard link off","operationId":"delete_v1_analytics_dashboard_link_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^dsh_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/customers/ach-authorization-link":{"post":{"tags":["Bank Payments"],"summary":"Get a link where the customer signs a bank debit authorization","operationId":"post_v1_customers_ach_authorization_link","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["customer_external_ref"],"properties":{"customer_external_ref":{"description":"Your own id for the customer.","type":"string","minLength":1,"maxLength":200},"payment_method_ref":{"description":"Your processor's id for the customer's saved card or bank account.","type":"string","minLength":1,"maxLength":200},"rail":{"description":"How the money moves: card or ach.","type":"string","enum":["ach","instant_bank"]},"bank_name":{"description":"The bank's name.","type":"string","maxLength":80},"account_last4":{"description":"Last 4 digits of the bank account.","type":"string","pattern":"^[0-9]{4}$"},"processor_mandate_ref":{"description":"The bank mandate's id at your processor.","type":"string","maxLength":200},"per_order_cents":{"description":"The most per order.","type":"integer","minimum":100,"maximum":50000000},"range_cents":{"description":"The allowed amount range.","type":["integer","null"],"minimum":0,"maximum":50000000},"monthly_cents":{"description":"The most per month.","type":"integer","minimum":100,"maximum":50000000},"merchant_external_refs":{"description":"Your own ids for the stores.","type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":1,"maxLength":200}},"days":{"description":"A number of days, or the days of the week (0 = Sunday) for hours.","type":"integer","enum":[90,180,365,730]},"valid_hours":{"description":"How many hours the link works.","type":"integer","minimum":1,"maximum":168}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/ach-authorizations":{"get":{"tags":["Bank Payments"],"summary":"List signed ACH debit authorizations","operationId":"get_v1_ach_authorizations","parameters":[{"name":"customer_external_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id for the customer."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/ach-authorizations/{id}/revoke":{"post":{"tags":["Bank Payments"],"summary":"Revoke an ACH debit authorization","operationId":"post_v1_ach_authorizations_id_revoke","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^bka_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/retry-payment":{"post":{"tags":["Bank Payments"],"summary":"Retry a returned bank debit (within Nacha's retry limits)","operationId":"post_v1_orders_id_retry_payment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/payments/{id}/bank-outcome":{"post":{"tags":["Platform-Run Payments"],"summary":"Report how a bank debit ended (cleared or returned)","operationId":"post_v1_payments_id_bank_outcome","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^pay_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"description":"Where it stands. On an incremental charge: pending, approved, declined, expired, cancelled.","type":"string","enum":["succeeded","returned"]},"return_code":{"description":"The bank's return code (for example R01).","type":"string","pattern":"^R[0-9]{2}$"}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/bank-returns/health":{"get":{"tags":["Bank Payments"],"summary":"Return rates over the last 60 days, against Nacha thresholds","operationId":"get_v1_bank_returns_health","parameters":[{"name":"merchant_external_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id for the store."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/sandbox/bank-reconcile":{"post":{"tags":["Sandbox"],"summary":"Clear or return pending test bank debits now","operationId":"post_v1_sandbox_bank_reconcile","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/merchants/{ref}/connect-link":{"post":{"tags":["Stores"],"summary":"Get a link for the store owner to connect their own account","description":"Square: \"Connect with Square\" (the owner approves on Square). Braintree: the owner enters the store's own API keys, checked with Braintree first. Adyen: the owner enters the store's API key, merchant account and webhook HMAC key, checked with Adyen first. PayPal: the owner enters the client ID and secret of their PayPal app, checked with PayPal first; Wilby adds its webhook to that app. Valid 7 days, used once. Credentials are stored encrypted and never shown again.","operationId":"post_v1_merchants_ref_connect_link","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id (in the address)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["processor"],"properties":{"processor":{"description":"The payment processor (stripe, square, braintree, adyen, paypal).","type":"string","enum":["square","braintree","adyen","paypal"]}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/merchants/{ref}/connections":{"get":{"tags":["Stores"],"summary":"See which account a store's payments run on (its own, or platform keys)","operationId":"get_v1_merchants_ref_connections","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id (in the address)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/merchants/{ref}/disconnect":{"post":{"tags":["Stores"],"summary":"Disconnect a store's own account","description":"Square access is revoked at Square too. The store goes back to platform keys, if any.","operationId":"post_v1_merchants_ref_disconnect","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id (in the address)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["processor"],"properties":{"processor":{"description":"The payment processor (stripe, square, braintree, adyen, paypal).","type":"string","enum":["square","braintree","adyen","paypal"]}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/bank-accounts":{"post":{"tags":["Bank Payments"],"summary":"Save and verify a customer's bank account (Braintree)","description":"Send the one-time token from Braintree's bank form. `network_check` verifies at once; `micro_transfers` sends two small deposits the customer confirms. If your Braintree account does not have network check turned on, the answer has `error: verification_not_enabled`: use `micro_transfers` or ask Braintree to turn it on.","operationId":"post_v1_bank_accounts","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["merchant_external_ref","token"],"properties":{"merchant_external_ref":{"description":"Your own id for the store.","type":"string","minLength":1,"maxLength":200},"token":{"description":"A one-time token from your processor's bank account form.","type":"string","minLength":4,"maxLength":200},"verification":{"description":"How to verify it.","type":"string","enum":["network_check","micro_transfers"]}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/bank-accounts/confirm":{"post":{"tags":["Bank Payments"],"summary":"Confirm the two test deposit amounts","operationId":"post_v1_bank_accounts_confirm","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["merchant_external_ref","verification_id","amounts_cents"],"properties":{"merchant_external_ref":{"description":"Your own id for the store.","type":"string","minLength":1,"maxLength":200},"verification_id":{"description":"The bank account check's id.","type":"string","minLength":4,"maxLength":200},"amounts_cents":{"description":"The two small test deposit amounts, in cents, that confirm a bank account.","type":"array","minItems":2,"maxItems":2,"items":{"type":"integer","minimum":1,"maximum":99}}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/settings/stripe-key":{"post":{"tags":["Stores"],"summary":"Save your own Stripe key (Wilby charges on your Stripe)","description":"A restricted key (rk_test_… on sandbox, rk_live_… on live) for your Stripe platform or account. Checked with Stripe, then sealed; never shown again (GET /v1/settings shows its kind and last 4). Stores under your platform use their connected account id as `processor_account_ref`; a store on your own account uses `\"self\"`. Without a key, Wilby uses its own Stripe platform.","operationId":"post_v1_settings_stripe_key","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["stripe_key"],"properties":{"stripe_key":{"description":"Your Stripe restricted key (saved, never shown again).","type":"string","minLength":10,"maxLength":300}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"delete":{"tags":["Stores"],"summary":"Remove your Stripe key","operationId":"delete_v1_settings_stripe_key","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/settings/google-orders":{"post":{"tags":["Agent Storefront"],"summary":"Save your Google key for order updates (UCP)","description":"`{\"google_partner_id\", \"api_key\"}` from Google's UCP onboarding. Sealed and never shown again (GET /v1/settings shows the platform id and the key's last 4). For orders Google places, Wilby sends Google: order placed, shipped and delivered (with tracking), cancellations, refunds and disputes.","operationId":"post_v1_settings_google_orders","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["google_partner_id","api_key"],"properties":{"google_partner_id":{"description":"Your Google partner id.","type":"string","minLength":1,"maxLength":100},"api_key":{"description":"A key you got from another service (Google order updates, a processor). Kept on Wilby's server; never shown again.","type":"string","minLength":10,"maxLength":300}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"delete":{"tags":["Agent Storefront"],"summary":"Remove your Google key for order updates","operationId":"delete_v1_settings_google_orders","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/ucp/order-updates":{"get":{"tags":["Agent Storefront"],"summary":"Order updates sent to platforms and Google (UCP)","description":"The last 100, with what each answered. `needs_attention=true`: only updates Google refused (4xx), which are never retried unchanged; fix the cause (often a missing tracking link or the key) and report the order again.","operationId":"get_v1_ucp_order_updates","parameters":[{"name":"needs_attention","in":"query","required":false,"schema":{"type":"boolean"},"description":"List only what needs your attention."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/ucp/link-clients":{"post":{"tags":["Agent Storefront"],"summary":"Register a platform for account linking (UCP)","description":"`{\"name\": \"Google\", \"redirect_uris\": [...], \"auth_method\": \"client_secret_basic\" | \"private_key_jwt\", \"jwks_uri\"}`. Returns `client_id` and, for client_secret_basic, `client_secret` (shown once). Enter them in the platform's account-linking setup (Google: Merchant Center).","operationId":"post_v1_ucp_link_clients","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["redirect_uris"],"properties":{"name":{"description":"A name.","type":"string","maxLength":60},"redirect_uris":{"description":"The platform's return addresses for account linking (https).","type":"array","minItems":1,"maxItems":10,"items":{"type":"string","maxLength":500}},"auth_method":{"description":"How the platform signs in to Wilby's account linking: `client_secret_basic` or `private_key_jwt`.","type":"string","enum":["client_secret_basic","private_key_jwt"]},"jwks_uri":{"description":"The https address where the platform publishes its public keys.","type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"get":{"tags":["Agent Storefront"],"summary":"Platforms registered for account linking","description":"Each with how many customers are linked through it now. Secrets are never shown.","operationId":"get_v1_ucp_link_clients","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/ucp/link-clients/{id}/disable":{"post":{"tags":["Agent Storefront"],"summary":"Turn a platform's account linking off","description":"Every customer's link through it ends (each permission revoked, signed on the customer's record) and its tokens stop working.","operationId":"post_v1_ucp_link_clients_id_disable","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^occ_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/storefront/secret":{"post":{"tags":["Agent Storefront"],"summary":"Create the storefront secret","description":"Wilby signs every call to your Storefront API with it (Wilby-Signature header; Openhold-Signature is also sent during the move; same scheme as webhooks). Shown once; a new one replaces the old.","operationId":"post_v1_storefront_secret","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/storefront/sign-ins":{"post":{"tags":["Agent Storefront"],"summary":"Tell Wilby who signed in","description":"Your login page got `openhold_request`; after the customer signs in with their normal account, send `request_id` and your `customer_external_ref` (and `payment_method_ref`, their saved card, if Wilby takes the payment for you). Redirect the customer to the `continue_url` you get back (they set the agent's limits there, in your look).","operationId":"post_v1_storefront_sign_ins","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["request_id","customer_external_ref"],"properties":{"request_id":{"description":"The sign-in request's id (`oar_…` or `csi_…`).","type":"string","pattern":"^(oar|csi)_[0-9a-z]{20}$"},"customer_external_ref":{"description":"Your own id for the customer.","type":"string","minLength":1,"maxLength":200},"payment_method_ref":{"description":"Your processor's id for the customer's saved card or bank account.","type":"string","minLength":3,"maxLength":200}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/integration/check":{"get":{"tags":["Stores"],"summary":"What's done and what's left before going live","description":"From your settings and your last 30 days of activity with this key's mode: stores, orders end to end, reporting (if you charge), webhooks, codes, your look, screens and agents (if used), and going live. Each item is `done`, `check` or `missing`, with the fix and a docs link. Read-only. The same list is the Setup tab in Dashboard.","operationId":"get_v1_integration_check","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/screen-sessions":{"post":{"tags":["Ready-Made Screens"],"summary":"Get a screen pass for one customer","description":"Call from your server (never the browser) and put `client_secret` on the page: `<wilby-order-card client-secret=\"wcs_…\" order-id=\"prm_…\">` or `Wilby.init({clientSecret})`. Up to 30 minutes (`valid_minutes`); `order_id` limits it to one order. It works only from your `screen_origins` (POST /v1/settings) and Wilby's own address; a request with no Origin (a phone app) is allowed. It can read this customer's orders and rule, save the same or a stricter rule, decline an incremental charge and turn an agent off. Approving an incremental charge or a looser rule opens a small Wilby window where the customer confirms it's them.","operationId":"post_v1_screen_sessions","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["customer_external_ref"],"properties":{"customer_external_ref":{"description":"Your own id for the customer.","type":"string","minLength":1,"maxLength":200},"order_id":{"description":"The order's id (`prm_…`).","type":"string","pattern":"^prm_[0-9a-z]{20}$"},"valid_minutes":{"description":"How many minutes it works.","type":"integer","minimum":5,"maximum":30},"customer_contact":{"description":"How to reach the customer for a one-time code: `label` (the name on their passkey) and `email`. Kept 7 days, never in the signed record.","type":"object","additionalProperties":false,"properties":{"label":{"description":"A short name shown to people.","type":["string","null"],"maxLength":80},"email":{"description":"An email address (shown masked when read back).","type":["string","null"],"maxLength":254}}}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/customers/{ref}/contact":{"post":{"tags":["Customer Permissions"],"summary":"How to reach a customer for a one-time code, and the name on their passkey","description":"`email`: where Wilby emails a one-time code when you don't text codes yourself (customers whose phone has no screen lock, and a customer's first setup). `label`: shown on their passkey (\"Example Shop · Jane D.\"); without it the passkey is saved as \"Your Example Shop Account\" (your business name). Kept 7 days after you last send it, then deleted; never put in the signed record. The same block can go with an incremental charge (`customer_contact` on POST /v1/orders/{id}/incremental-charges), a screen pass, or the in-app approval.","operationId":"post_v1_customers_ref_contact","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id (in the address)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"label":{"description":"A short name shown to people.","type":["string","null"],"maxLength":80},"email":{"description":"An email address (shown masked when read back).","type":["string","null"],"maxLength":254}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/customers/{ref}/payment-method":{"post":{"tags":["Customer Permissions"],"summary":"Change a customer's saved payment method","description":"When the customer changes their card in your app. Wilby charges the new one from the next payment on.","operationId":"post_v1_customers_ref_payment_method","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id (in the address)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["payment_method_ref"],"properties":{"payment_method_ref":{"description":"Your processor's id for the customer's saved card or bank account.","type":"string","minLength":3,"maxLength":200}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/settings":{"get":{"tags":["Stores"],"summary":"Your settings: extra-charge choices and your look on customer pages","operationId":"get_v1_settings","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"post":{"tags":["Stores"],"summary":"Change your settings","description":"Every setting is explained on the Settings page (/docs/settings). `rule_choices_pct` (1 to 4 percents; \"always ask me first\" is always offered), `recommended_pct`, `branding` (display name, color, logo, whether the Wilby line shows), and `return_url` (default \"back to your app\" address for every customer page), `wording` (your own lines on customer pages) and `apps` (your iOS app ids and Android packages with signing-certificate fingerprints, to approve inside your app). `agent_access` chooses which AI agents may order from you: `{\"mode\": \"all\", \"blocked\": [\"perplexity\"]}` or `{\"mode\": \"only\", \"allowed\": [\"claude\", \"chatgpt\"]}`, plus `\"verified_only\": true` to require a signed identity. `screen_origins`: your websites where Wilby's ready-made screens run (up to 10 https origins). `first_setup_code` (default true): before a customer's first passkey is set up, a one-time code proves it's them (when a code can reach them: your text or Wilby's email). `ucp`: take Google's agent checkout (UCP): `{\"enabled\": true, \"website_url\", \"terms_url\", \"require_signatures\", \"google_pay\": {\"gateway\", \"gateway_merchant_id\", \"merchant_id\", \"merchant_name\"}}` (needs the storefront on with the catalog answer; see Agent Storefront).","operationId":"post_v1_settings","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"return_url":{"description":"Where Wilby's pages send the customer when they are done (https, or your app's own link).","type":["string","null"],"maxLength":500},"wording":{"description":"Your own lines on customer pages (keys like `extra_title`; null goes back to Wilby's default).","type":"object","additionalProperties":{"type":["string","null"],"maxLength":200}},"storefront":{"description":"Your Agent Storefront: `enabled`, `slug`, `name`, `description`, `login_url`, `api_url`, `answers`, `extras`, `times_path`.","type":"object","additionalProperties":false,"properties":{"enabled":{"description":"Whether it is turned on.","type":"boolean"},"slug":{"description":"Your storefront's short name in its address (3–40 lowercase letters, digits and dashes).","type":["string","null"],"maxLength":40},"name":{"description":"A name.","type":["string","null"],"maxLength":60},"description":{"description":"Plain text describing it. On an order: what was ordered.","type":["string","null"],"maxLength":300},"login_url":{"description":"Your sign-in page for customers connecting an AI agent.","type":["string","null"],"maxLength":500},"api_url":{"description":"Your Storefront API base address; Wilby calls it with signed requests.","type":["string","null"],"maxLength":500},"answers":{"description":"What your Agent Storefront answers: `locations`, `times`, `catalog`, `delivery`, `addresses`.","type":"array","minItems":1,"maxItems":5,"items":{"type":"string","enum":["locations","times","catalog","delivery","addresses"]}},"extras":{"description":"Storefront: the extras you accept (`tip`, `promo_code`, `rewards`). In a quote request: what the customer asked for.","type":"array","maxItems":3,"items":{"type":"string","enum":["tip","promo_code","rewards"]}},"times_path":{"description":"Your open-times endpoint: `/pickup-times` (default) or `/open-times`.","type":"string","enum":["/open-times","/pickup-times"]}}},"apps":{"description":"Your iOS and Android apps, so customers can approve inside your app.","type":"object","additionalProperties":false,"properties":{"ios":{"description":"Your iOS app ids (Team ID + bundle id).","type":"array","maxItems":5,"items":{"type":"string","maxLength":170}},"android":{"description":"Your Android apps: `package_name` and `sha256_cert_fingerprints`, so approving can happen inside the app.","type":"array","maxItems":5,"items":{"type":"object","additionalProperties":false,"required":["package_name","sha256_cert_fingerprints"],"properties":{"package_name":{"description":"Your Android package name.","type":"string","maxLength":150},"sha256_cert_fingerprints":{"description":"Your Android app's signing certificate fingerprints.","type":"array","maxItems":4,"items":{"type":"string","maxLength":95}}}}}}},"agent_rules":{"description":"Your own rules for AI agent orders, stricter than the customer's: `max_order_cents`, `always_approval_required_above_cents`, `hours`.","type":["object","null"],"additionalProperties":false,"properties":{"max_order_cents":{"description":"The most an AI agent may order at once from you.","type":["integer","null"]},"always_approval_required_above_cents":{"description":"Above this amount, the customer always approves the order themselves, whatever their limits.","type":["integer","null"]},"hours":{"description":"When AI agents may order: `tz` (IANA time zone), `days` (0 = Sunday), `start` and `end` (HH:MM).","type":["object","null"],"additionalProperties":false,"required":["days","start","end"],"properties":{"tz":{"description":"An IANA time zone, like America/New_York.","type":"string","maxLength":64},"days":{"description":"A number of days, or the days of the week (0 = Sunday) for hours.","type":"array","minItems":1,"maxItems":7,"items":{"type":"integer","minimum":0,"maximum":6}},"start":{"description":"Start time (HH:MM, 24-hour).","type":"string","maxLength":5},"end":{"description":"End time (HH:MM, 24-hour).","type":"string","maxLength":5}}}}},"embed_origins":{"description":"Your websites that may show the Dashboard inside your own dashboard (up to 5 https origins).","type":"array","maxItems":5,"items":{"type":"string","maxLength":200}},"screen_origins":{"description":"Your websites where Wilby's ready-made screens run (up to 10 https origins).","type":"array","maxItems":10,"items":{"type":"string","maxLength":200}},"first_setup_code":{"description":"Before a customer's first passkey, a one-time code proves it's them (default true).","type":"boolean"},"variable_amount":{"description":"Whether your final price can change after checkout (default false).","type":"boolean"},"ucp":{"description":"Google's agent checkout (UCP): `enabled`, `require_signatures`, `share_saved_addresses`, `prefer_mcp`, `public_base_url`, `version`, `terms_url`, `website_url`, `google_pay`.","type":"object","additionalProperties":false,"properties":{"enabled":{"description":"Whether it is turned on.","type":"boolean"},"require_signatures":{"description":"Google agent checkout: require signed requests.","type":"boolean"},"share_saved_addresses":{"description":"Google agent checkout: share the customer's saved addresses.","type":"boolean"},"prefer_mcp":{"description":"Google agent checkout: prefer the MCP connection.","type":"boolean"},"public_base_url":{"description":"Google agent checkout: your public address.","type":["string","null"],"maxLength":300},"version":{"description":"The version.","type":"string","enum":["2026-04-08","2026-08-25"]},"terms_url":{"description":"Your terms address.","type":["string","null"],"maxLength":500},"website_url":{"description":"Your website address.","type":["string","null"],"maxLength":500},"google_pay":{"description":"Google Pay for agent checkout: `gateway`, `gateway_merchant_id`, `merchant_id`, `merchant_name`, `stripe_version`, `client_key`.","type":["object","null"],"additionalProperties":false,"required":["gateway","gateway_merchant_id"],"properties":{"gateway":{"description":"Your Google Pay gateway (for example stripe).","type":"string","maxLength":40},"gateway_merchant_id":{"description":"Your merchant id at the Google Pay gateway.","type":"string","maxLength":200},"merchant_id":{"description":"Wilby's id for the store (`mer_…`).","type":["string","null"],"maxLength":60},"merchant_name":{"description":"The store name shown in Google Pay.","type":["string","null"],"maxLength":80},"stripe_version":{"description":"The Stripe API version for Google Pay.","type":["string","null"],"maxLength":20},"client_key":{"description":"Your Google Pay client key from your gateway, when it needs one.","type":["string","null"],"maxLength":120}}}}},"listing":{"description":"What AI app directories ask for: `one_liner`, `long_description`, `privacy_url`, `support`, `docs_url`, `example_prompts`, `reviewer_customer_ref`, `reviewer_steps`.","type":"object","additionalProperties":false,"properties":{"one_liner":{"description":"One sentence for AI app directories (up to 200 characters).","type":["string","null"],"maxLength":200},"long_description":{"description":"The long description for AI app directories (up to 2,000 characters).","type":["string","null"],"maxLength":2000},"privacy_url":{"description":"Your privacy policy address.","type":["string","null"],"maxLength":500},"support":{"description":"Your support contact for AI app directories.","type":["string","null"],"maxLength":200},"docs_url":{"description":"Your help page for the connector.","type":["string","null"],"maxLength":500},"example_prompts":{"description":"Example requests customers can try with your connector (up to 5).","type":"array","maxItems":5,"items":{"type":"string","maxLength":200}},"reviewer_customer_ref":{"description":"The customer account AI app directory reviewers sign in with.","type":["string","null"],"maxLength":128},"reviewer_steps":{"description":"Steps for directory reviewers.","type":["string","null"],"maxLength":2000}}},"agent_access":{"description":"Which AI agents may order from you: `mode` all or only, `allowed`, `blocked`, `verified_only`.","type":"object","additionalProperties":false,"properties":{"mode":{"description":"`sandbox` (test) or `live`. In agent access: `all` or `only`.","type":"string","enum":["all","only"]},"verified_only":{"description":"Agent access: only take orders from agents that signed their requests.","type":"boolean"},"allowed":{"description":"Whether it is allowed (true or false), or the list of what is allowed.","type":"array","maxItems":7,"items":{"type":"string","enum":["claude","chatgpt","gemini","copilot","perplexity","meta","other"]}},"blocked":{"description":"The AI agents you refuse orders from.","type":"array","maxItems":7,"items":{"type":"string","enum":["claude","chatgpt","gemini","copilot","perplexity","meta","other"]}}}},"website_agents":{"description":"AI agents on your own website: `likely` (`record_only` or `ask_customer`).","type":"object","additionalProperties":false,"properties":{"likely":{"description":"AI agents on your website: `record_only` (record a likely agent visit) or `ask_customer` (the customer confirms above your amount).","type":"string","enum":["record_only","ask_customer"]}}},"rule_choices_pct":{"description":"The percent choices offered to customers for extra charges (1 to 4).","type":"array","minItems":1,"maxItems":4,"items":{"type":"integer","enum":[5,10,15,20,25,30,40,50]}},"recommended_pct":{"description":"The choice shown as recommended.","type":"integer","enum":[5,10,15,20,25,30,40,50]},"branding":{"description":"Your look on customer pages: `display_name`, `accent_color`, `secondary_color`, `logo_data_uri`, `show_secured_by`.","type":"object","additionalProperties":false,"properties":{"display_name":{"description":"Your business name as customers see it.","type":["string","null"],"maxLength":60},"accent_color":{"description":"Your main brand color on customer pages, like #1E3059.","type":["string","null"],"maxLength":7},"secondary_color":{"description":"Your second brand color.","type":["string","null"],"maxLength":7},"logo_data_uri":{"description":"Your logo as a PNG or JPEG data URI (under 150 KB).","type":["string","null"],"maxLength":200000},"show_secured_by":{"description":"Whether \"Protected by Wilby\" shows on customer pages.","type":"boolean"}}}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/merchants/{id}/agent-rules":{"get":{"tags":["Agent Storefront"],"summary":"One store's own rules for AI agent orders","description":"The store's own rules (`store`) and what applies there (`applies`: the stricter of the business's and the store's, the store's hours if set, and the agents it turns away).","operationId":"get_v1_merchants_id_agent_rules","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"post":{"tags":["Agent Storefront"],"summary":"Set one store's rules for AI agent orders (stricter only)","description":"Any of `max_order_cents`, `always_approval_required_above_cents`, `hours` ({days 0-6, start, end, tz}) and `blocked_agents`. Null clears a rule. A store can only be stricter than the business (the smaller amount wins; its hours replace the business's). Signed with the change.","operationId":"post_v1_merchants_id_agent_rules","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"max_order_cents":{"description":"The most an AI agent may order at once from you.","type":["integer","null"]},"always_approval_required_above_cents":{"description":"Above this amount, the customer always approves the order themselves, whatever their limits.","type":["integer","null"]},"hours":{"description":"When AI agents may order: `tz` (IANA time zone), `days` (0 = Sunday), `start` and `end` (HH:MM).","type":["object","null"],"additionalProperties":false,"required":["days","start","end"],"properties":{"tz":{"description":"An IANA time zone, like America/New_York.","type":"string","maxLength":64},"days":{"description":"A number of days, or the days of the week (0 = Sunday) for hours.","type":"array","minItems":1,"maxItems":7,"items":{"type":"integer","minimum":0,"maximum":6}},"start":{"description":"Start time (HH:MM, 24-hour).","type":"string","maxLength":5},"end":{"description":"End time (HH:MM, 24-hour).","type":"string","maxLength":5}}},"blocked_agents":{"description":"Refused AI agent orders, by agent.","type":"array","maxItems":7,"items":{"type":"string","enum":["claude","chatgpt","gemini","copilot","perplexity","meta","other"]}}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/storefront/readiness":{"get":{"tags":["Agent Storefront"],"summary":"Agent Readiness Check: how ready each store is for AI agents","description":"Asks your Storefront API what an agent would see (stores, services, prices, open times; nothing is ordered or quoted) and checks your settings. Returns a score out of 100 per store and for the business, and each check with what to fix. Optional `store_ref` for one store. Also in Dashboard under Agent Readiness.","operationId":"get_v1_storefront_readiness","parameters":[{"name":"store_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your id for the store."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/storefront/full-test":{"get":{"tags":["Agent Storefront"],"summary":"Full Storefront Test: the whole agent script against one store","description":"Since 0.69.0. Free, on Wilby's server, in seconds. Plays what an AI agent does (find the store, read it, open times, quotes with a tip, a bad promo code, no time, a taken time, an unknown item, a mixed basket, then status and cancel for an unknown order) with `price_check_only: true`, so nothing is ordered or kept. Checks the contract, the things real AI apps misread, and the directory rules for your connector. `store_ref` picks the store (default: your first). `near` (since 0.70.3) is a ZIP or place to search near when your store search asks for a location; without it, the store's own ZIP from `/store` is used. Each step has `status` (pass, warn, fail, skipped), what happened and what to fix.","operationId":"get_v1_storefront_full_test","parameters":[{"name":"store_ref","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your id for the store."},{"name":"near","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":80},"description":"A ZIP code, address or place to search stores near (on /stores and, since 0.70.3, on the full storefront test)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/storefront/listing":{"get":{"tags":["Agent Storefront"],"summary":"Get Listed: materials for each AI app's directory","description":"Puts together what each directory asks for from your settings (name, one-line summary, description, icon, privacy policy, support, help page, example prompts, reviewer steps, tool labels) with a checklist: Done, Check This or Missing. Your privacy policy link is opened to check that it works. Set the materials with `POST /v1/settings {\"listing\": {\"one_liner\", \"long_description\", \"privacy_url\", \"support\", \"docs_url\", \"example_prompts\", \"reviewer_customer_ref\", \"reviewer_steps\"}}`. `reviewer_customer_ref`: a test customer in your system for directory reviewers; Wilby skips the first-setup code for that one customer (they still confirm with their device's lock). Also in Dashboard under Get Listed. Since 0.71.0: Gemini and Grok, your own address (`own_address`), ready-made answers (`money_answer`, `data_handling`, `compliance`, `privacy_section`), and calls from the reviewer account carry `reviewer: true` (its orders are cancelled after 30 minutes).","operationId":"get_v1_storefront_listing","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/storefront/domain":{"get":{"tags":["Agent Storefront"],"summary":"Your own connector address","description":"Since 0.71.0. Your own address for your connector (for example `agents.yourbusiness.com`): `host`, `status` (`none`, `pending`, `verified` or `active`), the two `dns_records` to add (`CNAME` to Wilby, `TXT` to show it's yours), `connector_url`, `last_error` from the last check. `active` means the security certificate is in place and the connector answers there.","operationId":"get_v1_storefront_domain","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"post":{"tags":["Agent Storefront"],"summary":"Choose your own connector address","description":"Since 0.71.0. `{\"host\": \"agents.yourbusiness.com\"}`: an address under your own domain (not the domain itself, so your website stays where it is). Answers with the two DNS records to add. Choosing another address replaces the first. Refusals: `invalid_host`, `host_taken`.","operationId":"post_v1_storefront_domain","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["host"],"additionalProperties":false,"properties":{"host":{"description":"The website address where it happened.","type":"string","minLength":4,"maxLength":253}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"delete":{"tags":["Agent Storefront"],"summary":"Remove your own connector address","description":"Since 0.71.0. Your connector keeps working on Wilby's address.","operationId":"delete_v1_storefront_domain","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/storefront/domain/check":{"post":{"tags":["Agent Storefront"],"summary":"Check your DNS records","description":"Since 0.71.0. Looks up both DNS records now. Both found: `verified`; Wilby then gets the security certificate by itself and the address turns `active`, usually within minutes (check again any time; `certificate` shows where it is). Not found: stays `pending`, with what's missing in `last_error`. DNS changes can take up to an hour to show.","operationId":"post_v1_storefront_domain_check","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/agent-access/report":{"get":{"tags":["Stores"],"summary":"See which AI agents ordered from you and which were turned away","description":"For the last 30 days, per agent (claude, chatgpt, gemini, copilot, perplexity, meta, other): orders, orders with a verified signed identity, how many times your Agent Access Policy turned it away, and whether it is allowed now. Set the gate with `agent_access` on POST /v1/settings.","operationId":"get_v1_agent_access_report","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/customers/{ref}/overage":{"get":{"tags":["Customer Permissions"],"summary":"Get a customer's pre-approved overage","description":"Also says whether they have chosen one yet (`has_rule`) and which choices to show them.","operationId":"get_v1_customers_ref_overage","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id (in the address)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"post":{"tags":["Customer Permissions"],"summary":"Change a customer's pre-approved overage from your app","description":"Same or stricter than now: saved at once (confirmed in your app). Looser: answers 202 with a `url` where the customer confirms it themselves (Face ID or a code).","operationId":"post_v1_customers_ref_overage","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Your own id (in the address)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["preapproved_overage_pct"],"properties":{"preapproved_overage_pct":{"description":"How far above the amount the customer lets you charge without asking (percent).","type":"integer","minimum":0,"maximum":50},"approval_required_above_cents":{"description":"Above this amount, the customer approves each incremental charge themselves.","type":["integer","null"],"minimum":100,"maximum":100000000},"return_url":{"description":"Where Wilby's pages send the customer when they are done (https, or your app's own link).","type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/refunds":{"post":{"tags":["Orders"],"summary":"Refund part or all of a captured order","operationId":"post_v1_orders_id_refunds","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["amount_cents","reason"],"properties":{"amount_cents":{"description":"An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.","type":"integer","minimum":1,"maximum":10000000000},"reason":{"description":"Why, as a code or in words. On an incremental charge: the store's reason the customer sees.","type":"string","minLength":1,"maxLength":300}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/fulfillment":{"post":{"tags":["Orders"],"summary":"Report a shipment (with tracking) or a delivery","description":"`{\"type\": \"shipped\", \"tracking_number\", \"tracking_url\", \"carrier\"}` (tracking number and an https tracking link are required), then `{\"type\": \"delivered\"}`. Optional `line_items` for part of the order, `description` (up to 200 characters). Signed into the order's record. Orders from Google's agent checkout (UCP) pass these to the platform and to Google (Google requires shipped and delivered, with tracking).","operationId":"post_v1_orders_id_fulfillment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"description":"What kind it is.","type":"string","enum":["shipped","delivered"]},"tracking_number":{"description":"The shipment's tracking number.","type":"string","minLength":1,"maxLength":100},"tracking_url":{"description":"The tracking page (https).","type":"string","maxLength":500},"carrier":{"description":"The shipping company.","type":"string","maxLength":60},"description":{"description":"Plain text describing it. On an order: what was ordered.","type":"string","maxLength":200},"line_items":{"description":"The items, each with a name, quantity and amount.","type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["id","quantity"],"properties":{"id":{"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order).","type":"string","minLength":1,"maxLength":64},"quantity":{"description":"How many.","type":"integer","minimum":1,"maximum":1000000}}}}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/evidence":{"post":{"tags":["Incremental Charges and Tips"],"summary":"Add evidence to an order (a photo, a scale reading)","operationId":"post_v1_orders_id_evidence","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["type","sha256"],"properties":{"type":{"description":"What kind it is.","type":"string","enum":["scale_reading","photo","receipt","delivery","customer_message","device_record","other"]},"sha256":{"description":"SHA-256 fingerprint.","type":"string","pattern":"^[0-9a-f]{64}$"},"file_ref":{"description":"Your reference to a file you keep (a photo, a document). Wilby stores its fingerprint, not the file.","type":"string","maxLength":500},"label":{"description":"A short name shown to people.","type":"string","maxLength":120},"meta":{"description":"Extra details about a piece of evidence (your own keys and values).","type":"object"}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/confirmations":{"post":{"tags":["Orders"],"summary":"Ask the customer to confirm statements only they can make","description":"Send 1 to 5 `statements` in your own words (plain text, up to 200 characters each), for example \"I'm 21 or older.\" You get a `url` to send the customer; they tick each statement and confirm with Face ID or a texted code. The order then shows them under `order.customer_statements` (and the `statements.confirmed` webhook). An AI agent can never confirm these.","operationId":"post_v1_orders_id_confirmations","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["statements"],"properties":{"statements":{"description":"Statements only the customer can confirm (for example \"I am 21 or older\").","type":"array","minItems":1,"maxItems":5,"items":{"type":"string","maxLength":400}},"valid_hours":{"description":"How many hours the link works.","type":"integer","minimum":1,"maximum":168},"return_url":{"description":"Where Wilby's pages send the customer when they are done (https, or your app's own link).","type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/receipt-link":{"post":{"tags":["Records"],"summary":"Get the order's verify link","description":"A link anyone can open to check the order's signed record.","operationId":"post_v1_orders_id_receipt_link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"valid_days":{"description":"How many days the link works.","type":"integer","minimum":1,"maximum":130},"return_url":{"description":"Where Wilby's pages send the customer when they are done (https, or your app's own link).","type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/orders/{id}/disputes":{"post":{"tags":["Disputes"],"summary":"Record a chargeback","operationId":"post_v1_orders_id_disputes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^prm_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"description":"Why, as a code or in words. On an incremental charge: the store's reason the customer sees.","type":"string","enum":["overcharged","not_delivered","damaged","other"]},"note":{"description":"A note in plain words.","type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/disputes/{id}":{"get":{"tags":["Disputes"],"summary":"Get a dispute and its evidence","operationId":"get_v1_disputes_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^dsp_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/disputes/{id}/resolve":{"post":{"tags":["Disputes"],"summary":"Record how a dispute ended","operationId":"post_v1_disputes_id_resolve","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^dsp_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["outcome","note"],"properties":{"outcome":{"description":"How it ended.","type":"string","enum":["merchant_won","customer_refunded"]},"refund_cents":{"description":"An amount to refund, in cents. On a dispute: how much was refunded.","type":"integer","minimum":0,"maximum":10000000000},"note":{"description":"A note in plain words.","type":"string","minLength":1,"maxLength":500}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/agent-checks":{"post":{"tags":["AI Agents on Your Website"],"summary":"Who is visiting (website key)","description":"Called by your server or Worker with `Authorization: Bearer wk_…`. Send `stage` (`page` in the background, or `checkout`), `host`, `path`, and what you have: `user_agent`, `ip` (used once, never stored), `signature`, `signature_input`, `signature_agent` and the signed `headers`, `bot_score` (1–99, below 30 means automated) or `automated`, the `forwarded` header (read only when the signature checks out), and at checkout `browser_signals` (the `wilby_signals` field from /agent-signals.js on your checkout page). Answer: `level` (`verified`, `named_itself`, `likely_agent` or `no_sign_of_agent`; never \"human\"), `agent`, `clue`, `signed_for` for signed requests tagged for browsing or paying, `browser_signals` (what the page script found), `buyer_hints` (a verified agent's buyer country, time zone and language), `allowed` (your Agent Access Policy, with `message` when not), your `rules`, and at checkout an `id` (`ach_…`, 30 minutes, once) to pass as `agent_check_id` on POST /v1/orders. Treat a slow or failed answer as no sign of an agent.","operationId":"post_v1_agent_checks","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["stage","host","path"],"properties":{"stage":{"description":"Where the order is: created, confirmed, authorized, captured, cancelled, expired, disputed.","type":"string","enum":["page","checkout"]},"method":{"description":"The HTTP method of the signed request.","type":"string","maxLength":10},"host":{"description":"The website address where it happened.","type":"string","minLength":1,"maxLength":300},"path":{"description":"Which way to integrate, or a path.","type":"string","minLength":1,"maxLength":2000},"query":{"description":"The query string of the signed request.","type":"string","maxLength":2000},"user_agent":{"description":"The customer's browser (User-Agent), so Wilby can pick the right way to approve on that device.","type":"string","maxLength":1000},"ip":{"description":"The visitor's IP address (used only for the check, not kept in the record).","type":"string","maxLength":64},"bot_score":{"description":"Your bot tool's score for the visitor (1–99; below 30 means automated, as Cloudflare scores it).","type":"integer","minimum":1,"maximum":99},"automated":{"description":"Your own bot detection result: true when you think the visitor is automated.","type":"boolean"},"signature":{"description":"The signature.","type":"string","maxLength":4000},"signature_input":{"description":"The Signature-Input header of the signed request.","type":"string","maxLength":4000},"signature_agent":{"description":"The Signature-Agent header (who the agent says it is).","type":"string","maxLength":500},"headers":{"description":"The request headers that were signed.","type":"object","maxProperties":20,"additionalProperties":{"type":"string","maxLength":2000}},"browser_signals":{"description":"Signs of an AI agent working inside the customer's own browser, from /agent-signals.js on the checkout page. In a request: the `wilby_signals` summary (counts and yes/no markers only). In an answer: `sent` and `found` (each with `id`, `label` and `strength`: strong or weak). Never makes a check \"verified\".","type":"string","maxLength":2000},"forwarded":{"description":"The visitor's Forwarded header, as received. Only country, time zone and language are read from it, and only when the request's signature checks out.","type":"string","maxLength":2000}}}}}},"security":[{"websiteKey":[]}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/public/audit-trail/{id}":{"get":{"tags":["Public"],"summary":"An order's signed record (with its verify code `k`)","operationId":"get_v1_public_audit_trail_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/public/agent-proof/{id}":{"get":{"tags":["Public"],"summary":"Proof for one AI agent (with its code `k`)","description":"What the customer allowed (signed with Face ID or a code), when it was turned off, every order it made, and whether anything happened after. The same proof the customer gets from \"Get Proof\"; the human-readable page is /agent-proof/{id}?k=…","operationId":"get_v1_public_agent_proof_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/public/evidence-package/{id}":{"get":{"tags":["Public"],"summary":"Claim packet for an order the customer reported (with its code `k`)","description":"For an order the customer said their AI agent got wrong: what the customer allowed, what the agent did, the report, and what the business did about it, each with its signed record. The finding is always authorized_but_wrong. The page at /claim-packet/{id}?k= prints to one page. The link is in `order.reported_wrong.claim_packet_url`.","operationId":"get_v1_public_evidence_package_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/public/quotes/{id}":{"get":{"tags":["Public"],"summary":"A signed quote (with its code `k`)","description":"The price an AI agent was quoted, signed by Wilby: the document, whether the signature checks out, and what became of it (open, expired, or the order with its final price and whether it stayed within the quote). The page is at /quote/{id}?k=. The link comes back from quote_order as `signed_quote.verify_url` and on the order as `order.signed_quote.url`.","operationId":"get_v1_public_quotes_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/public/checkpoints":{"get":{"tags":["Public"],"summary":"Daily public checkpoints","operationId":"get_v1_public_checkpoints","security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/public/checkpoints/{id}":{"get":{"tags":["Public"],"summary":"One checkpoint, its signed text and signature","operationId":"get_v1_public_checkpoints_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/public/checkpoints/{id}/body":{"get":{"tags":["Public"],"summary":"The exact signed text of a checkpoint","operationId":"get_v1_public_checkpoints_id_body","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/public/checkpoints/{id}/ots":{"get":{"tags":["Public"],"summary":"The Bitcoin timestamp proof (.ots) of a checkpoint","operationId":"get_v1_public_checkpoints_id_ots","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/session":{"get":{"tags":["Ready-Made Screens"],"summary":"The business's look and words, and the customer's rule (screen pass)","operationId":"get_v1_client_session","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/orders":{"get":{"tags":["Ready-Made Screens"],"summary":"This customer's orders (screen pass)","operationId":"get_v1_client_orders","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20},"description":"How many to return (paging)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/orders/{id}":{"get":{"tags":["Ready-Made Screens"],"summary":"One order's screen-ready block (screen pass)","operationId":"get_v1_client_orders_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","maxLength":40},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/overage":{"post":{"tags":["Ready-Made Screens"],"summary":"Save the customer's rule (screen pass)","description":"The same or stricter: saved at once, recorded as confirmed on the business's website. Looser: `status: needs_customer` with `window_url`, the Wilby window where the customer confirms it's them.","operationId":"post_v1_client_overage","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["preapproved_overage_pct"],"properties":{"preapproved_overage_pct":{"description":"How far above the amount the customer lets you charge without asking (percent).","type":"integer","minimum":0,"maximum":100},"approval_required_above_cents":{"description":"Above this amount, the customer approves each incremental charge themselves.","type":["integer","null"],"minimum":0},"app_return":{"description":"Your app's own link to return to after a Wilby screen (for example `yourapp://done`).","type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/incremental-charges/{id}/decline":{"post":{"tags":["Ready-Made Screens"],"summary":"Decline an incremental charge (screen pass)","description":"Charges nothing; recorded as declined on the business's website.","operationId":"post_v1_client_incremental_charges_id_decline","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/incremental-charges/{id}/window":{"post":{"tags":["Ready-Made Screens"],"summary":"Open the Wilby window to approve an incremental charge (screen pass)","description":"A fresh approval page (earlier links for this incremental charge then say \"Newer Link Sent\"). Opened with `?w=<your origin>`, it tells your page when the customer is done (`postMessage {wilby: \"window_done\", state}`) and closes.","operationId":"post_v1_client_incremental_charges_id_window","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":["object","null"],"additionalProperties":false,"properties":{"app_return":{"description":"Your app's own link to return to after a Wilby screen (for example `yourapp://done`).","type":"string","maxLength":300}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/incremental-charges/{id}/passkey/begin":{"post":{"tags":["Ready-Made Screens"],"summary":"In your app: start the phone's own Face ID approval (screen pass)","description":"For apps registered with `apps` in POST /v1/settings (`session.in_app_passkey` is true), or from your own website when it is in `screen_origins` and on Wilby's /.well-known/webauthn list (`session.in_page_passkey` is true; the web script does this for you). Same as POST /v1/incremental-charges/{id}/passkey/begin, with the screen pass instead of your API key.","operationId":"post_v1_client_incremental_charges_id_passkey_begin","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/incremental-charges/{id}/passkey/finish":{"post":{"tags":["Ready-Made Screens"],"summary":"In your app: finish the Face ID approval (screen pass)","operationId":"post_v1_client_incremental_charges_id_passkey_finish","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["ceremony_id","response"],"properties":{"ceremony_id":{"description":"The id of a Face ID / Touch ID / fingerprint prompt. Send it back when finishing.","type":"string","maxLength":40},"response":{"description":"The browser's WebAuthn answer, passed through unchanged."}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/incremental-charges/{id}/passkey/new_phone/send":{"post":{"tags":["Ready-Made Screens"],"summary":"In your app: new phone, send a code (screen pass)","operationId":"post_v1_client_incremental_charges_id_passkey_new_phone_send","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/incremental-charges/{id}/passkey/new_phone/verify":{"post":{"tags":["Ready-Made Screens"],"summary":"In your app: new phone, check the code (screen pass)","operationId":"post_v1_client_incremental_charges_id_passkey_new_phone_verify","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^top_[0-9a-z]{20}$"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["code_id","code"],"properties":{"code_id":{"description":"The id of a sent code. Send it back with the code the customer types.","type":"string","maxLength":40},"code":{"description":"A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.","type":"string","maxLength":12}}}}}},"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/agents":{"get":{"tags":["Ready-Made Screens"],"summary":"The customer's AI agents (screen pass)","operationId":"get_v1_client_agents","responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/v1/client/agents/{id}/off":{"post":{"tags":["Ready-Made Screens"],"summary":"Turn an agent off (screen pass)","description":"Takes effect at once. Turning one back on needs the customer's own confirmation, on Wilby's Your AI Agents page.","operationId":"post_v1_client_agents_id_off","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","maxLength":40},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Any unique string per action (e.g. your order id + step). A repeat returns the first answer; the same key with a different body is refused."}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/agent/v1/connect":{"post":{"tags":["Agent API"],"summary":"Connect with the customer's code","description":"Exchanges the 8-character code the customer gives the agent for an agent key.","operationId":"post_agent_v1_connect","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"description":"A code: a 6-digit approval code, a connection (pairing) code, or an error code, depending on the call.","type":"string","maxLength":20}}}}}},"security":[],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/agent/v1/me":{"get":{"tags":["Agent API"],"summary":"What this agent may do (limits left)","operationId":"get_agent_v1_me","security":[{"assistantKey":[]}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/agent/v1/stores":{"get":{"tags":["Agent API"],"summary":"Stores this agent may order from","operationId":"get_agent_v1_stores","security":[{"assistantKey":[]}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/agent/v1/orders":{"get":{"tags":["Agent API"],"summary":"List this agent's orders","operationId":"get_agent_v1_orders","security":[{"assistantKey":[]}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}},"post":{"tags":["Agent API"],"summary":"Place an order inside the customer's permission","description":"Above a limit the answer is `needs_customer` with the reason: the customer decides, not the agent.","operationId":"post_agent_v1_orders","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["store_id","description","amount_cents"],"additionalProperties":false,"properties":{"store_id":{"description":"The store's id.","type":"string","maxLength":40},"description":{"description":"Plain text describing it. On an order: what was ordered.","type":"string","maxLength":300},"amount_cents":{"description":"An amount in cents (US dollars). On an order: the price, or the estimate when the price can change. On a payment or refund: that payment's amount.","type":"integer","minimum":100}}}}}},"security":[{"assistantKey":[]}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/agent/v1/orders/{id}":{"get":{"tags":["Agent API"],"summary":"Get an order","operationId":"get_agent_v1_orders_id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[{"assistantKey":[]}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/agent/v1/orders/{id}/approve-extra":{"post":{"tags":["Agent API"],"summary":"Approve an incremental charge inside the customer's permission","operationId":"post_agent_v1_orders_id_approve_extra","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["request_id"],"properties":{"request_id":{"description":"The sign-in request's id (`oar_…` or `csi_…`).","type":"string","maxLength":40}}}}}},"security":[{"assistantKey":[]}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/agent/v1/orders/{id}/proof":{"get":{"tags":["Agent API"],"summary":"Proof the order stayed inside the permission","operationId":"get_agent_v1_orders_id_proof","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[{"assistantKey":[]}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}},"/agent/v1/orders/{id}/cancel":{"post":{"tags":["Agent API"],"summary":"Cancel an order","operationId":"post_agent_v1_orders_id_cancel","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Wilby's id for it (a prefix plus 20 characters, like `prm_…` for an order)."}],"security":[{"assistantKey":[]}],"responses":{"200":{"description":"OK. Every field in the answer is explained in Objects (/docs/objects)."},"4XX":{"description":"Error: `{ error, message, details? }`. `error` is a stable code; every code is listed in Error Codes (/docs/errors)."}}}}}}