{"openapi":"3.1.0","info":{"title":"OTTR Agent Commerce API","version":"1.0.0","description":"Product discovery and customer-approved purchasing for AI agents. Agents prepare purchases; only the customer can approve them, on OTTR; OTTR pays the merchant with a single-use virtual card the agent never sees. Sandbox: purchases complete at a test merchant and nothing real is charged."},"servers":[{"url":"https://ottr.si/v1/agent"}],"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"Your agent key, ottr_ak_..."},"customerRef":{"type":"apiKey","in":"header","name":"OTTR-Customer-Ref","description":"The reference the customer issued to your agent from their OTTR Security page, ottr_cr_..."}},"schemas":{"Error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"Money":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string","example":"GBP"}},"required":["amount","currency"]},"Offer":{"type":"object","properties":{"offer_id":{"type":"string"},"title":{"type":"string"},"brand":{"type":["string","null"]},"merchant":{"type":"string"},"merchant_environment":{"type":"string","enum":["sandbox","live"]},"price":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string","example":"GBP"}},"required":["amount","currency"]},"delivery":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"estimate":{"type":["string","null"]}}},"total":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string","example":"GBP"}},"required":["amount","currency"]},"in_stock":{"type":"boolean"},"purchasable":{"type":"boolean","description":"Whether OTTR can buy this offer itself"},"url":{"type":["string","null"]}}},"PurchaseIntent":{"type":"object","properties":{"id":{"type":"string"},"product":{"type":"string"},"merchant":{"type":"string"},"total":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string","example":"GBP"}},"required":["amount","currency"]},"state":{"type":"string","enum":["OFFER_SELECTED","AWAITING_APPROVAL","APPROVED","FUNDING_PENDING","FUNDED","CARD_ISSUED","CHECKOUT_IN_PROGRESS","OUTCOME_UNKNOWN","PAYMENT_AUTHORISED","ORDER_CONFIRMED","COMPLETED","FAILED","CANCELLED","REFUND_PENDING","REFUNDED"]},"state_label":{"type":"string"},"failure_reason":{"type":["string","null"]},"order_id":{"type":["string","null"]},"merchant_order_ref":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"merchant_order_ref":{"type":"string"},"status":{"type":"string"},"total":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string","example":"GBP"}},"required":["amount","currency"]},"items":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"quantity":{"type":"integer"}}}},"shipment":{"type":["object","null"]},"refunds":{"type":"array","items":{"type":"object"}}}}}},"paths":{"/search":{"post":{"summary":"Search products","security":[{"agentKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"max_price":{"type":"number","description":"Pounds, including delivery"},"limit":{"type":"integer","maximum":10}},"required":["query"]}}}},"responses":{"200":{"description":"Offers","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/purchase-intents":{"post":{"summary":"Prepare a purchase (charges nothing)","security":[{"agentKey":[],"customerRef":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_id":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":5}},"required":["offer_id"]}}}},"responses":{"200":{"description":"Prepared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseIntent"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/purchase-intents/{id}":{"get":{"summary":"Purchase state","security":[{"agentKey":[],"customerRef":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseIntent"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/purchase-intents/{id}/approval-requests":{"post":{"summary":"Ask the customer to approve","description":"Sends the customer a secure, single-use approval link on their own channel. Only the customer can approve, signed in to OTTR.","security":[{"agentKey":[],"customerRef":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Requested","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["awaiting_customer_approval","needs_customer_setup"]},"approval_url":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"delivered_to_customer":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string"}}}}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/purchases":{"post":{"summary":"Proceed with an approved purchase","description":"Refused with 409 approval_required until the customer has approved.","security":[{"agentKey":[],"customerRef":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"intent_id":{"type":"string"}},"required":["intent_id"]}}}},"responses":{"200":{"description":"Purchase","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseIntent"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"get":{"summary":"Order status","security":[{"agentKey":[],"customerRef":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Order id or merchant order reference","schema":{"type":"string"}}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/returns":{"post":{"summary":"Start a return","security":[{"agentKey":[],"customerRef":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Return started"},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}