{"openapi":"3.1.0","info":{"title":"Paperstall API","version":"1.0.0","description":"Paper → intent → PayPal rail. Sandbox only. Every response carries `receipts`: the outbound PayPal/Gemini/Channel3 calls it made, with PayPal debug IDs.","license":{"name":"MIT","identifier":"MIT"}},"servers":[{"url":"https://paperstall.vercel.app"}],"paths":{"/api/v1/ai/read":{"post":{"tags":["AI"],"summary":"Read a photo of paper","description":"Image → structured Read (intent, items with 0–1000 boxes, currency, questions, warnings) plus an acceptable-use check. Rate-limited per IP.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"image":{"type":"string","description":"Base64 JPEG/PNG/WebP, ≤4 MB"},"hint":{"type":"string","maxLength":200}},"required":["image"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"read":{"type":"object","properties":{"intent":{"type":"string","enum":["shop","invoice","subscription","unknown"]},"intentReason":{"type":"string","maxLength":240},"business":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"kind":{"type":"string","maxLength":80}},"additionalProperties":false},"sourceLanguage":{"type":"string","maxLength":20,"description":"BCP-47, e.g. en, es, fr"},"currency":{"type":"object","properties":{"detected":{"description":"ISO 4217 code","type":"string","maxLength":3},"symbolSeen":{"type":"string","maxLength":8},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["confidence"],"additionalProperties":false},"items":{"maxItems":60,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":40},"nameOriginal":{"type":"string","maxLength":200,"description":"Exactly as written, any language or script"},"nameEn":{"type":"string","maxLength":200,"description":"English name for international buyers"},"description":{"description":"Short and honest; no invented claims","type":"string","maxLength":300},"unitPrice":{"type":"number","description":"Price per unit in the detected currency, as written"},"quantity":{"description":"Invoices only","type":"number"},"unit":{"description":"e.g. \"per plate\", \"per kg\"","type":"string","maxLength":40},"interval":{"description":"Subscriptions only","type":"string","enum":["week","month","year"]},"box":{"minItems":4,"maxItems":4,"type":"array","items":{"type":"number","minimum":0,"maximum":1000},"description":"[ymin, xmin, ymax, xmax] normalized 0-1000"},"confidence":{"type":"number","minimum":0,"maximum":1},"retail":{"type":"object","properties":{"isBrandedProduct":{"type":"boolean","description":"True only for branded, mass-produced goods; never food, handmade or services"},"searchQuery":{"description":"Brand + model, e.g. \"JBL Go 3\"","type":"string","maxLength":120}},"required":["isBrandedProduct"],"additionalProperties":false}},"required":["id","nameOriginal","nameEn","unitPrice","box","confidence"],"additionalProperties":false}},"customer":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"email":{"type":"string","maxLength":200},"company":{"type":"string","maxLength":120},"country":{"type":"string","maxLength":60}},"additionalProperties":false},"dates":{"type":"object","properties":{"issued":{"type":"string","maxLength":40},"due":{"type":"string","maxLength":40}},"additionalProperties":false},"writtenTotal":{"type":"number"},"taxRate":{"description":"Tax rate if the paper states one, e.g. \"prices + 8% tax\" → 8","type":"number","minimum":0,"maximum":50},"tax":{"description":"Tax amount written on the paper (tax, VAT, GST, sales tax), if any. Never an item","type":"number"},"writtenTotalBox":{"description":"Where the written total is on the page, if any","minItems":4,"maxItems":4,"type":"array","items":{"type":"number","minimum":0,"maximum":1000}},"taxOrNotes":{"type":"string","maxLength":300},"questions":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":40},"ask":{"type":"string","maxLength":160},"options":{"maxItems":4,"type":"array","items":{"type":"string","maxLength":40}}},"required":["id","ask"],"additionalProperties":false}},"warnings":{"maxItems":10,"type":"array","items":{"type":"string","maxLength":200}}},"required":["intent","intentReason","business","sourceLanguage","currency","items","questions","warnings"],"additionalProperties":false},"aup":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"reason":{"type":"string"}},"required":["id","reason"],"additionalProperties":false}},{"type":"null"}]},"aupChecked":{"type":"boolean"}},"required":["read","aup","aupChecked"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/market":{"post":{"tags":["AI"],"summary":"Market check for branded items (Channel3)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"items":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"query":{"type":"string"}},"required":["id","query"],"additionalProperties":false}}},"required":["currency","items"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"enabled":{"type":"boolean"},"matches":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["enabled","matches"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/stalls/sign":{"post":{"tags":["Stalls"],"summary":"Sign a stall so it can take payments","description":"The server assigns the stall ID and returns an owner token once; refunds and shipping need it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"payload":{"type":"object","properties":{"n":{"type":"string","minLength":1,"maxLength":60},"k":{"type":"string","maxLength":40},"c":{"type":"string"},"p":{"type":"string","maxLength":127,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"i":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":24},"name":{"type":"string","minLength":1,"maxLength":80},"orig":{"type":"string","maxLength":80},"price":{"type":"integer","exclusiveMinimum":0,"maximum":100000000},"unit":{"type":"string","maxLength":30},"desc":{"type":"string","maxLength":140},"mkt":{"type":"array","prefixItems":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}],"items":false,"minItems":2,"maxItems":2},"img":{"type":"string","maxLength":400,"format":"uri"}},"required":["id","name","price"],"additionalProperties":false}},"t":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"l":{"type":"string","maxLength":12},"r":{"type":"integer","minimum":0,"maximum":5000}},"required":["n","c","p","i"],"additionalProperties":false}},"required":["payload"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"signed":{"type":"string","description":"Signed stall link payload: `<lz-string>.<HMAC>` (the part after `/s#`)"},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"owner":{"type":"string"},"doorbell":{"type":"string"}},"required":["signed","id","owner"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/stalls/check":{"post":{"tags":["Stalls"],"summary":"Check a stall link's signature and expiry","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"signed":{"type":"string","description":"Signed stall link payload: `<lz-string>.<HMAC>` (the part after `/s#`)"}},"required":["signed"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"ok":{"type":"boolean"},"reason":{"type":"string"}},"required":["ok"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/orders":{"post":{"tags":["Checkout"],"summary":"Create a PayPal order from a signed stall and a cart","description":"Prices are recomputed on the server from the signed stall; client totals are ignored. The stall's payee receives the money.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"signed":{"type":"string","description":"Signed stall link payload: `<lz-string>.<HMAC>` (the part after `/s#`)"},"cart":{"minItems":1,"maxItems":40,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":24},"qty":{"type":"integer","minimum":1,"maximum":99}},"required":["id","qty"],"additionalProperties":false}},"notes":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string","maxLength":100}}},"required":["signed","cart"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string"}},"required":["orderId"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/orders/capture":{"post":{"tags":["Checkout"],"summary":"Capture an approved order and get the signed receipt code","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"signed":{"type":"string","description":"Signed stall link payload: `<lz-string>.<HMAC>` (the part after `/s#`)"},"orderId":{"type":"string"}},"required":["signed","orderId"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string"},"captureId":{"type":"string"},"totalMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"currency":{"type":"string"},"receiptCode":{"type":"string"}},"required":["orderId","captureId","totalMinor","currency","receiptCode"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/verify":{"post":{"tags":["Verify"],"summary":"Verify a payment with PayPal before recording it","description":"Checks order + capture status, payee, amount, currency, stall and replay. Send a scanned receipt `code` or a typed `orderId`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"orderId":{"type":"string"},"signed":{"type":"string","description":"Signed stall link payload: `<lz-string>.<HMAC>` (the part after `/s#`)"},"recorded":{"type":"object","properties":{"orderIds":{"type":"array","items":{"type":"string"}},"captureIds":{"type":"array","items":{"type":"string"}}},"required":["orderIds","captureIds"],"additionalProperties":false}},"required":["signed","recorded"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"verdict":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean","const":true},"orderId":{"type":"string"},"captureId":{"type":"string"},"currency":{"type":"string"},"totalMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","name","quantity"],"additionalProperties":false}},"paidAt":{"type":"string"}},"required":["ok","orderId","captureId","currency","totalMinor","items"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","const":false},"reason":{"type":"string","enum":["not_paid","wrong_payee","amount_mismatch","currency_mismatch","wrong_stall","already_recorded"]},"message":{"type":"string"},"recordedAt":{"type":"string"}},"required":["ok","reason","message"],"additionalProperties":false}]}},"required":["verdict"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/invoices":{"post":{"tags":["Invoicing"],"summary":"Create, send and QR a PayPal invoice","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"currency":{"type":"string","minLength":3,"maxLength":3},"businessName":{"type":"string"},"recipient":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"givenName":{"type":"string"},"surname":{"type":"string"},"businessName":{"type":"string"}},"required":["email"],"additionalProperties":false},"items":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"quantity":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"unitMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["name","quantity","unitMinor"],"additionalProperties":false}},"dueDate":{"type":"string"},"memo":{"type":"string"},"note":{"type":"string"}},"required":["currency","recipient","items"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"totalMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"payerUrl":{"type":"string"},"qrPng":{"type":"string"},"owner":{"type":"string"}},"required":["id","status","totalMinor","owner"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/plans":{"post":{"tags":["Subscriptions"],"summary":"Create a Catalog Product + active Billing Plan","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string","minLength":3,"maxLength":3},"priceMinor":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"interval":{"type":"string","enum":["week","month","year"]},"trialCycles":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["name","currency","priceMinor","interval"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"productId":{"type":"string"},"planId":{"type":"string"},"status":{"type":"string"}},"required":["productId","planId","status"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/subscriptions":{"post":{"tags":["Subscriptions"],"summary":"Create a subscription for approval, or read its status","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"planId":{"type":"string"}},"required":["planId"],"additionalProperties":false},{"type":"object","properties":{"subscriptionId":{"type":"string"}},"required":["subscriptionId"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"subscriptionId":{"type":"string"},"status":{"type":"string"}},"required":["subscriptionId","status"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/ai/concierge":{"post":{"tags":["AI"],"summary":"Buyer concierge: request → cart proposal from this stall's items only","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"signed":{"type":"string","description":"Signed stall link payload: `<lz-string>.<HMAC>` (the part after `/s#`)"},"ask":{"type":"string","maxLength":300}},"required":["signed","ask"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"qty":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"note":{"type":"string"}},"required":["id","qty"],"additionalProperties":false}},"explanation":{"type":"string"}},"required":["lines","explanation"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}},"/api/v1/ai/penny":{"post":{"tags":["AI"],"summary":"Penny, the seller's clerk","description":"Gemini function calling over PayPal tools. Mutating tools return proposals only; they execute through the routes above after the seller approves.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","model"]},"text":{"type":"string"}},"required":["role","text"],"additionalProperties":false}},"context":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["messages","context"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"reply":{"type":"string"},"proposals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"tool":{"type":"string"},"args":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","tool","args"],"additionalProperties":false}}},"required":["reply","proposals"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"debugId":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false},"receipts":{"type":"array","items":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"at":{"type":"string"},"service":{"type":"string","enum":["paypal","gemini","channel3"]},"method":{"type":"string"},"path":{"type":"string"},"status":{"type":"number"},"ok":{"type":"boolean"},"debugId":{"type":"string"},"requestId":{"type":"string"},"ms":{"type":"number"}},"required":["id","at","service","method","path","status","ok","ms"],"additionalProperties":false}}}}}}}}}}}}