{"openapi":"3.1.0","info":{"title":"ProxyAI API and product checkout payments","version":"1.0.0","description":"Product checkout payment API. Authenticate using /auth.md. Errors are JSON with machine-readable error codes. RateLimit-Policy advertises enforced quotas; RateLimit reports remaining requests and reset seconds. Respect Retry-After on 429. Anonymous /api/v1 quotes allow 60 requests/minute per IP; authenticated checkout operations share 120 requests/minute per commerce grant. RateLimit fields follow draft-ietf-httpapi-ratelimit-headers-11."},"x-service-info":{"categories":["commerce"],"docs":{"homepage":"https://www.proxyai.app/docs"}},"servers":[{"url":"https://www.proxyai.app"}],"security":[{"commerce":[]}],"components":{"schemas":{"PublicProduct":{"type":"object","additionalProperties":false,"required":["id","name","description","price","creditValue"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"price":{"type":"string","description":"Decimal USD price, without binary rounding."},"creditValue":{"type":["string","null"],"description":"Included credit value in USD, if any."}}},"ProductCatalogPage":{"type":"object","additionalProperties":false,"required":["currency","items","has_more","next_cursor"],"properties":{"currency":{"type":"string","const":"USD"},"items":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/PublicProduct"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"Pass as cursor on the next request; null marks the last page."}}},"CatalogProblem":{"type":"object","required":["type","title","status","code","message","hint"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"}},"description":"Application errors retain the error code consumed by existing clients; code, message and hint explain recovery. Payment SDK errors can contain only error."},"PaymentProblem":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer","const":402},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":true,"description":"RFC 9457 payment problem supplied by the MPP SDK. A challenge may have no body; use WWW-Authenticate and PAYMENT-REQUIRED."},"PendingPayment":{"type":"object","required":["checkout_id","order_id","status","message"],"properties":{"checkout_id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"},"status":{"type":"string","const":"complete_in_progress"},"message":{"type":"string"}},"description":"Poll GET /checkout_sessions/{checkout_id} with the same commerce token and API-Version. Never submit another payment while settlement is pending."},"Checkout":{"type":"object","required":["id","protocol","status","currency","line_items","totals","created_at","updated_at","expires_at"],"properties":{"id":{"type":"string","format":"uuid"},"protocol":{"type":"object","required":["version"],"properties":{"version":{"type":"string"}}},"status":{"type":"string","enum":["ready_for_payment","not_ready_for_payment","complete_in_progress","requires_escalation","authentication_required","completed","canceled","expired"]},"currency":{"type":"string","const":"usd"},"line_items":{"type":"array","items":{"type":"object","required":["id","item","quantity","totals"],"properties":{"id":{"type":"string"},"item":{"type":"object","required":["id","name","unit_amount"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"unit_amount":{"type":"integer","minimum":0,"description":"USD cents"}}},"quantity":{"type":"integer","const":1},"totals":{"type":"array","items":{"type":"object","required":["type","display_text","amount"],"properties":{"type":{"type":"string"},"display_text":{"type":"string"},"amount":{"type":"integer","minimum":0,"description":"USD cents"}}}}}}},"totals":{"type":"array","items":{"type":"object","required":["type","display_text","amount"],"properties":{"type":{"type":"string"},"display_text":{"type":"string"},"amount":{"type":"integer","minimum":0,"description":"USD cents"}}}},"fulfillment_options":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"title":{"type":"string"},"totals":{"type":"array","items":{"type":"object","required":["type","display_text","amount"],"properties":{"type":{"type":"string"},"display_text":{"type":"string"},"amount":{"type":"integer","minimum":0,"description":"USD cents"}}}}}}},"messages":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"content_type":{"type":"string"},"content":{"type":"string"}}}},"links":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"url":{"type":"string","format":"uri"}}}},"capabilities":{"type":"object","description":"ACP payment handlers and supported interventions","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"continue_url":{"type":"string","format":"uri"},"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"checkout_session_id":{"type":"string","format":"uuid"},"permalink_url":{"type":"string","format":"uri"},"status":{"type":"string"}}},"metadata":{"type":"object","description":"Checkout payment state, order ID and optional target bot ID","additionalProperties":true}}},"AcpError":{"type":"object","required":["type","code","message"],"properties":{"type":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}},"CreateCheckout":{"type":"object","additionalProperties":false,"properties":{"line_items":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","minLength":1,"maxLength":120},"name":{"type":"string","maxLength":300},"unit_amount":{"type":"integer","minimum":0}},"required":["id"]}},"currency":{"type":"string","const":"usd"},"buyer":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"full_name":{"type":"string","maxLength":200}},"required":["email"]},"capabilities":{"type":"object","additionalProperties":false,"properties":{"payment":{"type":"object","additionalProperties":false,"properties":{"handlers":{"type":"array","maxItems":20,"items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","maxLength":100},"name":{"type":"string","maxLength":100}},"additionalProperties":true}}},"required":["handlers"]},"interventions":{},"extensions":{"type":"array","maxItems":20,"items":{"type":"string","maxLength":100}}},"required":[]},"metadata":{"type":"object","additionalProperties":false,"properties":{"attach_to_client_products_id":{"type":"string","format":"uuid"}},"required":[]},"locale":{"type":"string","maxLength":30},"timezone":{"type":"string","maxLength":100}},"required":["line_items","currency","capabilities"]},"UpdateCheckout":{"type":"object","additionalProperties":false,"properties":{"line_items":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","minLength":1,"maxLength":120},"name":{"type":"string","maxLength":300},"unit_amount":{"type":"integer","minimum":0}},"required":["id"]}},"buyer":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"full_name":{"type":"string","maxLength":200}},"required":["email"]}},"required":[]},"CompleteCheckout":{"type":"object","additionalProperties":false,"properties":{"payment_data":{"type":"object","additionalProperties":false,"properties":{"handler_id":{"type":"string"},"instrument":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string"},"credential":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string"},"token":{"type":"string","minLength":1,"maxLength":2048}},"required":["type","token"]}},"required":["type","credential"]}},"required":["handler_id","instrument"]},"buyer":{"type":"object","additionalProperties":false,"properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string","maxLength":100},"last_name":{"type":"string","maxLength":100},"full_name":{"type":"string","maxLength":200}},"required":["email"]},"ap2_mandate":{"type":"string","minLength":1,"maxLength":14000}},"required":["payment_data"]},"CancelCheckout":{"type":"object","additionalProperties":false,"properties":{},"required":[]}},"securitySchemes":{"commerce":{"type":"http","scheme":"bearer","description":"Resource-specific commerce token obtained through /auth.md. Drafts and reads use commerce:read; completion and payment require commerce:purchase."}}},"paths":{"/api/v1/products":{"get":{"operationId":"listPublicProducts","summary":"List public ProxyAI products and prices","security":[],"description":"Read-only public catalogue, ordered by product ID. Pass next_cursor as cursor until next_cursor is null. Link rel=next provides the next request URL. Prices are USD decimal strings. No account data or purchases. Limit: 60 requests/minute per IP; respect RateLimit and Retry-After.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","minLength":1,"maxLength":120},"description":"Use next_cursor from the previous page. Omit for the first page."}],"responses":{"200":{"description":"One page of active, publicly visible products","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"Link":{"schema":{"type":"string"},"description":"rel=next when another page exists"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCatalogPage"}}}},"400":{"description":"Invalid query","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/CatalogProblem"}}}},"429":{"description":"Rate limited","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/CatalogProblem"}}}},"503":{"description":"Catalogue unavailable","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/CatalogProblem"}}}}}}},"/checkout_sessions":{"post":{"operationId":"createCheckout","summary":"Create an idempotent product checkout","parameters":[{"name":"API-Version","in":"header","required":true,"schema":{"type":"string","const":"2026-01-30"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Unique per logical mutation and commerce grant. Retry the same operation, checkout and JSON body with the same key. Reusing it for changed input returns 409 request_not_idempotent. Replay returns the checkout's current state."}],"description":"Requires a resource-specific commerce token and API-Version. Completion additionally requires commerce:purchase. Never create a new key to retry an uncertain payment; poll the checkout. Prices are quoted by the server.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheckout"}}}},"responses":{"201":{"description":"Current checkout state","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"401":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"402":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"403":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"404":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"409":{"description":"Idempotency conflict or checkout state conflict; inspect code","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"413":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"422":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"429":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"500":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"502":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"503":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}}}}},"/checkout_sessions/{id}":{"get":{"operationId":"getCheckout","summary":"Read a checkout","parameters":[{"name":"API-Version","in":"header","required":true,"schema":{"type":"string","const":"2026-01-30"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"description":"Requires a resource-specific commerce token and API-Version. Completion additionally requires commerce:purchase. Never create a new key to retry an uncertain payment; poll the checkout. Prices are quoted by the server.","responses":{"200":{"description":"Current checkout state","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"401":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"402":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"403":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"404":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"409":{"description":"Idempotency conflict or checkout state conflict; inspect code","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"413":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"422":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"429":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"500":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"502":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"503":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}}}},"post":{"operationId":"updateCheckout","summary":"Update a checkout","parameters":[{"name":"API-Version","in":"header","required":true,"schema":{"type":"string","const":"2026-01-30"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Unique per logical mutation and commerce grant. Retry the same operation, checkout and JSON body with the same key. Reusing it for changed input returns 409 request_not_idempotent. Replay returns the checkout's current state."}],"description":"Requires a resource-specific commerce token and API-Version. Completion additionally requires commerce:purchase. Never create a new key to retry an uncertain payment; poll the checkout. Prices are quoted by the server.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCheckout"}}}},"responses":{"200":{"description":"Current checkout state","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"401":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"402":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"403":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"404":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"409":{"description":"Idempotency conflict or checkout state conflict; inspect code","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"413":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"422":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"429":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"500":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"502":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"503":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}}}}},"/checkout_sessions/{id}/complete":{"post":{"operationId":"completeCheckout","summary":"Complete a checkout using an approved payment handler","parameters":[{"name":"API-Version","in":"header","required":true,"schema":{"type":"string","const":"2026-01-30"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Unique per logical mutation and commerce grant. Retry the same operation, checkout and JSON body with the same key. Reusing it for changed input returns 409 request_not_idempotent. Replay returns the checkout's current state."}],"description":"Requires a resource-specific commerce token and API-Version. Completion additionally requires commerce:purchase. Never create a new key to retry an uncertain payment; poll the checkout. Prices are quoted by the server.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteCheckout"}}}},"responses":{"200":{"description":"Current checkout state","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"401":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"402":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"403":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"404":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"409":{"description":"Idempotency conflict or checkout state conflict; inspect code","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"413":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"422":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"429":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"500":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"502":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"503":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}}}}},"/checkout_sessions/{id}/cancel":{"post":{"operationId":"cancelCheckout","summary":"Cancel an unpaid checkout","parameters":[{"name":"API-Version","in":"header","required":true,"schema":{"type":"string","const":"2026-01-30"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Unique per logical mutation and commerce grant. Retry the same operation, checkout and JSON body with the same key. Reusing it for changed input returns 409 request_not_idempotent. Replay returns the checkout's current state."}],"description":"Requires a resource-specific commerce token and API-Version. Completion additionally requires commerce:purchase. Never create a new key to retry an uncertain payment; poll the checkout. Prices are quoted by the server.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelCheckout"}}}},"responses":{"200":{"description":"Current checkout state","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"400":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"401":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"402":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"403":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"404":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"409":{"description":"Idempotency conflict or checkout state conflict; inspect code","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"413":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"422":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"429":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"500":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"502":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}},"503":{"description":"ACP request failed; inspect code and message","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcpError"}}}}}}},"/api/v1":{"get":{"operationId":"purchaseProductBundle","summary":"Buy a new Basic Chatbot with a paid add-on","description":"One-time product purchase, not per-call API billing. The default offer is Basic Chatbot plus Human Handoff. Authenticate with a commerce:purchase Bearer token before submitting payment. A payment retry creates an idempotent checkout owned by that account and fulfills the purchased products after settlement.","x-payment-info":{"method":"evm","intent":"charge","amount":"10000000","currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","recipient":"0xc0B863436dD8C3D53DBd5c040a8693fB99377C3B","network":"eip155:8453","description":"One-time ProxyAI product purchase: Basic Chatbot + Human Handoff"},"parameters":[{"name":"product_id","in":"query","required":false,"schema":{"type":"string","default":"human-handoff"},"description":"Paid add-on to purchase with a new free Basic Chatbot. A different product has its own live quote."}],"responses":{"200":{"description":"Paid checkout; products activated","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"202":{"description":"Settlement pending; poll the checkout and do not submit another payment","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingPayment"}}}},"400":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Commerce authentication required; see /auth.md","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"MPP/x402 payment challenge. The SDK can return an empty body; the challenge headers are authoritative.","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"WWW-Authenticate":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PaymentProblem"}},"application/json":{"schema":{"type":"object","description":"x402 SDK payment challenge","additionalProperties":true}}}},"403":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Quota exceeded; wait Retry-After seconds","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"431":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/checkout_sessions/{id}/pay":{"post":{"operationId":"payCheckout","summary":"Pay an existing product or add-on order with MPP or x402","x-payment-info":{"amount":null,"currency":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","description":"Amount is the immutable order total; obtain an authenticated checkout challenge.","intent":"charge","method":"evm","recipient":"0xc0B863436dD8C3D53DBd5c040a8693fB99377C3B","network":"eip155:8453"},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"API-Version","in":"header","required":true,"schema":{"type":"string","const":"2026-01-30"}}],"description":"Keep the Bearer token in Authorization. MPP uses Payment-Authorization; x402 v2 uses Payment-Signature. x402 clients must support the advertised mppx route-binding extension. A pending settlement must never be re-submitted as a new payment.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"ap2_mandate":{"type":"string","maxLength":14000}}}}}},"responses":{"200":{"description":"Paid checkout; products activated","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Checkout"}}}},"202":{"description":"Settlement pending; poll the checkout and do not submit another payment","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingPayment"}}}},"400":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Commerce authentication required; see /auth.md","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"MPP/x402 payment challenge. The SDK can return an empty body; the challenge headers are authoritative.","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"WWW-Authenticate":{"schema":{"type":"string"}},"PAYMENT-REQUIRED":{"schema":{"type":"string"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/PaymentProblem"}},"application/json":{"schema":{"type":"object","description":"x402 SDK payment challenge","additionalProperties":true}}}},"403":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Quota exceeded; wait Retry-After seconds","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"},"Retry-After":{"schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"431":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Request failed; use error, message and hint to recover","headers":{"RateLimit-Policy":{"description":"IETF RateLimit policy: quoted policy name with q (quota) and w (window seconds).","schema":{"type":"string"},"example":"\"default\";q=60;w=60"},"RateLimit":{"description":"Current enforced quota: r is remaining requests, t is seconds until reset. Present after a quota is consumed.","schema":{"type":"string"},"example":"\"default\";r=59;t=60"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}